--- name: docker description: "Use when authoring or auditing a Dockerfile/Containerfile, shrinking a bloated image, hardening a container that runs as root, choosing a base image, or wiring a Compose dev loop with hot reload. Triggers: 'dockerize this app', 'my node image is 1.2GB make it smaller', 'the build cache keeps busting', 'harden this Dockerfile, trivy flags it', 'docker compose watch for local dev', 'distroless vs alpine vs slim', 'la imagen pesa demasiado', 'el build de docker tarda siglos'. NOT the CI/CD pipeline or deploy-to-host (that is deployment), NOT k8s autoscaling/HPA (that is scaling), NOT app-level SQL injection or secrets-in-code (that is secure-coding)." tags: [docker, containers, dockerfile, compose, image-security] recommends: [deployment, secure-coding, scaling, github-actions] origin: risco --- # 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. ```text 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.** Pushing to a registry, building in CI, deploying to a host, rollback — that is `../deployment/SKILL.md`. It already references Dockerfiles; you are the image-internals specialist it leans on. ## When to use - Authoring or auditing a `Dockerfile` for any stack (Node, Python, Go, Rust, JVM, static SPA). - An image is too big (800 MB+ Node image), builds too slowly, or fails `trivy`/`hadolint`. - A container runs as root and you need least privilege. - Standing up local dev with `compose.yaml` + `docker compose watch` (sync / rebuild / sync+restart). - Choosing a base image and getting multi-stage + BuildKit cache mounts right. ## 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 | ## The five rules 1. **Multi-stage, always.** Build deps (compilers, dev packages, the full SDK) must never reach the runtime image. Multiple `FROM` stages; copy only the built artifact into a minimal final stage. *Why: a Go binary needs ~10 MB, not a 900 MB toolchain — and every extra package is CVE surface.* 2. **Choose the base deliberately and pin it — never `:latest`.** Pin a tag (ideally a digest) so a rebuild is reproducible. *Why: `:latest` silently changes under you, breaking builds and busting the scan you just passed.* 3. **Install deps before copying source.** Order layers so the lockfile install is cached and use BuildKit cache mounts. *Why: copying everything first invalidates the dependency layer on every one-character source edit.* 4. **Run as a non-root `USER`.** Default PID 1 is root (UID 0); a container escape from root is a host compromise. *Why: least privilege is the cheapest blast-radius reduction you can ship.* 5. **One concern per container; EXEC-form `CMD`; add a `HEALTHCHECK`.** *Why: shell-form `CMD foo` wraps your process in `/bin/sh -c`, which swallows `SIGTERM` so the container ignores graceful shutdown; a healthcheck lets Compose/orchestrators gate on readiness.* ## 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 live in [references/base-images-and-stages.md](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. ```dockerfile # 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. ```dockerfile # 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. ```dockerfile # 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 .`. ```gitignore .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: ```bash 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: ```dockerfile # 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 ``` ```bash 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. `develop.watch` is GA since Compose 2.22.0 and gives you a tight dev loop. ```yaml 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](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` (pin/digest) | `:latest` drifts; builds + scans become non-reproducible | | runs as root (no `USER`) | `USER nonroot` / `USER 10001` | root 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 swallows `SIGTERM`; no graceful shutdown | ## References & siblings - [references/base-images-and-stages.md](references/base-images-and-stages.md) — per-language multi-stage templates (Rust, JVM jlink, static SPA → nginx), tag maps, multi-arch buildx. - [references/compose-recipes.md](references/compose-recipes.md) — fuller Compose patterns. - Once the image is green and scanned: `../deployment/SKILL.md`. Image/container hardening pairs with `../secure-coding/SKILL.md`. Self-hosted host ops: `../coolify/SKILL.md`.