Docker Multi-Stage Builds: Optimization Patterns for Production

Architecture

A Docker multi-stage build is a manufacturing pipeline. The build stage installs compiler toolchains and dependency caches, generates artifacts, and runs validation. The final stage starts from a minimal runtime base, copies only the needed binary or web assets, and strips anything irrelevant. This is the difference between a development container and a deployment artifact: development images are convenient, production images are constrained, reproducible, and small. A production team should optimize for deterministic output and minimal attack surface, not for the easiest local build.

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/package*.json ./
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

FROM rust:1.79 AS builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
WORKDIR /app
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/my-service /usr/local/bin/my-service
USER 10001
CMD ["/usr/local/bin/my-service"]

docker image inspect my-service:latest | jq '.[0].Size'

1.2GB

Step 6/10: RUN npm ci ... -> cache miss after a CSS file change

...

Why the build stage exists

A Docker image is built in layers, but a production image does not need every layer from a dev workstation. Build tooling, compilers, source trees, and test dependencies are often useful while the software is being compiled, but they are not useful in a runtime container. A multi-stage build honors that boundary.

This is more than a clean-up exercise. Smaller images have smaller attack surfaces, faster push times, lower transfer costs, and better startup performance. In many teams, the docker build step becomes the bottleneck for delivery speed. A good image pipeline keeps the compile and package phases isolated from the runtime phase so the final artifact stays deployable and minimal.

Build once, ship the result

The core idea is straightforward: use one stage to assemble artifacts and a second stage to ship those artifacts. The builder stage can include the full toolchain and package manager state needed to compile code. The final stage often uses a slim operating system and nothing more than the compiled binary, static assets, and required runtime libraries.

This prevents a common trap: copying the entire repository into the final image and leaving all the dev dependencies in place. It also makes the final image easier to understand and audit. A runtime image should be able to answer a very basic question: “What do I need to run this service?” The answer should be short, explicit, and reproducible.

Layer ordering decides rebuild speed

The most important optimization is not the number of stages; it is the order of commands in each stage. Docker caches layers by content hash. If you copy your entire source tree before you install dependencies, a trivial application change invalidates the dependency installation layer. That leads to slower builds and less predictable CI time.

The right pattern is usually:

1. copy package manifests or dependency lock files;
2. install dependencies;
3. copy application source;
4. run the compile or test step;
5. final stage copy only the built artifact.

This gives you strong cache reuse, which is essential for a fast developer loop and a reliable CI system. It also keeps the build output stable across repeated runs.

Minimal runtime is a security decision

A big runtime image is not only heavier; it is more dangerous. It often includes package managers, shell utilities, compilers, and debugging libraries that make the system easier to poke at but harder to defend. Many production incidents arise from unnecessary dependencies being present in a runtime container, especially when the image package manager remains available to untrusted users.

That is why a minimal final stage often includes:

• a small base such as debian:bookworm-slim or alpine;
• a non-root user;
• only copied application artifacts;
• no source tree, no compiler, no debugging tools.

The goal is not to make the image impossible to debug; it is to make the image intentionally small enough that its responsibilities are obvious. If debugging is needed, use a temporary image or a debug target instead of shipping extra tools to every runtime container.

Production examples: static assets and packaged services

For a web application, the final stage may copy only the built dist or .next directory, the public assets, and the exact runtime dependencies needed to serve them. For a Go or Rust service, you will often copy the compiled binary and a tiny set of certificates or shared libraries. This is where output discipline matters.

If your builder stage runs tests, linting, or static analysis, keep those checks in the build stage. The final image should not include test fixtures or build directories. The ability to separate quality gates from actual deployment assets is exactly the value of multi-stage builds in a serious engineering organization.

BuildKit helps with better caching

Modern Docker builds often benefit from BuildKit’s cache mounts. This lets the builder persist package manager state across builds without bloating the final image. For example, JavaScript package managers, Go module caches, and Cargo caches can be mounted locally or in a cache volume to reduce repeated network fetches. The result is a compound benefit: faster builds and leaner artifact output.

This pattern is worth adopting when you have a service with several dependency layers or when your CI runners rebuild images frequently. The build cache should optimize the build pipeline, not the runtime artifact.

Final guideline

The best multi-stage Dockerfile is not the most complex one; it is the one that preserves clarity. Use stages to separate concerns clearly: build tools, dependency installation, artifact generation, and runtime execution. Copy only what the process needs. Keep caches warm without leaking them into the deployment image. Remove shell access and extra packages unless they are absolutely required.

That is the foundation of a secure, fast, and maintainable image strategy. A multi-stage build should feel like a packaging pipeline for production, not a place to keep a full development machine.