Learn Docker - Multi-Stage Builds & Image Optimization

#Introduction

After creating a production-grade Dockerfile in episode 6 — dissecting ENV vs ARG, running processes as non-root with USER, and optimizing the build with layer caching and .dockerignore — in this episode we face the next biggest problem: image size. In episode 6 we managed to shrink the layers, but there's one structural problem left untouched: for applications that need to be built, all the build tooling stays glued into the image.

Imagine a Go application: to compile it you need the Go SDK (±200 MB), and the resulting binary is only a few megabytes. With the usual Dockerfile approach, your image will carry the SDK, compiler, source code, and all build libraries — even though at runtime the application only needs its binary. The same thing happens with Node.js native dependencies (node-gyp needs Python + gcc), or Java/Maven applications that need a JDK to build but only a JRE to run. This is a real production problem: giant images mean slow downloads, a wider security attack surface, and bloated registry storage costs.

In this episode we'll dissect the solution that's become the industry standard: multi-stage builds. We'll build the application in a "build stage" full of tooling, then copy only the result into a tiny "runtime stage" — so much so that you can drop image size from gigabytes to tens of megabytes, and reach the crucial question: when to use Alpine, Distroless, or even scratch?

#Main Discussion

#The Bloated Image Problem

Before multi-stage existed, the common practice was writing one Dockerfile that contained everything — build tools and runtime in a single image. Let's see how wasteful that is. An image built from golang:1.23 (which needs a compiler) carries around 800 MB — just to run a 10 MB binary. Same with full node:20 (±1 GB) for an application that's already built into static assets, or maven:3.9-eclipse-temurin (±1 GB) to deliver a single JAR.

docker pull golang:1.23-alpine
docker pull node:20-alpine
docker pull alpine:3.20

golang:1.23-alpine      257MB
node:20-alpine          185MB
alpine:3.20              8MB

Note the numbers: just the base image of Go's Alpine variant is already 257 MB, and that's before application code and dependencies. Now recall the layer lesson from episode 5: any file ever copied gets "locked" in a layer forever. So if we copy source code and run go build in the same image where we run the binary, all the in-between files — source, cache, compiler, toolchain — get carried into the final image. A final image that should contain a 10 MB binary instead becomes 300+ MB.

The fundamental principle: build tools (SDK, compiler, dev dependencies) must not exist in the production image. A production image should only contain what's needed at runtime: the binary/application, a minimal runtime, and configuration. Multi-stage build is Docker's mechanism for realizing this principle cleanly.

#The Multi-Stage Builds Concept

A multi-stage build is simply a Dockerfile with more than one FROM. Each FROM starts a new "stage" — think of a stage as a separate workroom in a single construction project: the first room is where components are assembled (full of tools), the second room is where the finished product is packed (containing only shipping boxes). Docker runs each stage, then lets you copy files between stages with COPY --from=<stage-name>. What determines the final image size is only the last stage — everything from previous stages is discarded once the build finishes, except what's copied.

# Stage 1: build — penuh tooling
FROM golang:1.23-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app/myapp .
 
# Stage 2: runtime — mungil
FROM alpine:3.20
WORKDIR /app
COPY --from=builder /app/myapp ./myapp
CMD ["./myapp"]

Here, AS builder names the first stage. The second stage starts from alpine:3.20 (tiny), then COPY --from=builder /app/myapp ./myapp pulls the compiled binary from the builder stage. The end result: an image containing only Alpine (8 MB) + the binary (10 MB) = about 18 MB, not 300 MB. Source code, the Go SDK, and cache are all discarded.

A few important details:

1. Stage names are optional. Without AS builder, you can refer to a stage by its sequential index — COPY --from=0 /app/myapp ./myapp refers to the first stage. Names are much more readable, so always name them.
2. Only the last stage becomes the final image — unless you target another stage with --target at build time (docker build --target builder), which is useful for development images.
3. There can be more than two stages. For complex applications, the common pattern is: a deps stage (download dependencies), a build stage (compile), and a runtime stage (final). These stages can be reused and built in parallel by BuildKit.

#Example 1: A Go Application

Go is the most perfect candidate for multi-stage because its output is a single static binary that needs no runtime at all. Note the CGO_ENABLED=0 flag — it produces a static binary that can run without system libraries, even on an empty image.

FROM golang:1.23-alpine AS builder
WORKDIR /src
ENV CGO_ENABLED=0 GOOS=linux
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -trimpath -ldflags="-s -w" -o /out/app .
 
FROM scratch
COPY --from=builder /out/app /app
ENTRYPOINT ["/app"]

Let's break it down: -ldflags="-s -w" strips the symbol table and debug info from the binary (shrinking it by a few more MB). -trimpath removes absolute paths from the binary's metadata. Then — the peak of optimization — the runtime stage uses scratch, the "completely empty" image that contains nothing, not even a shell or ls. A static Go binary can run directly on scratch because it doesn't depend on external libraries. Final size: a few megabytes, roughly the size of the binary itself.

scratch isn't for everyone — containers on it have no /bin/sh, so debugging (docker exec ... sh) is impossible. But for a well-tested static binary, scratch is the safest and smallest image you can have.

#Example 2: A Node.js Application

Node.js differs from Go: JavaScript applications aren't compiled into a binary, so the Node.js runtime itself is still needed in the final stage. But that doesn't mean multi-stage doesn't help. Two problems multi-stage solves for Node.js:

1. Dev dependencies. Applications like Next.js, React, or TypeScript APIs need the full node_modules (including development dependencies and bundling tooling) while building assets. In the build stage, install everything; in the runtime stage, copy only the production node_modules (npm ci --omit=dev) and the build output.

