dockerfile-best-practices

A production image contains exactly what the process needs to run, built reproducibly, running as a non-root user, and stopping cleanly when asked. Everything below follows from those four properties.

Structure: multi-stage

# syntax=docker/dockerfile:1.7
FROM node:22.11-bookworm-slim AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile --prod=false

FROM deps AS build
COPY . .
RUN pnpm build && pnpm prune --prod

FROM node:22.11-bookworm-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
RUN groupadd -r app && useradd -r -g app -d /app app
COPY --from=build --chown=app:app /app/node_modules ./node_modules
COPY --from=build --chown=app:app /app/dist ./dist
COPY --chown=app:app package.json ./
USER app
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s CMD node dist/healthcheck.js
ENTRYPOINT ["node", "dist/server.js"]

Build stages hold compilers and dev dependencies; the runtime stage copies artifacts only.

Rules

Base images

• Pin to a specific version tag (22.11-bookworm-slim), and for reproducible builds pin the digest (@sha256:...) with a tool (Renovate, Dependabot) to bump it.
• Prefer -slim or distroless over alpine for glibc-dependent runtimes (Node native modules, Python wheels); alpine for Go static binaries is fine.
• One process per container; no supervisord.

Layers and cache

• Order from least to most frequently changed: base, system packages, dependency manifests, dependency install, source, build. Copy lockfiles before source so dependency layers cache.
• RUN steps combined with && and cleanup in the same step (apt-get install ... && rm -rf /var/lib/apt/lists/*); a later rm does not shrink an earlier layer.
• .dockerignore with .git, node_modules, build output, .env*, tests, docs; without it the build context and the cache invalidation are both wrong.
• BuildKit cache mounts for package managers: RUN --mount=type=cache,target=/root/.npm npm ci.

Security

• USER non-root before ENTRYPOINT; files copied with --chown. Bind to a port above 1024.
• No secrets in ENV, ARG, or copied files; they persist in layers and history. Use RUN --mount=type=secret,id=npmrc for build-time secrets and runtime injection (env at run, mounted files, a secrets manager) for the rest.
• Read-only root filesystem where possible (--read-only with tmpfs for /tmp); drop capabilities; no --privileged.
• Scan (docker scout, trivy image) in CI; fail on critical CVEs with a fix available.

Runtime behaviour

• ENTRYPOINT in exec form (JSON array) so the process is PID 1 and receives signals; CMD for default arguments only. Shell form wraps in sh -c and swallows SIGTERM.
• The application handles SIGTERM: stop accepting, drain in-flight requests, close connections, exit within the orchestrator's grace period (default 30 s). If the runtime cannot (some shell scripts), use tini as the init (ENTRYPOINT ["tini", "--", ...]).
• HEALTHCHECK (or the orchestrator's probe) hits a cheap endpoint that checks dependencies the process needs; readiness separate from liveness in Kubernetes.
• Logs to stdout/stderr, unbuffered (PYTHONUNBUFFERED=1); no log files in the container.
• EXPOSE documents the port; it does not publish it.

Size

• Check with docker image ls and dive. Typical targets: Go static under 20 MB (distroless/static), Node under 200 MB, Python under 250 MB.
• Do not install dev dependencies, docs, or test files in the runtime stage.

Language notes

• Node: npm ci / pnpm install --frozen-lockfile; NODE_ENV=production; node directly, not npm start (npm does not forward signals); set --max-old-space-size from the container limit or use a version that respects cgroups.
• Python: python:3.12-slim; pip install --no-cache-dir -r requirements.txt (or uv sync --frozen) in a build stage into a venv copied to runtime; PYTHONDONTWRITEBYTECODE=1; run with gunicorn/uvicorn directly; --workers from CPU limit.
• Go: build stage golang:1.23, CGO_ENABLED=0 go build -ldflags="-s -w", runtime gcr.io/distroless/static-debian12:nonroot, copy the binary and CA certs.
• Java: build with the JDK, run on a JRE (eclipse-temurin:21-jre), layered jar (spring-boot:build-image or jarmode=layertools), -XX:MaxRAMPercentage=75.

Compose for local development

compose.yaml with the service built from the Dockerfile's build stage (target: build), source bind-mounted for hot reload, dependencies (db, cache) with named volumes and health checks, depends_on with condition: service_healthy, env from .env (git-ignored) with an .env.example committed.

Review checklist

Pinned base; multi-stage; lockfile copied before source; .dockerignore; non-root; exec-form ENTRYPOINT; signals handled; health check; no secrets in layers (docker history shows none); scan clean; size within target; builds reproducibly twice with the same digest.