docker — container-craft

You own one question, deeply: how do I turn this app into a small, secure, fast-building image — and run a frictionless local stack with Compose? Your artifacts are the Dockerfile, the .dockerignore, and the compose.yaml: their layers, their attack surface, their build cache, their dev loop. You do not touch what happens after the image is built.

source  →  Dockerfile (multi-stage, cache mounts)  →  small + scanned image  +  compose.yaml (dev loop)
                                                            └──────────────┬──────────────┘
                                                    hand off to ../deployment/SKILL.md

The hand-off is sharp: the moment you have a green, scanned image and a working compose.yaml, you are done. Everything downstream is ../deployment/SKILL.md — it already references Dockerfiles and leans on you for the image internals.

When NOT to use — and who owns it instead

You're asked for…	Owner	Why it's not you
CI build, registry push, deploy to host, rollback	../deployment/SKILL.md	You build + harden the image; it moves the image through CI to prod
k8s manifests, HPA autoscaling, ingress	scaling	Orchestration above a single image
App SQL injection, secrets in source, dep CVE triage	../secure-coding/SKILL.md	You cover only image/container hardening
Install/operate a self-hosted PaaS	../coolify/SKILL.md	Host operation, not the image
Containerless PaaS deploy mechanics	../railway/SKILL.md, ../fly-io/SKILL.md	Platform deploy, not the Dockerfile

Pick a base image (2026 reality)

