From agent-almanac
Creates multi-stage Dockerfiles separating build and runtime for minimal production images using scratch, distroless, alpine. Use for oversized images, build tools in runtime, or edge/serverless deployments.
npx claudepluginhub pjt222/agent-almanacThis skill uses the workspace's default tool permissions.
---
Creates optimized multi-stage Dockerfiles for any language/framework using best practices for minimal size, security, and performance.
Creates production-ready Dockerfiles for Node.js, Python, Go, Rust, and Java projects. Use for first-time containerization, consistent environments, cloud deployment, or Docker Compose.
Generates optimized multi-stage Dockerfiles for Node.js, Python, Rust, Go apps with non-root users, layer caching, health checks, and .dockerignore. Use for containerizing apps or Docker Compose setup.
Share bugs, ideas, or general feedback.
Build multi-stage Dockerfiles that produce minimal production images by separating build tooling from runtime.
| 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 |
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>]
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"]
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"]
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"]
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"]
Expected: Final image contains only the runtime and compiled artifacts.
On failure: Check COPY --from=builder paths. Use docker build --target builder to debug the build stage.
| 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.
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.
# 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
Expected: Production image is 50-90% smaller than the build stage.
docker build completes for all stagesdocker run works correctly from the slim imageCOPY --from=builder paths are correctlibc, libssl). Test the slim image thoroughly.COPY --from paths: The artifact path must match exactly. Use docker build --target builder then docker run --rm builder ls /path to debug.-slim instead.ARG declared before FROM is available to FROM lines only. Re-declare inside each stage that needs it.scratch has no certificates. Copy /etc/ssl/certs/ca-certificates.crt from the builder or use distroless.create-dockerfile - single-stage general Dockerfilescreate-r-dockerfile - R-specific Dockerfiles with rocker imagesoptimize-docker-build-cache - layer caching and BuildKit featuressetup-compose-stack - compose configurations using multi-stage images