The image carries compiled code, production dependencies and the migrations, applies pending migrations before it listens, and reports ready only when it can reach its database. Because a rolling update runs the new container beside the old one, every migration must be compatible with the previous release: expand, migrate, contract.
Hard rules: never break these
- Build natively on the runner, copy artifacts into the image. No
pnpm installinside Docker, no build on the server. - Migrations run in the entrypoint, with
prisma migrate deploy, nevermigrate dev,db pushormigrate reset. The entrypoint applies them and then execs the server, so a failed migration stops the container before it takes traffic. - Applied migrations are immutable. CI rejects any edit, rename or deletion under
prisma/migrations; a mistake gets a new migration. - Every release starts from a restore-verified backup. The deploy job takes one before touching the tag (the
vps-ops-toolkitskill provides it). - Readiness means the database answers. The probe calls the readiness route that runs a trivial query, so a container that cannot reach Postgres never takes traffic.
- Non-root user, no host ports, a stop that finishes within 10 s.
Step 1: Audit the API
cat package.json | jq '{scripts, engines, packageManager}'
ls prisma prisma/migrations | head; cat prisma.config.ts 2>/dev/null
grep -rn "process.env" src/config | head -40
grep -rn "health" src/routes src/modules 2>/dev/null | head
List the runtime variables the app validates at boot (database URL, secrets, allowed origins, feature switches) and which have safe values for a smoke test. Note native or downloaded dependencies (a headless browser, image libraries): they must be fetched on the runner and copied in, with their shared libraries installed in the image.
Step 2: Add the runtime files
| File | Purpose |
|---|---|
| Dockerfile | node:<major>-slim, copies node_modules, dist, prisma, config and entrypoint; USER node; HEALTHCHECK on the probe |
| docker-entrypoint.sh | prisma migrate deploy when migrations exist, then exec node dist/server.js |
| healthcheck.ts | compiled with the app; fetches the readiness route with a 4 s timeout |
| .dockerignore | keeps sources, tests, docs and env files out; node_modules and dist deliberately stay in |
Readiness route: GET <prefix>/health/ready runs SELECT 1 through Prisma and answers {status: "ok", checks: {database: "up"}} with 200, or 503. Liveness GET <prefix>/health answers without touching the database.
Step 3: Build the context on the runner
In this order, because an in-place --prod install leaves dev tooling in pnpm's store:
pnpm install --frozen-lockfile --ignore-scripts
pnpm run build # tsc -p tsconfig.build.json, prisma generate
rm -rf node_modules && pnpm install --prod --frozen-lockfile --ignore-scripts
ls node_modules/.pnpm/@prisma+engines@*/node_modules/@prisma/engines/schema-engine-* # the migrate engine must be present
The schema engine is downloaded by the Prisma CLI on first use; the container cannot download it at start as an unprivileged user over root-owned files, so prove it exists before docker build.
Step 4: Smoke-test against a throwaway Postgres
In CI, a postgres service on a non-default port; locally, docker run -d -p 5433:5432 -e POSTGRES_PASSWORD=... postgres:17-alpine. Start the image with --network host, a DATABASE_URL pointing at it, and safe values for every required variable. Loop docker exec <c> node dist/healthcheck.js until it exits 0 (migrations applied, database reachable), check id -un is node, then docker stop -t 30 must return within 10 s with exit code 0. The full script is the image job in the ghcr-coolify-pipeline skill; the migration guard and the migrate diff --exit-code schema check belong in its quality job.
Step 5: Hand over
Report the image size, the migration state the smoke test reached, the list of runtime variables Coolify must carry (names only), and any compatibility note for the next release (a column added now, removed later). Migration safety itself is the db-migration-safety skill.
