What the agent does
The agent reads the scripts before writing a single RUN, because in this kind of app the build script does things an image build cannot. In an app laid out like trpc/examples-next-prisma-starter, package.json has next ^15.5.25, react 19, @trpc/server, @trpc/client, @trpc/next and @trpc/react-query on the canary tag, @prisma/client and prisma ^6.7.0, zod 4, superjson and @tanstack/react-query 5, with vitest, @playwright/test, tailwindcss 3 and tsx as dev dependencies. Its scripts are the problem: postinstall is pnpm generate, which is prisma generate, so the Prisma schema has to be present before dependencies are installed; prebuild is run-s generate migrate, where migrate is prisma migrate deploy, so pnpm build tries to reach a database before next build; and .npmrc sets enable-pre-post-scripts=true so pnpm runs both hooks. There is no pnpm-lock.yaml and no packageManager field. .github/workflows/main.yml runs on Node 22 with a postgres service, pnpm/action-setup, pnpm prebuild, pnpm build, Playwright and vitest.
Two files decide what the image needs at build time and at run time. src/server/env.ts parses process.env with a zod schema that requires DATABASE_URL to be a URL and NODE_ENV to be one of development, test or production, and throws otherwise; next.config.ts imports it, so next build fails without a well-formed DATABASE_URL even though the build never connects. src/server/prisma.ts creates one PrismaClient and logs queries only in development. prisma/schema.prisma uses the postgres provider and one Post model, with four migrations under prisma/migrations/ and a migration_lock.toml for postgresql; prisma/seed.ts upserts one post through tsx. src/server/routers/_app.ts exposes a healthcheck query that returns yay!, reachable at /api/trpc/healthcheck through src/pages/api/trpc/[trpc].ts. The committed .env holds a local postgresql://postgres:@localhost:5432/... URL, and .gitignore excludes .next, node_modules, coverage and playwright/test-results but not .env.
The Dockerfile the agent writes has three stages on node:22-alpine, matching the Node the workflow uses. The deps stage copies package.json, .npmrc and prisma/ first, pins pnpm with corepack enable and corepack prepare at a named version, and runs pnpm install, which triggers postinstall and generates the client while the schema is already in place; it also installs openssl, which Prisma 6's engine for Alpine links against. The build stage copies the source, sets ARG DATABASE_URL=postgresql://build:build@localhost:5432/build and NODE_ENV=production so env.ts accepts the environment, and runs pnpm exec next build directly rather than pnpm build, which skips the prebuild hook and therefore the migrate deploy that has no database to reach. For that build to be small, next.config.ts gains output: 'standalone', so .next/standalone holds server.js and the pruned node_modules; the runner stage copies that directory, .next/static, public, prisma/ and the prisma CLI's output, runs as the image's node user, exposes 3000, and sets HOSTNAME=0.0.0.0. Its entrypoint runs prisma migrate deploy against the real DATABASE_URL, then node server.js. A HEALTHCHECK calls /api/trpc/healthcheck with wget. .dockerignore lists node_modules, .next, .git, playwright/test-results, coverage and .env, so the committed local URL never enters a layer.
The sandbox has no Docker, so the agent installs it with sudo apt-get install -y docker.io and starts dockerd before docker build -t app .. It starts a postgres container with docker run, runs the image with DATABASE_URL pointing at it, watches the entrypoint apply the four migrations, then requests /api/trpc/healthcheck and / with curl and reads the status and the JSON. It runs docker image ls to record the image size the standalone output produced, and pnpm tsc and pnpm lint on the host to confirm the one-line next.config.ts change passes the workflow's Check types and lint steps. It does not add a lockfile, but the pull request says that without one every image build resolves canary and ^ ranges afresh, and recommends committing pnpm-lock.yaml and a packageManager field.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a Dockerfile to this tRPC Next.js app. Read package.json, .npmrc, .env, .gitignore, next.config.ts, src/server/env.ts, src/server/prisma.ts, prisma/schema.prisma, the prisma/migrations directory, src/server/routers/_app.ts and .github/workflows/main.yml first, and note which scripts the postinstall and prebuild hooks run. Write a three-stage Dockerfile on node:22-alpine: a deps stage that copies package.json, .npmrc and prisma/ before pnpm install so the postinstall prisma generate works, pins pnpm with corepack and installs openssl; a build stage that passes a placeholder DATABASE_URL build argument and NODE_ENV=production for the env schema and runs next build directly so the prebuild migrate step is skipped; and a runner stage from the Next.js standalone output as the node user with prisma migrate deploy in the entrypoint before node server.js and a HEALTHCHECK on /api/trpc/healthcheck. Add output standalone to next.config.ts and a .dockerignore that excludes .env, node_modules, .next and test results. Install Docker in the sandbox, build the image, start a postgres container, run the image against it, show the migrations applying and the healthcheck and home page responses, run pnpm tsc and pnpm lint, and open a pull request. Do not commit a lockfile, but say in the pull request why one should be added.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds Dockerfile, .dockerignore and an entrypoint script, and changes one line of next.config.ts. Its description shows the docker build tail, the entrypoint's migration log, the curl responses for the health check and the home page, the image size from docker image ls, and the tsc and lint output.
The Testing workflow runs on the pull request as before, Build + E2E tests and Unit tests + typecheck, both with pnpm build against their Postgres service; the standalone setting changes where next build writes, not what the Playwright and vitest runs see. The run's record holds the container session that the workflow does not reproduce.
Before merging, a reviewer decides which pnpm version to pin and whether to commit the lockfile the pull request asks for, whether migrations should run in the entrypoint or as a separate release step before the new image starts, and whether the seed in prisma/seed.ts belongs in any environment the image reaches.
Run it on every tRPC service that needs an image
A team that runs several tRPC services starts one run per repository from its own server: a POST /o/{org}/sessions each, with this prompt as input, the repository in resources and a request_id that is a UUID v5 of the repository's full name so a retried call returns the run already started. Each run reads its own scripts, so a service whose build script has no prebuild hook gets a plain pnpm build, one with a lockfile gets --frozen-lockfile, and one on the App Router gets the same standalone stage with its own output layout.
A team that tracks platform work in Linear runs the same prompt from an automation in the Project with a linear trigger on issues labelled docker. The trigger adds the issue after the prompt, so an issue that names the registry, the base image policy or the port the platform expects reaches the agent with those details, and the pull request links back to it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A Dockerfile is right only when the image builds and the container answers, and this app has three ways to get that wrong before the first request: a postinstall that needs the schema, a prebuild that needs a database, and a config that refuses to load without a URL. The agent finds each by reading the scripts, then proves the fix by building the image and running it against a real Postgres in its own sandbox, with the migration log and the curl output kept in the run.
Installing Docker, pulling base images and running a database is slow work that does not belong on a laptop in the middle of something else, and the same prompt runs across every service at once, each in its own sandbox with its own pull request.
Frequently asked questions
Why not run pnpm build in the Dockerfile?
Because prebuild runs prisma migrate deploy, which needs a reachable database, and an image build has none. The Dockerfile runs next build directly and leaves migrations to the entrypoint, where DATABASE_URL is real. prisma generate still happens, through the postinstall hook during pnpm install.
Where do migrations run?
In the entrypoint, before node server.js, with prisma migrate deploy, which applies the four migrations under prisma/migrations and refuses to run anything else. The pull request names the alternative, a one-off job before the new image starts, for teams that run more than one replica and do not want each one racing to migrate.
Why node:22-alpine with openssl installed?
Node 22 is what .github/workflows/main.yml tests on. Prisma 6's query engine for Alpine is built against OpenSSL 3, which the base image does not ship, so the deps and runner stages add the openssl package; without it the client fails at the first query rather than at build.
Does the committed .env end up in the image?
No. .dockerignore excludes it, and the build passes a placeholder DATABASE_URL as a build argument only so src/server/env.ts can parse the environment. The container reads the real URL from its own environment at start.
Why standalone output?
output: 'standalone' makes next build write .next/standalone with server.js and only the packages the server needs, so the runner stage copies that directory instead of the full node_modules with Playwright, vitest and Tailwind in it. The .next/static and public directories are copied beside it because the standalone server does not include them.
More tRPC jobs
The same job on other stacks
- Add a Dockerfile to an AdonisJS App (AdonisJS)
- Add a Dockerfile to an aiohttp App (aiohttp)
- Add a Dockerfile to a Blazor Web App (Blazor)