create-multistage-dockerfile

Create Multi-Stage Dockerfile

Build multi-stage Dockerfiles that produce minimal production images by separating build tooling from runtime.

When to Use

• Production images are too large (>500MB for compiled languages)
• Build tools (compilers, dev headers) are included in the final image
• Need separate images for development and production from one Dockerfile
• Deploying to constrained environments (edge, serverless)

Inputs

• Required: Existing Dockerfile or project to containerize
• Required: Language and build system (npm, pip, go build, cargo, maven)
• Optional: Target runtime base (slim, alpine, distroless, scratch)
• Optional: Size budget for final image

Procedure

Step 1: Identify Build vs Runtime Dependencies

Category	Build Stage	Runtime Stage
Compilers	gcc, g++, rustc	Not needed
Package managers	npm, pip, cargo	Sometimes (interpreted langs)
Dev headers	-dev packages	Not needed
Source code	Full source tree	Only compiled output
Test frameworks	jest, pytest	Not needed

Step 2: Structure the Multi-Stage Build

The core pattern: build in a fat image, copy artifacts to a slim image.

# ---- Build Stage ----
FROM <build-image> AS builder
WORKDIR /src
COPY <dependency-manifest> .
RUN <install-dependencies>
COPY . .
RUN <build-command>

# ---- Runtime Stage ----
FROM <runtime-image>
COPY --from=builder /src/<artifact> /<dest>
EXPOSE <port>
CMD [<entrypoint>]

Step 3: Apply Language-Specific Patterns

Node.js (pruned node_modules)

FROM node:22-bookworm AS builder
WORKDIR /src
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

FROM node:22-bookworm-slim
RUN groupadd -r app && useradd -r -g app app
WORKDIR /app
COPY --from=builder /src/dist ./dist
COPY --from=builder /src/node_modules ./node_modules
COPY --from=builder /src/package.json .
USER app
EXPOSE 3000
CMD ["node", "dist/index.js"]