--- name: docker-build-strategies description: Use this skill when writing, reviewing, or optimizing Dockerfiles, even if the user just says their image is too large, their build is slow, or they need to harden a container for production. Covers multi-stage builds, layer caching, .dockerignore, non-root users, and image size optimization. license: Apache-2.0 compatibility: Requires Docker 23.0+ (BuildKit default). On Docker 20.10–22.x, set DOCKER_BUILDKIT=1 before building. --- # Docker Build Strategies ## Overview This skill provides rules and patterns for writing and reviewing production-quality Dockerfiles. Apply it when the main task is image-build quality: multi-stage builds, cache behavior, non-root execution, build context hygiene, and runtime image size. ## When to use this skill Activate this skill when: - Creating a new Dockerfile for any language or framework - Optimizing an existing Dockerfile for size, speed, or security - Reviewing a Dockerfile for best-practice compliance - Adding a `.dockerignore` file to a project ## Do not use this skill when Do not use this skill when: - The project has no Docker setup yet and the main need is a first-pass scaffold - The main task is wiring services together in `compose.yaml` - The main task is debugging Compose startup ordering, networking, or development overrides ## Core guidance ### Multi-stage builds Use multi-stage builds when the project has a build step or when build-time dependencies differ from runtime. Separate build-time dependencies from the runtime image. 1. Name every stage explicitly (`FROM ... AS build`, `FROM ... AS runtime`). 2. Use the smallest appropriate base for the runtime stage: `distroless`, `alpine`, or `slim` variants. 3. Copy only the final artifact into the runtime stage with `COPY --from=build`. 4. Use `COPY --link` when copying from a prior stage or adding static files — it improves cache reuse by making the COPY independent of previous layers. See `references/multi-stage-builds.md` for language-specific patterns (Go, Node, Python, Java). ### Layer caching Order Dockerfile instructions from least-frequently-changed to most-frequently-changed. 1. Place dependency manifests (`package.json`, `go.mod`, `requirements.txt`) and install steps before copying application source code. 2. Use BuildKit cache mounts for package manager caches: - Go: `RUN --mount=type=cache,target=/go/pkg/mod go build ...` - Node: `RUN --mount=type=cache,target=/root/.npm npm ci` - Python: `RUN --mount=type=cache,target=/root/.cache/pip pip install ...` 3. Pin base image tags to a specific version or digest — never use `latest` in production. 4. Combine related `RUN` commands with `&&` to reduce layer count, but keep logically distinct steps separate for cache granularity. See `references/layer-caching.md` for detailed cache invalidation rules and cache mount patterns. ### Build secrets and SSH access Never bake credentials into the image. Use BuildKit secrets and SSH mounts so credentials are available only during the specific `RUN` step that needs them, and never persist in any layer or `docker history` output. 1. **Do NOT** pass credentials through `ARG` or `ENV`. Both end up in the image layers and are inspectable via `docker history`. 2. **Do NOT** `COPY` credential files into the build context: `.npmrc`, `.pypirc`, `.netrc`, `pip.conf`, Maven `settings.xml`, `.env`, cloud credentials (`~/.aws/credentials`, `~/.config/gcloud/`, service-account JSON files, `~/.azure/`), secret-manager tokens (`~/.vault-token`), package-registry tokens (`~/.cargo/credentials.toml`), TLS keys (`*.pem`, `*.p12`), `kubeconfig`, SSH keys (`id_rsa`, `id_dsa`, `id_ed25519`, `id_ecdsa`). Even when the final stage does not copy them forward, they live in intermediate layers and the build cache. 3. **Do NOT** echo, write, or expand the secret value inside a `RUN` command in a way that persists it to a layer or emits it to build logs. Access the secret file (e.g., `/run/secrets/`, or directly via the mount `target=`) — never `echo "$(cat /run/secrets/X)"`, never substitute it into a shell argument that will be logged with `--progress=plain`. 4. **Use `RUN --mount=type=secret`** for package manager registry credentials: ```dockerfile RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=false \ --mount=type=cache,target=/root/.npm \ npm ci --omit=dev ``` The secret is available only inside that `RUN`, never written to a layer. Use `required=true` when the build will always need the credential (e.g., all packages come from a private registry, so missing the secret should fail the build immediately); use `required=false` only when the secret is optional (the build can succeed with public packages alone). 5. **Use `RUN --mount=type=ssh`** for fetching private Git repositories or modules. The build container has no `known_hosts` by default — populate it inside the same `RUN`: ```dockerfile RUN --mount=type=ssh \ mkdir -p -m 0700 /root/.ssh && \ ssh-keyscan github.com >> /root/.ssh/known_hosts && \ git clone git@github.com:org/private-repo.git ``` Do NOT use `StrictHostKeyChecking=no` as a shortcut — it disables host-key verification entirely. `ssh-keyscan` pins the known fingerprint at build time. 6. **Invoke buildx with the secret and SSH sources:** ```bash # Ensure an SSH agent is running with the key loaded (or use --ssh default=): eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519 docker buildx build \ --secret id=npmrc,src=$HOME/.npmrc \ --ssh default \ . ``` Alternatively, pass the key file directly without an agent: `--ssh default=$HOME/.ssh/id_ed25519`. 7. `.dockerignore` exclusions of `.env` and credential files are **defense in depth**, not the primary mechanism — keep them, but do not rely on them as your only protection. See `references/multi-stage-builds.md` for per-language patterns (npm, pip, Maven, Go `GOPRIVATE`). ### .dockerignore Always generate a `.dockerignore` alongside the Dockerfile. Exclude: - `.git/`, `.github/`, `.vscode/`, `.idea/` - `node_modules/`, `__pycache__/`, `.venv/`, `vendor/` (when rebuilt in the build stage) - `*.md`, `LICENSE`, `docs/` - Build outputs, test artifacts, and IDE configs - `.env` files and any secrets See `assets/dockerignore-example` for a comprehensive template. ### Non-root user Always configure the final image to run as a non-root user. 1. Create a dedicated user and group in the runtime stage: ```dockerfile RUN addgroup --system --gid 1001 appgroup && \ adduser --system --uid 1001 --ingroup appgroup appuser ``` 2. Set ownership on application files: `COPY --from=build --chown=appuser:appgroup /app /app` 3. When combining `--chown` with `COPY --link`, always use the numeric UID:GID you assigned (e.g., `--chown=1001:1001` if you used `--uid 1001 --gid 1001` above), not named users. `--link` creates an independent layer where named users from prior `RUN` instructions are not available. 4. Place the `USER appuser` instruction after all file operations and before `ENTRYPOINT`/`CMD`. 5. On distroless images, use the built-in nonroot user: `USER nonroot:nonroot`. ### Image size optimization 1. Prefer `FROM scratch` (Go static binaries), distroless, or Alpine-based images for the runtime stage. 2. Remove package manager caches in the same `RUN` layer that installs packages: `apt-get install -y ... && rm -rf /var/lib/apt/lists/*` 3. Do not install documentation, man pages, or debug tools in the runtime image. 4. Use `.dockerignore` aggressively to minimize the build context. ### General rules - Always include a `# syntax=docker/dockerfile:1` directive as the first line to enable BuildKit features. - Set `WORKDIR` before any `COPY` or `RUN` instructions — never rely on the default `/`. - Prefer `ENTRYPOINT` with exec form (`["binary"]`) over shell form. - Add `EXPOSE` to document the listening port. - Add metadata labels: `LABEL org.opencontainers.image.source=...` ## Related skills - For first-time Docker project scaffolding and deciding which files to create, use `docker-project-foundations`. - For service dependencies, health checks, overrides, networks, and volume patterns, use `docker-compose-patterns`. - For destructive Docker CLI commands (`docker system prune`, `docker rm -f`, image/network/builder pruning) and a cross-product index of destructive-command guardrails, use `docker-destructive-guardrails`. ## References - `references/multi-stage-builds.md` — Language-specific multi-stage patterns for Go, Node.js, Python, and Java - `references/layer-caching.md` — Deep dive on layer ordering, cache invalidation, and BuildKit cache mounts ## Assets - `assets/Dockerfile.go` — Multi-stage Go build with distroless runtime and non-root user - `assets/Dockerfile.nodejs` — Multi-stage Node.js build with proper layer caching and non-root user - `assets/Dockerfile.python` — Python build with virtual env, layer ordering, and non-root user - `assets/dockerignore-example` — Comprehensive `.dockerignore` template ## Scripts - **`scripts/verify-build.sh`** — Builds the image, reports size and configured user. ```bash bash scripts/verify-build.sh [--help] [IMAGE_NAME] ``` Exit status is `0` when all Docker commands succeed or help is requested, the failing Docker command's non-zero status when verification fails, and `2` for invalid arguments. ## Checks - `checks/verification.md` — Detailed verification runbook for manual review.