docker

Docker: Production Image and Compose Rules

From production, not defaults. Claude's Dockerfiles tend to be wrong in the same few ways. Fix them here.

Dockerfile

• Multi-stage builds, always. Build in a stage that has the compilers and dev dependencies, then COPY --from=build only the artifacts into a slim runtime stage. The runtime image carries no build tools, which cuts size hard (a real build went from ~2GB to ~200MB) and removes a pile of CVEs.

FROM node:22 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-slim AS runtime
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
ENTRYPOINT ["node", "dist/server.js"]

• Order layers by how often they change: stable first, source last. Docker caches each layer and rebuilds every layer after the first one whose inputs changed. So copy the dependency manifest and install deps BEFORE copying source: COPY package*.json ./ then RUN npm ci then COPY . .. Copy source first and a one-line code change reinstalls every dependency, every build.

• The runtime command is ENTRYPOINT/CMD in exec form, never RUN. RUN executes at build time; the container's process belongs in ENTRYPOINT ["node","server.js"] (a JSON array). Use exec form, not shell form (ENTRYPOINT node server.js): shell form runs your app under /bin/sh -c, so sh is PID 1, it swallows SIGTERM, and your app never shuts down gracefully (Docker waits out the grace period then SIGKILLs it) and its exit code is lost. Exec form makes your process PID 1 so signals and exit codes propagate. ENTRYPOINT for the executable, CMD for default args.

• Pin base image versions. FROM node:22.3.0-slim, not node:latest. latest makes builds non-reproducible and shifts under you silently. Pin a tag (or a digest for full reproducibility), and expose it as an ARG so it's easy to bump deliberately.

• Add a .dockerignore. Exclude node_modules, .git, .env, dist, and local junk. Without it the whole directory ships as build context (slow), busts the cache on unrelated changes, and can bake a stale node_modules or a secret file into the image.