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.

In Practice: Navigating Feedback & Collaboration

Let’s face it – technical communication isn’t just about writing code. It’s a crucial skill when working in teams, especially when dealing with complex processes like Docker multi-stage builds. For non-native English speakers, the nuances of professional phrasing can be particularly challenging. Consider this scenario: Sarah, a developer on a project using Docker, is reviewing a pull request submitted by Mark. Mark has used a multi-stage build to create an image for their new API service. The PR description is…sparse. It simply states “Builds the API.”

Mark’s lack of detail immediately raises a flag. A good review comment isn’t just about pointing out problems; it’s about facilitating understanding and ensuring future maintainability. Instead of saying, “This build is unclear,” Sarah might respond in Slack with something like, “Hi Mark, could you elaborate on the stages used in this build? Specifically, I’d like to understand which base image you’re starting from and what steps are involved in copying dependencies into the final artifact. Knowing this helps us assess potential size bloat and ensure our deployment process remains efficient.” This phrasing uses precise vocabulary – “base image,” “dependencies,” “artifact” - terms frequently encountered when discussing build processes. It focuses on why clarity is important (“assess potential size bloat,” “ensure our deployment process remains efficient”) rather than simply stating a demand for more information.

Another common situation arises during PR descriptions themselves. When proposing a new multi-stage build, it’s vital to be explicit about the reasoning behind each stage. Saying “This builds the application” isn’t enough. Instead, you might write: “This multi-stage build utilizes a Node.js base image (node:16) for compiling the frontend and backend code. The first stage compiles the source into an optimized JavaScript bundle, which is then copied to a smaller Alpine Linux base image in the second stage. This minimizes the final image size by excluding unnecessary development tools.” This level of detail demonstrates professionalism and allows reviewers to quickly grasp the build’s purpose and potential impact. It’s about conveying intent – that you’ve considered optimization and security best practices.

Finally, remember that concise language is key. Avoid overly verbose descriptions. Focus on delivering crucial information efficiently. Using terms like “intermediate artifact” or “layer” when discussing Docker builds can often streamline communication, but only if your audience understands those terms.

Here’s a simple example demonstrating how to specify the Dockerfile instruction for copying files between stages:

FROM node:16 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
# Build the application
RUN npm run build

FROM alpine:latest AS final
COPY --from=builder /app/dist ./public