/containers

name: containers
description: Use when building or debugging container images. Covers multi-stage builds, layer caching, image size, non-root users, signal handling, and the security defaults most Dockerfiles get wrong.
metadata:
  category: devops
  version: 1.0.0
  tags: [docker, containers, dockerfile, security, build]

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.