Files
CV_Site_Nuxt/OKF_Nuxt/decisions/dev-container-shape.md
T

5.2 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. The volume is a snapshot copied from the image when the container is first created; it never refreshes afterwards.
Compose env CI: "true" pnpm 11 verifies dependency state before every pnpm run (runDepsStatusCheck). When the state is stale it wants to purge node_modules, and with no TTY under compose it aborts (ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY). CI mode replaces the prompt with a non-interactive reinstall per the mounted lockfile.
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.
docker compose up after the mounted manifests drifted from the volume's snapshot Exit 1: ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY — pnpm's pre-run check found the drift, wanted to purge node_modules, and had no TTY to ask.
docker compose up -d --build -V with CI: "true" in the compose file Builds, renews the stale anonymous volume, server reports "Ready in 2.62s"; no pnpm prompt or abort.

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

  • 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.