containerization

Containerization

A container image is a build artifact meant to be byte-identical everywhere it runs. Most Dockerfile trouble comes from treating it like a virtual machine — installing a shell's worth of tools, running as root, and rebuilding the world on every code change.

Aim for three properties: small, reproducible, and least-privileged. A change that does not move one of those is not worth making.

For language-specific multi-stage templates, distroless runtimes, and BuildKit cache and secret mounts, read references/dockerfile-patterns.md.

1. Order layers by how often they change

Docker caches per layer and invalidates every layer after the first change. Put the stable things first so a one-line edit does not re-download the internet:

COPY package.json package-lock.json ./
RUN npm ci                      # cached until dependencies change
COPY . .                        # invalidated on every source change

Copying source before installing dependencies means every code change reinstalls everything. This single reordering is usually the largest build-time win available.

Done when: a code-only change does not reinstall dependencies.

2. Separate build tooling from the runtime image

A multi-stage build compiles or installs in one stage and copies only the resulting artifact into a clean final stage. Compilers, headers, and package caches have no business shipping to production — they add size and give an attacker a toolbox if they land a shell. Name your stages (AS build, AS runtime) so the final COPY --from=build is unambiguous. Sizing the runtime image itself — which base to start the final stage from — is image-optimization's job; this step is about the boundary between building and running.

Done when: the runtime image contains no compiler, package manager cache, or source outside what running requires.

3. Pin the base image and run as a non-root user

FROM node:latest is not a build input, it is a random number generator — the tag moves under you and today's build is not tomorrow's. Pin to a digest or an explicit version tag so a rebuild six months from now produces the same bytes. Then drop privilege: create or reuse a non-root user and switch to it before the final CMD, so a container escape does not hand over root on the host. Combine this with a read-only root filesystem and a dropped CAP_* set where the runtime supports it.