Files
CV_Site_Nuxt/OKF_Nuxt/decisions/dev-container-shape.md
T
Noel Sabia bb0ab03a97
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / ESLint (pull_request) Successful in 35s
PR Check / Typecheck (pull_request) Successful in 38s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 5s
PR Check / Dependency audit (pull_request) Failing after 8s
PR Check / Dockerfile lint (droast) (pull_request) Failing after 5s
PR Check / AI code review (opencode) (pull_request) Canceled after 16s
docs: add OKF_Nuxt decision records and log
2026-10-18 18:09:45 +02:00

4.4 KiB

type, title, description, tags, status, generated, verified, sources
type title description tags status generated verified sources
Decision Dev container shape The Nuxt source is bind-mounted into a container that already holds the toolchain and the dependencies, and the dev server runs as the image's node user.
decision
docker
nuxt
development
stable
by at
opencode/deepseek-v4.1-flash 2026-10-18T12:41:52Z
by at
human:noel 2026-10-18T12:41:52Z
id resource title
node-image docker.io/library/node:26-slim@sha256:d62f13676d530f7edf97782729df69713c8ccfe6631e7f62f9ccab65968719a8 Node 26 slim base image

Decision

Dockerfile.dev is a prepared runtime, not a build of the application. It holds the toolchain and the installed dependencies. The source arrives at run time as a bind mount, and the container runs the Nuxt dev server. There is no COPY . . and no build step in the dev image.

Why

The alternative is to copy the source into the image and rebuild on every edit, which makes each edit cost a full image build. With the source mounted, an edit is a file write and the dev server's own reload does the rest. The image stops being something you rebuild and becomes something you run.

Shape

FROM node:26-slim@sha256:d62f13676d530f7edf97782729df69713c8ccfe6631e7f62f9ccab65968719a8

# Node no longer bundles pnpm (corepack and pnpm are both absent from this
# image), so install it. First instruction, so later changes reuse the layer.
RUN npm install -g pnpm@11.26.0

# The bind mount lands here at run time, owned by the image's `node` user.
# Its uid 1000 matches the host uid, so files it writes stay yours.
RUN mkdir -p /app && chown node:node /app
USER node
WORKDIR /app

# Manifests only: this layer and the install below survive every source edit
# and re-run only when a manifest changes.
COPY --chown=node:node package.json pnpm-lock.yaml pnpm-workspace.yaml ./
RUN pnpm install --frozen-lockfile

EXPOSE 3000
CMD ["pnpm", "run", "dev", "--", "--host", "0.0.0.0"]
Piece Choice Why
Base image node:26-slim, pinned by digest The digest makes the build reproducible; the checked digest resolves to Node v26.12.0.
pnpm Installed explicitly, pinned to 11.26.0 Neither corepack nor pnpm is present in the image. The pin matches the host version, so the same lockfile format is used on both sides.
User The image's node user, uid 1000 The host uid is also 1000. Files the dev server writes into the mounted repo stay owned by Noel instead of becoming root-owned. This is not a security measure.
node_modules Anonymous volume at /app/node_modules The bind mount replaces all of /app, which would otherwise hide the dependencies installed in the image.
Command pnpm run dev -- --host 0.0.0.0 The dev server would otherwise listen on localhost inside the container and be unreachable from the host. The -- passes the flag through pnpm to the dev script rather than letting pnpm interpret it.

Evidence

Command Result
docker build -f Dockerfile.dev -t cv-site-nuxt:dev . Builds. esbuild's postinstall ran, so the allowBuilds setting in pnpm-workspace.yaml is honoured. pnpm install reported "Lockfile passes supply-chain policies (593 entries)".
Same build run a second time Every layer CACHED.
docker run -v <repo>:/app -v /app/node_modules -p 13000:3000 cv-site-nuxt:dev HTTP 200 from the host after 4 seconds; server reported "Ready in 2.02s".
ls -A /app/node_modules inside that container 9 entries (nuxt, vue, vue-router, .pnpm, …) — the anonymous volume is populated from the image rather than starting empty.
Ownership of .nuxt on the host after that run noel:noel, so the uid-1000 choice holds.

Side effects on the host

The bind mount means Docker resolves the mount point for the node_modules volume through the host directory, so a first run leaves an empty, root-owned node_modules in the repository. It deletes without sudo, and if the directory already exists the ownership is left alone — a pre-created directory stays noel:noel.

Not verified

  • docker compose up --build -V as the remedy for a stale anonymous volume after a dependency change was not tested.
  • That a root-owned node_modules breaks a host-side pnpm install is inferred from the permissions, not measured.

Revisit when

  • The container runs on a machine whose uid is not 1000.
  • The dev server needs a host port other than 3000.