# Add a Dockerfile to a tRPC Next.js App

Yes. An agent writes a multi-stage Dockerfile for your tRPC and Prisma Next.js app with a standalone build and migrations at start, runs the image, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-dockerfile/trpc/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Show Zod Validation Errors From tRPC Under Each Form Field](https://getrush.ai/run/add-form-validation-errors/trpc/)
- [Add Health Check Endpoints to a tRPC and Next.js App](https://getrush.ai/run/add-health-checks/trpc/)
- [Add ESLint and Prettier Checks to CI for a tRPC App](https://getrush.ai/run/add-lint-to-ci/trpc/)

## The same job on other stacks

- [Add a Dockerfile to an AdonisJS App](https://getrush.ai/run/add-dockerfile/adonisjs/)
- [Add a Dockerfile to an aiohttp App](https://getrush.ai/run/add-dockerfile/aiohttp/)
- [Add a Dockerfile to a Blazor Web App](https://getrush.ai/run/add-dockerfile/blazor/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
