Files
Noel Sabia 7981575f86 fix(docker): pin the multi-platform base image index digest
The previous pin was the linux/amd64 platform manifest, so the arm64
runner failed instantly with 'no matching manifest for linux/arm64'.
Pin the OCI index digest that contains amd64 and arm64/v8.
2026-10-31 21:08:39 +01:00

3.0 KiB

type, title, description, tags, status, generated, verified, sources
type title description tags status generated verified sources
Decision Production image shape The production Dockerfile is a runnable Node server for the SSR app - multi-stage, digest-pinned base, non-root, healthchecked.
decision
docker
nuxt
production
stable
by at
opencode-go/glm-5.3-flash 2026-10-18T19:10:00Z
by at
human:noel not yet
id resource title
dockerfile Dockerfile Production Dockerfile
id resource title
droast .gitea/workflows/pr-checker.yml 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.