Base	Size	CVE / patch velocity	Debuggable?	Wins when
*-slim (e.g. bookworm-slim)	~30–80 MB	moderate, glibc	yes (shell, apt)	pragmatic default, native deps / Python wheels
distroless (gcr.io/distroless/*)	~2–25 MB	convenient but patches slower	no shell	static/compiled runtimes, want minimal surface
Chainguard / Wolfi	tiny, glibc	lowest live CVE count, SLSA L3 attestations	minimal	security-first; real scans found high-sev CVEs where the Chainguard equivalent had zero
alpine	~5 MB, musl	small surface	yes (apk)	tiny static services — but musl breaks many Python wheels / native deps
scratch	0	nothing to patch	no	a fully static binary (Go), nothing else

Rule of thumb: glibc app with native deps → *-slim or Wolfi. Static Go binary → scratch or distroless/static. Security mandate → Chainguard. Reach for alpine only when you've confirmed your wheels/native libs build against musl. Per-language tag maps, multi-stage templates for the stacks not shown below (Rust, JVM jlink, static SPA → nginx) and multi-arch buildx live in references/base-images-and-stages.md.

Multi-stage skeletons

Node — npm ci with a cache mount → distroless nonroot. Bad: single-stage node:20 ≈ 1.1 GB. Good: this ≈ 180 MB. Tags track Node 24 (the active LTS as of mid-2026); Node 22 is in Maintenance LTS, so swap 24→22 only when you deliberately want the conservative maintenance line.

# syntax=docker/dockerfile:1
FROM node:24-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

FROM gcr.io/distroless/nodejs24-debian13:nonroot
WORKDIR /app
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
USER nonroot
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD ["node", "dist/healthcheck.js"]
CMD ["dist/server.js"]

Python — uv into a venv → slim, non-root. Bad: python:3.12 + pip ≈ 1 GB. Good: ≈ 130 MB.

# syntax=docker/dockerfile:1
FROM python:3.13-slim-bookworm AS build
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
ENV UV_PROJECT_ENVIRONMENT=/opt/venv
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv uv sync --frozen --no-dev

FROM python:3.13-slim-bookworm
RUN useradd --create-home --uid 10001 app
COPY --from=build --chown=app:app /opt/venv /opt/venv
COPY --chown=app:app . /app
WORKDIR /app
ENV PATH="/opt/venv/bin:$PATH"
USER app
EXPOSE 8000
HEALTHCHECK CMD ["python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/health').status==200 else 1)"]
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Go — static binary → scratch. Bad: golang:1.26 ≈ 900 MB. Good: ≈ 12 MB. Pin a supported toolchain: Go maintains only the latest two minors (1.26/1.25 as of mid-2026), so a golang:1.23 build image is two minors past EOL and no longer gets security patches.

# syntax=docker/dockerfile:1
FROM golang:1.26-bookworm AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /app ./cmd/server

FROM scratch
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=build /app /app
USER 10001:10001
EXPOSE 8080
ENTRYPOINT ["/app"]

The cache-mount target differs per ecosystem: /root/.npm, /root/.cache/uv (or /root/.cache/pip), /go/pkg/mod. The cache persists across builds without bloating any layer.

.dockerignore — load-bearing, not optional

Without it the entire context (including .git, node_modules, .env) ships to the daemon: it slows the build and can bake secrets into a layer via COPY ..

.git
.gitignore
node_modules
dist
.env
.env.*
*.log
.venv
__pycache__
Dockerfile
.dockerignore
README.md

Mirror .gitignore, then add build outputs and the Dockerfile itself.

Harden the runtime

Non-root in the image (already shown above): create a user, COPY --chown, USER. Then lock the runtime down where the container actually runs:

docker run \
  --read-only --tmpfs /tmp \
  --security-opt=no-new-privileges \
  --cap-drop=ALL \
  myimage:1.4.0

--read-only rootfs + --tmpfs /tmp for scratch space; no-new-privileges blocks setuid escalation; --cap-drop=ALL then add back only what you truly need (--cap-add=NET_BIND_SERVICE to bind port < 1024).

Build secrets — never ARG/ENV. An ARG TOKEN lands in the image history and any ENV SECRET=... persists in a layer. Use a BuildKit secret mount; it is never written to a layer:

# Bad — leaks into image history:  ARG NPM_TOKEN
# Good:
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN="$(cat /run/secrets/npm_token)" npm ci

docker build --secret id=npm_token,env=NPM_TOKEN .

Compose for dev

Canonical filename is compose.yaml; omit the obsolete version: key; use docker compose (v2 subcommand), never the standalone docker-compose v1. One concern per container — the app, the database and the seed job are separate services. develop.watch is GA since Compose 2.22.0 and gives you a tight dev loop.

services:
  api:
    build: .
    ports: ["8000:8000"]
    depends_on:
      db:
        condition: service_healthy
    develop:
      watch:
        - action: sync          # hot-reload: copy changed files into the container
          path: ./src
          target: /app/src
        - action: rebuild       # lockfile / compiled langs: rebuild the image
          path: ./uv.lock
        - action: sync+restart  # config change: sync then restart the process
          path: ./config.yaml
          target: /app/config.yaml
  db:
    image: postgres:17-bookworm
    environment:
      POSTGRES_PASSWORD: dev
    volumes: ["pgdata:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
  seed:
    profiles: ["tools"]         # only runs with: docker compose --profile tools up
    build: .
    command: ["python", "-m", "app.seed"]

volumes:
  pgdata:

Run the dev loop with docker compose watch (or docker compose up --watch). Fuller patterns — watch-per-stack, multi-service healthcheck graphs, override files, env_file vs secrets, and when to graduate to deployment/scaling — are in references/compose-recipes.md.

Verify the image

These are exactly what scripts/verify.sh automates (it skips a tool gracefully if absent):

• hadolint Dockerfile — static lint of the Dockerfile (no error-level findings).
• docker compose config -q — the compose.yaml parses and resolves.
• trivy image myimage:1.4.0 — CVE + misconfig + secret scan of the built image.
• trivy config . — scan the Dockerfile/compose for misconfiguration without a build.
• dockle myimage:1.4.0 — CIS-style image hygiene.
• size check — assert the final image is under your threshold (docker image inspect -f '{{.Size}}').

Anti-patterns

Bad	Good	Why
FROM node:latest	FROM node:24-bookworm-slim, or pin a digest	:latest drifts under you; builds + scans become non-reproducible
runs as root (no USER)	USER nonroot / USER 10001	PID 1 defaults to root (UID 0), so a container escape == host compromise
ARG TOKEN / ENV SECRET=	RUN --mount=type=secret,...	ARG/ENV persist in image history & layers
COPY . . then RUN npm ci	copy lockfile → install → copy source	source edits bust the dep cache layer every build
single FROM, ship the SDK	multi-stage, copy only the artifact	runtime carries compilers & dev CVE surface
apt-get install x	apt-get install --no-install-recommends x && rm -rf /var/lib/apt/lists/*	recommends + apt lists bloat the layer
no .dockerignore	mirror .gitignore + build outputs	whole context ships; .env/.git can leak
version: "3.8" / docker-compose v1	omit version:; docker compose v2	the key is obsolete; v1 is EOL
CMD npm start (shell form)	CMD ["node", "server.js"] (exec)	shell form wraps the process in /bin/sh -c, which swallows SIGTERM — no graceful shutdown
no HEALTHCHECK	HEALTHCHECK CMD [...]	nothing for Compose/orchestrators to gate readiness on (condition: service_healthy)