2. Native dependencies. Packages using node-gyp need Python and a compiler to install. In the build stage, compile; in the runtime stage, copy the result.

FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine
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
EXPOSE 3000
USER node
CMD ["npm", "start"]

The key: the builder stage installs all dependencies and builds the application (npm run build). The runtime stage copies only package.json, the production node_modules, and the build output folder (.next). Note that in the runtime stage, node_modules is already in the "production" form produced by npm ci with NODE_ENV=production — as a result, the final image doesn't carry TypeScript, test runners, or bundling tooling that could eat hundreds of MB.

#Example 3: A Java/Maven Application (At a Glance)

The same pattern applies to the JVM ecosystem — where the benefit is even greater because the JDK is much larger than the JRE:

FROM maven:3.9-eclipse-temurin-21 AS builder
WORKDIR /src
COPY pom.xml ./
RUN mvn -B dependency:go-offline
COPY src ./src
RUN mvn -B package -DskipTests
 
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY --from=builder /src/target/*.jar ./app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

The first stage uses the giant Maven image (±1 GB) containing the JDK and Maven to download dependencies and package the application. The second stage uses eclipse-temurin:21-jre-alpine (JRE only, ±80 MB) and copies a single .jar file. The final image drops dramatically from over 1 GB to under 100 MB.

#Comparing Image Sizes

To truly feel the impact, let's compare two ways of building the same Go application:

FROM golang:1.23-alpine
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o /app .
CMD ["/app"]

FROM golang:1.23-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/app .
 
FROM scratch
COPY --from=builder /out/app /app
ENTRYPOINT ["/app"]

REPOSITORY   TAG       IMAGE ID       SIZE
myapp-single 1.0       5f2a1c9e3b41   312MB
myapp-multi  1.0       8d0c7a4f2e59   14.8MB
alpine       3.20      5c5d0b1a4e92   8.05MB

312 MB compared to 14.8 MB — a 95% reduction. In production, this difference means: much faster image pulls at deployment, more economical registry storage, and a drastically smaller security attack surface because the image no longer carries a compiler or source code.

#Image Optimization Best Practices

Besides multi-stage, there are several complementary practices:

1. --squash: why it's rarely used. The docker build --squash option merges all layers into one. At first glance it's appealing — the image becomes smaller and "cleaner". But there are strong reasons it isn't popular: (a) it destroys the benefit of layer caching — every change forces the entire image to be rebuilt from scratch; (b) buildkit historically hasn't fully supported it; (c) every size problem you're trying to solve can actually be solved with multi-stage + proper RUN chains — in a way that still preserves caching. The principle: fix the cause, not the symptom.

2. Use the smallest sensible base image. Multi-stage + Alpine/Distroless/scratch. Don't use full images at runtime without a reason.

3. Pin exact image versions. node:20-alpine, golang:1.23-alpine — pinned, not latest. An image tagged latest is a moving target: a base image that silently changes can break your build's reproducibility (we'll explore this supply chain concept in episode 26).

4. Combine related RUNs (the && chain pattern from episode 6) to avoid junk layers.

5. Watch out for multi-arch. Modern images are pushed as multi-architecture manifests — one tag (node:20-alpine) contains both linux/amd64 (cloud servers) and linux/arm64 (Apple Silicon, ARM servers) variants. On pull, Docker automatically selects the variant matching the host architecture. To preserve this, the base image must be official and published multi-arch. The consequence for you: when testing builds, make sure to use the appropriate emulation or builder (docker buildx build --platform linux/arm64 — covered in detail in episode 18). Go images with CGO_ENABLED=0 are very multi-arch friendly because a static binary doesn't depend on system library architecture.

#Alpine vs Distroless vs Scratch: When to Choose What?

Three "families" of runtime images are most commonly used, with different trade-offs:

Rule of thumb:

• Choose scratch for static binaries — usually Go or Rust with CGO disabled. The smallest and safest image. Prepare a debugging strategy (logging, healthcheck) from the start because there's no shell.
• Choose Distroless when you need a full runtime (Node.js, Python, Java) but want a safe, lean image without a shell — popular among teams applying strict security hardening (no shell to abuse after an exploit).
• Choose Alpine as the balance: tiny, has apk and a shell, very flexible for images that need extra tools. The downside: musl libc, and not all binaries/packages are compatible — always test your application before committing to Alpine.
• Avoid full images (node:20, golang:1.23, ubuntu) in runtime images unless there's a specific need — they carry tooling that's only useful at build time.

#Conclusion

In this episode 7 you've solved the bloated image problem: understanding that build tools must not go into the production image, mastering the multi-stage builds technique with multiple FROM + COPY --from=<stage>, and seeing it in three real ecosystems — Go (static binary to scratch), Node.js (build assets, lightweight runtime), and Java/Maven (giant JDK → slim JRE). You also learned why --squash is rarely used (it destroys caching), how multi-arch works, and when to choose Alpine, Distroless, or scratch — going from 312 MB to 14.8 MB, a 95% reduction.

Core takeaway: the final image must contain as little as possible — only what's needed at runtime. Multi-stage is the primary tool, and the choice of runtime base image is an architectural decision that affects long-term security and cost.

Starting from episode 8, we shift from how images are made to how data is managed — because this is where many people begin to realize that containers are stateless: once a container is deleted, all the data written inside it vanishes too. In the next episode, episode 8, we'll dissect data persistence & storage: bind mounts, named volumes, tmpfs, how to back up and restore volumes, and why your database must never live without a volume. See you in episode 8!