Containers

Purpose

Build container images that are small, cached effectively, and safe to run — not a 1.2 GB image running as root that rebuilds from scratch every time a source file changes.

When to Use

• Writing or reviewing a Dockerfile.
• Reducing image size or build time.
• Debugging a container that exits, hangs, or behaves differently from local development.
• Hardening images before a security review.

Capabilities

• Multi-stage builds and build-cache optimization.
• Base-image selection: distroless, Alpine, slim, and their trade-offs.
• Non-root users, read-only filesystems, and dropped capabilities.
• Signal handling and PID 1 semantics.
• Image scanning and SBOM generation.

Inputs

• The application, its runtime, and its build steps.
• The target platform (including whether ARM builds are required).
• Security and compliance requirements.

Outputs

• A multi-stage Dockerfile with an ordered, cache-friendly layer sequence.
• An image running as a non-root user, with no build tooling inside.
• A scan report with no critical vulnerabilities in the final image.

Workflow

1. Order layers by change frequency — Dependency manifests first, dependency install second, source code last. Copying the source before installing dependencies invalidates the cache on every code change.
2. Build in stages — A build stage with compilers and dev dependencies; a runtime stage containing only the artifact and its runtime. The compiler must not ship to production.
3. Run as non-root — Create a user in the image and USER it. A container running as root that is compromised is a root process on the node.
4. Handle signals — Use exec form (CMD ["node", "server.js"]), not shell form. Shell form makes /bin/sh PID 1, which does not forward SIGTERM, so your graceful shutdown never runs.
5. Scan and pin — Pin the base image by digest, scan the final image, and rebuild regularly to pick up base-image patches.

Best Practices

• COPY package*.json ./ then RUN npm ci then COPY . . — in that order. This is the single most impactful Dockerfile optimization and it is routinely written backwards.
• Shell-form CMD means your process is not PID 1 and will not receive SIGTERM. Every "why doesn't my container shut down gracefully" question has this answer.
• Distroless or scratch images have no shell, which is excellent for security and inconvenient for debugging. Use kubectl debug or a debug variant tag.
• A .dockerignore that excludes .git, node_modules, and build output can cut the build context from hundreds of megabytes to a few.
• latest is not a version. Pin by digest for reproducibility, or at minimum by an immutable tag.
• Secrets passed as build args are baked into the image layers and recoverable. Use BuildKit secret mounts.

Examples

Multi-stage build with correct caching, a non-root user, and exec-form CMD:

# syntax=docker/dockerfile:1

# ---- build stage: has the toolchain, ships nothing ----
FROM node:22-bookworm-slim AS build
WORKDIR /app

COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci                                   # cached unless the lockfile changes

COPY . .                                     # source last: code changes do not
RUN npm run build                            # invalidate the dependency layer

# ---- runtime stage: no compiler, no dev dependencies, no shell needed ----
FROM gcr.io/distroless/nodejs22-debian12@sha256:4c2e...
WORKDIR /app

COPY --from=build --chown=nonroot:nonroot /app/dist ./dist
COPY --from=build --chown=nonroot:nonroot /app/node_modules ./node_modules

USER nonroot                                 # never root
EXPOSE 8080
CMD ["dist/server.js"]                       # exec form: the process is PID 1

Secret at build time without baking it into a layer:

RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci

The token is available during the command and absent from the resulting layer. A ARG NPM_TOKEN would be permanently recoverable with docker history.

Notes

• docker history <image> shows every layer and the command that created it. Anything a build arg touched is visible there — which is why build args are not a secrets mechanism.
• Alpine uses musl instead of glibc. It is smaller, but it has caused real production bugs with DNS resolution and with native Node modules. slim variants are usually the safer default.
• A read-only root filesystem (readOnlyRootFilesystem: true) with an explicit writable emptyDir for temp files eliminates an entire class of container escape and persistence techniques.