91 lines
5.2 KiB
Markdown
91 lines
5.2 KiB
Markdown
---
|
|
type: Decision
|
|
title: Dev container shape
|
|
description: 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.
|
|
tags: [decision, docker, nuxt, development]
|
|
status: stable
|
|
generated: { by: opencode/deepseek-v4.1-flash, at: 2026-10-18T12:41:52Z }
|
|
verified: { by: human:noel, at: 2026-10-18T12:41:52Z }
|
|
sources:
|
|
- id: node-image
|
|
resource: docker.io/library/node:26-slim@sha256:d62f13676d530f7edf97782729df69713c8ccfe6631e7f62f9ccab65968719a8
|
|
title: 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
|
|
|
|
```dockerfile
|
|
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.
|