The image contains the standalone server and nothing else: the build runs natively in CI, the Dockerfile only copies output, and the container proves its own readiness and leaves within a second when asked. Those three properties make rolling updates safe and images small; everything below enforces them.
Hard rules: never break these
- Build on the runner, never in Docker and never on the server. Registry installs inside container builds hang; the server has no spare CPU. The Dockerfile copies
.next/standalone,.next/staticandpubliconly. output: "standalone"with noNEXT_DIST_DIRoverride at build time, so the output lands in.next.- Public env is baked at build time. Every
NEXT_PUBLIC_*value and the/apirewrite destination are inlined; set them in the workflow beforenext buildand verify them in.next/routes-manifest.json. Only server-only runtime secrets go to Coolify. - The health route lives outside anything proxied or localised.
/healthzsits besideapp/api, not under it, and the proxy matcher excludes it. - Exit within a second on SIGTERM. Next waits for in-flight requests; a long-lived stream (SSE, a WebSocket) keeps the old container alive for the whole grace period while the proxy still routes to it.
- No
latesttags, no root user, no host ports.
Step 1: Audit the app
grep -n "output\|distDir\|rewrites\|headers" next.config.*
grep -rn "process.env" app components lib proxy.ts middleware.ts 2>/dev/null | grep -v NEXT_PUBLIC_ | grep -v node_modules
grep -rln "next/image" app components | head
Classify every env read as build-time (NEXT_PUBLIC_*, anything in next.config) or runtime (read on the server at request time). Note whether next/image optimises local images: sharp is traced into the standalone output automatically when installed, so the runtime image needs no extra packages, but the smoke test must prove it.
Step 2: Add the runtime files
Copy and adapt, from templates/:
| File | Purpose |
|---|---|
| Dockerfile | node:<major>-slim, copies the three output folders plus the two scripts, USER node, HEALTHCHECK on the probe, exit deadline preloaded |
| .dockerignore | an allowlist: everything out except the build output |
| healthcheck.js | fetches /healthz on 127.0.0.1 with a 4 s timeout, exit 0 or 1 |
| shutdown.cjs | exits half a second after SIGTERM or SIGINT; NEXT_MANUAL_SIG_HANDLE=true in the Dockerfile disables Next's own wait |
| healthz route | app/healthz/route.ts, static, Cache-Control: no-store |
In next.config.*: output: "standalone", poweredByHeader: false, and send Strict-Transport-Security yourself (a platform edge used to add it; a self-hosted proxy does not). In the proxy or middleware matcher add healthz to the exclusions: "/((?!api|healthz|_next|.*\\..*).*)". Add the new files to knip or lint ignores if the repo gates unused files.
Step 3: Build and verify the baked values locally
NEXT_PUBLIC_API_BASE_URL=https://api.example.com pnpm build
jq -r '.rewrites.afterFiles[]?, .rewrites.beforeFiles[]?, .rewrites.fallback[]? | select(.source == "/api/:path*") | .destination' .next/routes-manifest.json
ls .next/standalone/node_modules/.pnpm | grep -c sharp # non-zero when next/image is used
docker build -t app:local . && docker image inspect app:local --format '{{.Size}}'
Step 4: Smoke-test the image the way CI will
Run the container with the memory limit and check, in order: Docker reports healthy within 30 s; id -u is not 0; /healthz 200; a page per locale (dir="rtl" present where expected); an unauthenticated protected route redirects to login; security headers present and x-powered-by absent; /_next/image?url=... returns image/* when the app optimises images; docker stop -t 10 returns in about a second. Write curl output to files before grepping: grep -q closes the pipe early and fails curl under pipefail. The exact script is the image job in the ghcr-coolify-pipeline skill.
Step 5: Hand over
Report the image size, the verified rewrite destination, the smoke results, which env values are baked and which are runtime, and anything the app does that the probe does not cover (background jobs, streams). The Coolify side is the coolify-image-app skill; the general container rules the dockerfile-best-practices skill.
