appkit: Skill for Claude Code

Multi-Stage Dockerfiles

Quick reference

• Multi-stage builds — separate builder from runtime; copy only artifacts.
• Pin versions — use exact image tags (python:3.13-slim-bookworm, not python).
• Minimize layers — combine RUN commands with &&; order from least→most changing.
• Non-root user — always set USER in the final stage.
• Cache mounts — use --mount=type=cache for package manager caches.
• Healthchecks — add HEALTHCHECK for production readiness.

Stage structure

dependencies → build → (test) → runtime

Use meaningful stage names with the AS keyword.

# ── Stage 1: Builder ──
FROM python:3.13-slim-bookworm AS builder
# install build deps, compile, fetch packages

# ── Stage 2: Runtime ──
FROM python:3.13-slim-bookworm AS runtime
# copy only runtime artifacts from builder
COPY --from=builder /app /app

Key rules

• Builder stage — install compilers, dev headers, build tools. Run pip install, npm ci, cargo build, etc.
• Runtime stage — start from a minimal base; copy only the built output, virtual env, or binary.
• Never install build-only tools (gcc, make, node-gyp) in the runtime stage.

Base image selection

Goal	Recommended base	Notes
Smallest possible	distroless / alpine	No shell; harder to debug
Balance size + compat	*-slim variants	Good default for Python, Node
Full tooling needed	*-bookworm / *-bullseye	Use only in builder stage

• Always pin to a specific tag: python:3.13-slim-bookworm, node:22-alpine3.20.
• Match builder and runtime base OS family when possible to avoid glibc mismatches.

Layer optimization

Order: stable → volatile

# 1. System deps (rarely change)
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# 2. Dependency manifests (change occasionally)
COPY pyproject.toml uv.lock ./

# 3. Install deps (cached unless manifests change)
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-install-project

# 4. Application code (changes frequently)
COPY . .