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.

```dockerfile
# ---- 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)

```dockerfile
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"]
```

#### Python (virtualenv copy)

```dockerfile
FROM python:3.12-bookworm AS builder
WORKDIR /src
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

FROM python:3.12-slim-bookworm
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app
COPY --from=builder /src .
RUN groupadd -r app && useradd -r -g app app
USER app
EXPOSE 8000
CMD ["python", "app.py"]
```

#### Go (static binary to scratch)

```dockerfile
FROM golang:1.23-bookworm AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server

FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /server /server
EXPOSE 8080
ENTRYPOINT ["/server"]
```

#### Rust (static musl binary)

```dockerfile
FROM rust:1.82-bookworm AS builder
RUN apt-get update && apt-get install -y musl-tools && rm -rf /var/lib/apt/lists/*
RUN rustup target add x86_64-unknown-linux-musl
WORKDIR /src
COPY Cargo.toml Cargo.lock ./
RUN mkdir src && echo "fn main() {}" > src/main.rs \
    && cargo build --release --target x86_64-unknown-linux-musl \
    && rm -rf src
COPY . .
RUN touch src/main.rs && cargo build --release --target x86_64-unknown-linux-musl

FROM scratch
COPY --from=builder /src/target/x86_64-unknown-linux-musl/release/myapp /myapp
EXPOSE 8080
ENTRYPOINT ["/myapp"]
```

**Got:** Final image contains only the runtime and compiled artifacts.

**If fail:** Check `COPY --from=builder` paths. Use `docker build --target builder` to debug the build stage.

### Step 4: Choose Runtime Base

| Base | Size | Shell | Use Case |
|------|------|-------|----------|
| `scratch` | 0 MB | No | Static Go/Rust binaries |
| `gcr.io/distroless/static` | ~2 MB | No | Static binaries + CA certs |
| `gcr.io/distroless/base` | ~20 MB | No | Dynamic binaries (libc) |
| `*-slim` | 50-150 MB | Yes | Interpreted languages |
| `alpine` | ~7 MB | Yes | When shell access needed |

**Note:** Alpine uses musl libc. Some Python wheels and Node native modules may not work. Prefer `-slim` (glibc) for interpreted languages.

### Step 5: Build Args Across Stages

```dockerfile
ARG APP_VERSION=0.0.0

FROM golang:1.23 AS builder
ARG APP_VERSION
RUN go build -ldflags="-X main.version=${APP_VERSION}" -o /server .

FROM gcr.io/distroless/static
COPY --from=builder /server /server
ENTRYPOINT ["/server"]
```

Build with: `docker build --build-arg APP_VERSION=1.2.3 .`

**Note:** `ARG` before `FROM` is global. Each stage must re-declare `ARG` to use it.

### Step 6: Compare Image Sizes

```bash
# Build both variants
docker build -t myapp:fat --target builder .
docker build -t myapp:slim .

# Compare sizes
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" | grep myapp
```

**Got:** Production image is 50-90% smaller than the build stage.

## Validation

- [ ] `docker build` completes for all stages
- [ ] Final image does not contain build tools (compilers, dev headers)
- [ ] `docker run` works correctly from the slim image
- [ ] Image size is significantly reduced vs single-stage
- [ ] `COPY --from=builder` paths are correct
- [ ] No source code leaks into the production image

## Pitfalls

- **Missing runtime libraries**: Compiled code may need shared libraries (`libc`, `libssl`). Test the slim image thoroughly.
- **Broken `COPY --from` paths**: The artifact path must match exactly. Use `docker build --target builder` then `docker run --rm builder ls /path` to debug.
- **Alpine musl issues**: Native Node.js addons and some Python packages fail on Alpine. Use `-slim` instead.
- **Global ARG scope**: An `ARG` declared before `FROM` is available to `FROM` lines only. Re-declare inside each stage that needs it.
- **Forgetting CA certificates**: `scratch` has no certificates. Copy `/etc/ssl/certs/ca-certificates.crt` from the builder or use distroless.

## Related Skills

- `create-dockerfile` - single-stage general Dockerfiles
- `create-r-dockerfile` - R-specific Dockerfiles with rocker images
- `optimize-docker-build-cache` - layer caching and BuildKit features
- `setup-compose-stack` - compose configurations using multi-stage images