English for Docker Multi-Stage Builds

A production image that ships the entire compiler toolchain alongside the compiled binary is bloated and harder to secure — multi-stage builds solve this by separating “build environment” from “runtime environment,” and naming that separation precisely is what keeps a Dockerfile review productive.

Key Vocabulary

Build stage — a named section of a Dockerfile (FROM node AS builder) that runs compilation, dependency installation, or bundling, whose intermediate layers never ship in the final image unless explicitly copied out. “The build stage installs all the dev dependencies and runs the TypeScript compiler, but none of that ends up in the final image — only the compiled JavaScript does.”

COPY —from — the instruction that pulls specific files or directories from an earlier build stage into the current one, the mechanism that actually moves compiled artifacts across stages. “We use COPY --from=builder /app/dist ./dist to bring just the compiled output into the runtime stage, leaving the entire node_modules dev install behind.”

Runtime stage — the final stage in a multi-stage Dockerfile, typically based on a minimal image, that contains only what’s needed to run the application, not to build it. “The runtime stage is based on node:slim with no compilers at all — it just runs the JavaScript that got copied in from the build stage.”

Base image — the image referenced in a FROM instruction that a stage builds on top of, chosen per stage based on what that stage actually needs (a full SDK for building, a minimal distro for running). “We picked a full SDK base image for the build stage and a distroless base image for the runtime stage — different jobs, different requirements.”

Layer caching — Docker’s mechanism for reusing unchanged intermediate layers across builds, which multi-stage builds interact with by letting dependency-install layers stay cached even when only application code changes. “Ordering the COPY package.json and install step before copying the rest of the source means layer caching skips the reinstall unless dependencies actually changed.”

Common Phrases

• “Is this dependency needed in the runtime stage, or just for building?”
• “We’re copying the compiled binary across with COPY --from, so the build tools never reach production.”
• “Can we shrink this by switching the runtime stage to a smaller base image?”
• “That layer isn’t caching because the copy order invalidates it on every source change.”
• “Which stage does this instruction belong in — build or runtime?”

Example Sentences

Explaining an image size reduction in a PR: “This multi-stage build cut the final image from 1.2GB to 180MB — the build stage still has the full compiler toolchain, but the runtime stage only copies out the compiled binary via COPY --from=builder.”

Reviewing a Dockerfile that skipped staging: “Right now everything’s in one stage, so the shipped image includes the entire build toolchain. Splitting this into a build stage and a slim runtime stage would meaningfully reduce the attack surface.”

Diagnosing a slow CI build: “The build stage is reinstalling dependencies on every run because the COPY . . happens before the install step — reordering it so dependency files are copied first would let layer caching actually kick in.”

Professional Tips

• Name build stage and runtime stage explicitly when reviewing a Dockerfile — reviewers often can’t tell at a glance which instructions belong to which without the labels.
• Point out unnecessary tools or dependencies that leaked into the runtime stage — a common review comment is “does this need to be here, or is it a build-only dependency?”
• Recommend COPY --from explicitly instead of installing build tools directly in the final stage — it’s the single change that most reduces image size and CVE surface.
• Mention layer caching order when a build is slower than expected — copying source before dependency manifests is a frequent, easily fixed cause.

Practice Exercise

1. Write a sentence explaining why the runtime stage should not include the compiler toolchain.
2. Explain what COPY --from=builder does in your own words.
3. Describe how instruction order affects layer caching in a multi-stage build.