Docker Multi-Stage Builds

A single-stage Dockerfile installs a full compiler, downloads every dev dependency, builds the app, and ships all of that — toolchain included — in the exact same image that runs in production. The bloat is the visible problem; the security issue is worse and less visible: any file written in an earlier RUN or COPY layer is part of that layer, permanently, and a later RUN rm only marks it deleted in a new, additional layer on top — the file still physically exists in the image's layer history and can be recovered by anyone who can pull the image and inspect its layers.

This means a build-time secret (an API key fetched to pull a private dependency, a signing credential) that ever touched an early layer is not actually gone just because a later step deletes it — it's still sitting in the image, one docker history and layer extraction away from being read by anyone with pull access. The only mechanism that genuinely excludes something from the final image is never including that layer in the final stage at all — which is exactly what multi-stage builds are for.

A multi-stage Dockerfile has more than one FROM instruction, each starting a fresh stage with its own base image and layer history. Naming a stage with AS builder lets a later stage reference it explicitly: COPY --from=builder /app/dist ./dist copies only that specific path from the named stage's filesystem — nothing else from the builder stage comes along. A Dockerfile can have as many stages as needed (a dependencies stage, a test stage, a build stage), and only the final FROM block (or one selected with docker build --target) becomes the actual image that gets tagged and shipped.

Stages don't have to share a base image or even a language — a Go binary's build stage can use the full golang image while its final stage uses a minimal alpine or distroless base with nothing but the compiled binary, because Go produces a statically-linked executable that doesn't need Go itself present at runtime at all.

Docker caches each instruction's resulting layer and reuses it on a rebuild if nothing that affects it has changed — but the moment one instruction's inputs change, every instruction after it in that stage rebuilds from scratch, cached or not. This makes instruction order a real performance decision: copying the entire source tree before installing dependencies means any source file edit invalidates the dependency-install layer's cache too, even though the dependencies themselves didn't change — forcing a full reinstall on every rebuild.

The fix is copying only the dependency manifest first, installing, and then copying the rest of the source — so an ordinary code change only invalidates the (usually fast) final copy-and-build steps, not the (usually slow) dependency install. BuildKit's --mount=type=cache goes further: it persists a directory (like npm's or pip's download cache) across builds without that cache ever becoming part of any image layer at all — faster rebuilds without the cache bloating the image the way baking it into a regular layer would.

The final stage's base image is a deliberate trade between size, security surface, and operability. Alpine is small and has a shell and package manager for debugging, but its musl libc occasionally causes subtle compatibility issues with binaries built against glibc elsewhere. Distroless (Google's images) strips out the shell and package manager entirely, leaving just the language runtime — smaller attack surface than Alpine, at the cost of not being able to exec into the container for a quick shell debug session. Scratch is completely empty — no shell, no libc, nothing — appropriate only for a fully static binary (a Go build with CGO_ENABLED=0, or Rust with the musl target) that needs nothing from the base image at all.

The debugging trade-off is real and worth deciding deliberately rather than defaulting to whatever the tutorial used: a distroless or scratch production image is harder to poke at with docker exec sh during an incident, which is a legitimate cost some teams accept for the security benefit and others don't, especially early on when operational familiarity matters more than a minimal attack surface.