Docker Multi-stage Builds Reference

You can assign names to build stages for easier reference:

FROM golang:1.18 AS builder

This creates a stage named "builder" based on the golang:1.18 image.

You can copy files from one stage to another using the COPY instruction with the --from flag:

COPY --from=builder /go/src/app/myapp /usr/local/bin/

This copies the myapp binary from the "builder" stage to the /usr/local/bin/ directory in the current stage.

You can build up to a specific stage by using the --target flag with docker build:

docker build --target builder -t myapp:builder .

This builds only up to the "builder" stage and tags the resulting image as myapp:builder.

You can build your Docker image up to a specific stage using the --target flag:

docker build --target builder -t myapp:builder .

This is useful for:

• Debugging a specific build stage
• Creating development images with additional tools
• Running tests in a build stage without proceeding to the final image

If you don't name your stages, you can refer to them by their index in the COPY --from instruction:

# First stage (index 0)
FROM golang:1.18
WORKDIR /app
COPY . .
RUN go build -o myapp .

# Second stage (index 1)
FROM alpine:3.16
WORKDIR /app
# Copy from the first stage (index 0)
COPY --from=0 /app/myapp .
CMD ["./myapp"]

However, using named stages is generally more readable and maintainable.

Docker BuildKit (enabled with DOCKER_BUILDKIT=1) provides additional features for multi-stage builds, including cache mounts:

FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
# Use a cache mount to persist the npm cache between builds
RUN --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/build /usr/share/nginx/html

This can significantly speed up builds, especially for stages with package managers that maintain their own caches.

BuildKit can build independent stages in parallel, speeding up the overall build:

# These stages can be built in parallel with BuildKit
FROM golang:1.18 AS backend
WORKDIR /app
COPY backend/ .
RUN go build -o api-server .

FROM node:18 AS frontend
WORKDIR /app
COPY frontend/ .
RUN npm ci && npm run build

# This stage depends on both previous stages
FROM alpine:3.16
COPY --from=backend /app/api-server /app/
COPY --from=frontend /app/build /app/public
CMD ["./app/api-server"]

Enable BuildKit by setting the DOCKER_BUILDKIT=1 environment variable when running docker build.

You can use build arguments to dynamically select base images for different stages:

ARG GO_VERSION=1.18
FROM golang:${GO_VERSION} AS builder
WORKDIR /app
COPY . .
RUN go build -o myapp .

ARG RUNTIME_VERSION=3.16
FROM alpine:${RUNTIME_VERSION}
COPY --from=builder /app/myapp /app/
CMD ["/app/myapp"]

This allows you to customize the build without modifying the Dockerfile.

Multi-stage builds are ideal for compiled languages like Go, Rust, C++, and Java, where you need a full development environment for compilation but only the compiled binary for runtime.

# Java application with multi-stage build
FROM maven:3.8-openjdk-17 AS builder
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src/ /app/src/
RUN mvn package -DskipTests

FROM openjdk:17-jre-slim
COPY --from=builder /app/target/*.jar /app/app.jar
CMD ["java", "-jar", "/app/app.jar"]

Multi-stage builds work well for frontend applications that need a build step (like React, Vue, or Angular) but then only need to serve static files at runtime.

# React application with multi-stage build
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/build /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

You can use multi-stage builds to run tests in an intermediate stage but exclude the test code and dependencies from the final image.

# Stage for testing
FROM node:18 AS tester
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm test

# Stage for building
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:18-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --only=production
COPY --from=builder /app/dist ./dist
CMD ["node", "dist/index.js"]

Multi-stage builds can create minimal images that contain only what's needed for runtime, reducing attack surface and image size.

# Build stage
FROM golang:1.18 AS builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o myapp .

# Create a minimal image from scratch
FROM scratch
COPY --from=builder /app/myapp /
CMD ["/myapp"]