--- type: Decision title: Production image shape description: The production Dockerfile is a runnable Node server for the SSR app - multi-stage, digest-pinned base, non-root, healthchecked. tags: [decision, docker, nuxt, production] status: stable generated: { by: opencode-go/glm-5.3-flash, at: 2026-10-18T19:10:00Z } verified: { by: human:noel, at: not yet } sources: - id: dockerfile resource: Dockerfile title: Production Dockerfile - id: droast resource: .gitea/workflows/pr-checker.yml title: Dockerfile lint job (droast) --- # Decision `Dockerfile` builds the production image as a **runnable Node server**: * Stage `build`: manifests first, `pnpm install --frozen-lockfile --ignore-scripts`, then the full source, then `pnpm build` - Nitro emits a self-contained `.output/server/index.mjs` with its traced dependencies. * Stage runtime: only `.output` is copied (chowned to `node`), the process runs as the image's non-root `node` user, the base image is the same digest-pinned `node:26-slim` as the dev container, and a `HEALTHCHECK` (node's own fetch, no curl in slim) polls the root path. This answers the previously open question "runnable Node server, or static files embedded in the gateway". The static-in-gateway plan recorded in the sibling `OKF_CV_Website` bundle predates the SSR reality of this repository: the gateway must now **proxy to this server** instead of embedding `.output/public/`. That sibling decision needs updating; the compose wiring is still open. # The arm64 digest lesson (2026-10-31) The first real release (`v1.5.0`, `v1.5.1`) failed at `Build image` after one second: the pinned `sha256:18f03e4b...` was the **linux/amd64 platform manifest**, not the multi-platform index, so `docker build --platform linux/arm64` on the arm64 runner found no arm64 entry. The base is now pinned to the OCI **index** digest (`sha256:e4db4c91...`, contains linux/amd64 and linux/arm64/v8). Rule: a digest pin for a multi-arch image must be the index digest; `docker buildx imagetools inspect` prints both, and the platform manifests carry a `Platform:` line. # Why `--ignore-scripts` The `postinstall` script (`nuxt prepare`) runs before the source is copied and would fail. `nuxt build` prepares everything it needs itself. Native binaries (esbuild, unrs-resolver) come from platform-specific optional packages, not install scripts, so skipping scripts loses nothing. # Verified (measured, 2026-10-18) * `docker build` on x86_64: full build succeeds in-image ("Build complete"). * `docker run`: HTTP 200 on `/` (28 KB page), process runs as `uid=1000(node)`, healthcheck reports `healthy`. * droast 1.7.0 (sha-verified): 0 errors; one accepted DF007 warning on `COPY . .` - that line *is* the source-last layer design. * arm64 correctness rests on the multi-arch digest pin (proven in CI for the dev container); the image build itself has only run on x86_64. # Revisit when * The gateway/compose stack is assembled (proxy target, port, network). * A `go` preset or full-static `nuxt generate` becomes preferable.