interface:
  display_name: Docker Build Strategies
  short_description: Strategies for efficient, secure, and optimized Docker image builds.
  default_prompt: Use this skill when writing or optimizing Dockerfiles.
policy:
  allow_implicit_invocation: true

# Verification Runbook

Use these checks to verify a generated Dockerfile meets quality standards.

## Scripted verification

Run the bundled script from the project root (the directory that contains the `Dockerfile`), with the script path resolved under the skill directory:

```bash
bash "<skill-dir>/scripts/verify-build.sh" [--help] [IMAGE_NAME]
```

Replace `<skill-dir>` with the absolute path of this skill's directory, the folder that contains `SKILL.md` and this `checks/` folder. Do not change into the skill directory to run it; the script builds the current directory.

The image name defaults to `verify-build-test`. Exit status is `0` when the build and inspection commands succeed or help is requested, the failing Docker command's non-zero status when verification fails, and `2` for invalid arguments.

## 1. Build succeeds

```bash
docker buildx build -t test-image .
```

The build must complete without errors. Use `--progress=plain` to inspect each step if debugging is needed (avoid this flag in CI where build logs are persisted, since it may expose the content of any secret that a `RUN` step accidentally echoes).

## 2. Image size is reasonable

```bash
docker images test-image --format "{{.Size}}"
```

Expected baselines for a minimal application:

| Language | Reasonable upper bound |
|---|---|
| Go (distroless/scratch) | < 30 MB |
| Node.js (Alpine) | < 200 MB |
| Python (slim) | < 250 MB |
| Java (JRE Alpine) | < 300 MB |

If the image exceeds these bounds, check for:

- Missing multi-stage build (build tools included in runtime image)
- Large unnecessary files copied into the image
- Missing `.dockerignore`
- OS package caches baked into a layer instead of a BuildKit cache mount (`apt-get`/`apk`)

Use `docker history test-image` to identify which layers are largest.

## 3. Runs as non-root

```bash
docker run --rm test-image whoami
```

Expected output: `appuser`, `nonroot`, or another non-root username. Must not return `root`.

If the image does not have `whoami` (e.g., distroless), verify with:

```bash
docker inspect test-image --format '{{.Config.User}}'
```

The output must be non-empty and must not be `0` or `root`.

## 4. No secrets in image

### 4a. Static check of the Dockerfile pattern (primary)

Before building, verify the Dockerfile does not `COPY` credential files or pass credentials through `ARG`/`ENV`. Any match below is a leak:

```bash
# Credential files copied into the build context
grep -nE "^(COPY|ADD) .*(\.npmrc|\.pypirc|\.netrc|pip\.conf|settings\.xml|\.env|\.aws/credentials|\.config/gcloud|\.azure/|\.vault-token|\.cargo/credentials|id_(rsa|dsa|ed25519|ecdsa)|service.account.*\.json|\.pem([[:space:]]|$)|\.p12([[:space:]]|$)|kubeconfig)" Dockerfile

# Credentials passed as build args (visible in docker history) — case-insensitive
grep -inE "^ARG .*(TOKEN|KEY|SECRET|PASSWORD)" Dockerfile

# Credentials baked into image env (visible to anyone with the image) — case-insensitive
grep -inE "^ENV .*(TOKEN|KEY|SECRET|PASSWORD)=" Dockerfile
```

If the project needs registry credentials, the Dockerfile must use `RUN --mount=type=secret` and the build invocation must pass the secret:

```bash
docker buildx build --secret id=<id>,src=<host-path> --progress=plain .
```

The `--progress=plain` output should show the secret being consumed inside the right `RUN` step **without printing its value**. If you see the secret content in the log, the `RUN` is leaking it (e.g., via `echo`, `cat`, or shell substitution into a logged command) — that is a build-log leak even when the layer itself is clean. For private Git access, use `--mount=type=ssh` and `docker buildx build --ssh default .`, then run the SSH checks in 4c.

### 4b. Backstop: scan the built image

```bash
docker history test-image --no-trunc
```

Inspect the output for any `ENV` instructions or `COPY` steps that might include `.env` files, API keys, or credentials.

**Note:** `docker history` shows layers of the final exported image only. It will **not** reveal credentials that were `COPY`-ed in an intermediate stage but not carried forward — those files still exist in BuildKit's build cache on the builder host. The static Dockerfile check in 4a is the only way to catch that class of leak. This step is a backstop.

### 4c. SSH forwarding for private Git access

If the Dockerfile uses `RUN --mount=type=ssh`, check what the build can reach before running it:

```bash
# Every key listed here can be used by the RUN --mount=type=ssh step
ssh-add -l

# Host-key checking stays enabled (must return nothing)
grep -nE 'StrictHostKeyChecking[[:space:]=]+no' Dockerfile
```

- `ssh-add -l` should list only the key this build needs. If it lists more, run the build from a dedicated agent (in an interactive terminal, `ssh-agent bash`, then `ssh-add <key-file>`) instead of removing keys from the user's agent.
- The `RUN` that fetches over SSH populates `/root/.ssh/known_hosts` in the same step (for example with `ssh-keyscan`) instead of disabling host-key checking.
- `--ssh default=<key-file>` works only with an unencrypted key file. BuildKit rejects passphrase-protected keys in this form (`this private key is passphrase protected`), so load those into an agent and pass `--ssh default`.

## 5. Layer count

```bash
docker history test-image --format "{{.CreatedBy}}" | wc -l
```

A well-structured image typically has 8-15 layers. Significantly more may indicate missing command consolidation.

## 6. Correct WORKDIR, EXPOSE, and ENTRYPOINT

```bash
docker inspect test-image --format '{{.Config.WorkingDir}}'
docker inspect test-image --format '{{.Config.ExposedPorts}}'
docker inspect test-image --format '{{.Config.Entrypoint}}'
```

Verify:

- `WorkingDir` is set (not empty or `/`)
- `ExposedPorts` documents the expected port
- `Entrypoint` uses exec form (JSON array), not shell form

## 7. .dockerignore exists

Verify a `.dockerignore` file is present alongside the Dockerfile and excludes at minimum:

- `.git/`
- `node_modules/`, `__pycache__/`, or equivalent language artifacts
- `.env` and secret files
- IDE configuration directories

## 8. BuildKit syntax directive

The first line of the Dockerfile must be:

```dockerfile
# syntax=docker/dockerfile:1
```

This enables BuildKit features like cache mounts and `COPY --link`.

# Layer Caching

Docker builds are incremental. Each instruction creates a layer, and Docker reuses cached layers when the inputs have not changed. Understanding cache invalidation rules is critical for fast builds.

## Cache invalidation rules

1. A layer's cache is invalidated when the instruction itself changes or any of its inputs change.
2. When a layer is invalidated, all subsequent layers are also invalidated.
3. For `COPY` and `ADD`, Docker computes a checksum of the files being copied. If the checksum differs from the cached layer, the cache is invalidated.
4. For `RUN`, the cache key is the command string. The cache does not detect changes to files fetched over the network — use cache mounts or explicit version pinning to manage this.

## Layer ordering strategy

Order instructions from least-frequently-changed to most-frequently-changed:

```
1. Base image (FROM)
2. System package installation
3. Dependency manifest (package.json, go.mod, requirements.txt), bind-mounted into the install step
4. Dependency installation (npm ci, go mod download, pip install)
5. Application source code copy
6. Application build
7. Runtime configuration (USER, EXPOSE, ENTRYPOINT)
```

The key insight: dependency manifests change far less often than application source code. By copying and installing dependencies before copying the source, you cache the expensive dependency installation step across most builds.

### Bad ordering

```dockerfile
# Invalidates dependency cache on every source change
COPY . .
RUN npm ci
RUN npm run build
```

### Good ordering

```dockerfile
# Dependencies cached until package.json or lock file changes; the manifest
# is bind-mounted rather than COPY-ed, so it never enters a layer
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=package-lock.json,target=package-lock.json \
    --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN npm run build
```

The bind mount only works for install commands that read the manifest without writing it back (`npm ci`, `pip install -r`, `go mod download`). If the step mutates the lockfile in place (e.g. `npm install` without a lockfile, or `go mod tidy`), `COPY` the manifest instead so the write lands in the image.

## BuildKit cache mounts

Cache mounts persist package manager caches across builds without embedding them in the image layer. They are the single most impactful optimization for dependency installation speed.

### Syntax

```dockerfile
RUN --mount=type=cache,target=<path> <command>
```

### Common cache mount targets

| Package manager | Cache mount target |
|---|---|
| Go modules | `/go/pkg/mod` |
| Go build cache | `/root/.cache/go-build` |
| npm | `/root/.npm` |
| yarn | `/usr/local/share/.cache/yarn` |
| pnpm | `/root/.local/share/pnpm/store` |
| pip | `/root/.cache/pip` |
| Maven | `/root/.m2` |
| Gradle | `/root/.gradle` |
| apt | `/var/cache/apt` and `/var/lib/apt` (both `sharing=locked`) |
| apk (Alpine) | `/etc/apk/cache` (`sharing=locked`, drop `--no-cache`) |

The apk row follows the Alpine wiki's [Local APK cache](https://wiki.alpinelinux.org/wiki/Local_APK_cache) page, not a Docker-verified doc.

### Cache mount with a non-root build user

When the build stage runs as a non-root user, specify `uid` and `gid`:

```dockerfile
RUN --mount=type=cache,target=/home/appuser/.cache/pip,uid=1001,gid=1001 \
    pip install -r requirements.txt
```

### Bind mounts for dependency manifests

Bind-mount `package.json`, `go.mod`/`go.sum`, or `requirements.txt` into the install `RUN` instead of `COPY`-ing them, so the manifest is visible to the command but never written to a layer:

```dockerfile
RUN --mount=type=bind,source=go.mod,target=go.mod \
    --mount=type=bind,source=go.sum,target=go.sum \
    --mount=type=cache,target=/go/pkg/mod \
    go mod download
```

Only do this for install commands that don't write the manifest back (`npm ci`, `pip install -r`, `go mod download`). A command that mutates the lockfile in place needs `COPY` so the change is captured in the image.

### Bind mounts for source

Use bind mounts to avoid copying source files into the build layer when the source is only needed for compilation, not for the final artifact:

```dockerfile
RUN --mount=type=bind,source=.,target=/src \
    --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    cd /src && go build -o /app/server ./cmd/server
```

This keeps the build context out of the layer history entirely.

## COPY --link

`COPY --link` creates a layer that is independent of all previous layers. This means:

- Changing a previous layer does not invalidate a `--link` copy.
- It allows Docker to parallelize layer creation.
- It is particularly useful when copying from a build stage into the runtime stage.

Use `COPY --link` when:

- Copying the final artifact from a build stage: `COPY --from=build --link /app/server .`
- Adding static config files that do not depend on prior layer content.

Do not use `COPY --link` when:

- The `COPY` depends on a directory structure created by a prior `RUN` instruction (the `--link` layer cannot see it).

## Reducing layer count

Combine related commands in a single `RUN` to avoid intermediate layers:

```dockerfile
# Good: single layer, cache mounts keep the apt cache and lists out of the image entirely
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
    apt-get install -y --no-install-recommends \
      ca-certificates \
      curl

# Bad: three layers, apt cache persists in the first layer
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*
```

But do not over-combine. Keep dependency installation and application build in separate `RUN` instructions so that the dependency layer caches independently.

## Debugging cache behavior

Use `docker build --progress=plain` to see which steps are cached (`CACHED`) and which are re-executed. Use `docker history <image>` to inspect layer sizes and identify unexpectedly large layers.

# Multi-Stage Build Patterns

Multi-stage builds separate build-time toolchains from the runtime image. Every language has a common pattern.

## General structure

```dockerfile
# syntax=docker/dockerfile:1

# Stage 1: build
FROM <sdk-image> AS build
WORKDIR /src
RUN --mount=type=bind,source=<dependency-manifest>,target=<dependency-manifest> \
    <install-dependencies>
COPY . .
RUN <compile-or-bundle>

# Stage 2: runtime
FROM <minimal-base> AS runtime
WORKDIR /app
COPY --from=build --chown=appuser:appgroup /src/<artifact> .
USER appuser
ENTRYPOINT ["./artifact"]
```

## Go

Go produces static binaries, so the runtime stage can use `scratch` or distroless.

```dockerfile
# syntax=docker/dockerfile:1

FROM golang:1.23-alpine AS build
WORKDIR /src
RUN --mount=type=bind,source=go.mod,target=go.mod \
    --mount=type=bind,source=go.sum,target=go.sum \
    --mount=type=cache,target=/go/pkg/mod \
    go mod download
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server

FROM gcr.io/distroless/static-debian12:nonroot AS runtime
WORKDIR /app
COPY --from=build --link /app/server .
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["./server"]
```

Key points:

- Use `CGO_ENABLED=0` for a fully static binary when cgo is not needed.
- Use `-ldflags="-s -w"` to strip debug symbols and reduce binary size.
- Cache both `/go/pkg/mod` (downloaded modules) and `/root/.cache/go-build` (compilation cache).
- Bind-mount `go.mod`/`go.sum` into the `go mod download` step instead of `COPY`-ing them; `go mod download` alone doesn't rewrite them. The full source `COPY . .` that follows still brings them into the image for the build step.
- Distroless static images include a built-in `nonroot` user.
- For `GOPRIVATE` modules fetched via Git SSH, use `--mount=type=ssh` instead of baking keys or tokens. Populate `known_hosts` inside the same `RUN`, pair the git-config rewrite with the download so the config does not persist into later stages, and set `GOPRIVATE` inline so `go mod download` skips the public proxy and checksum database (`GOPRIVATE` implies `GONOSUMDB` and `GONOPROXY`):
  ```dockerfile
  RUN --mount=type=ssh \
      --mount=type=cache,target=/go/pkg/mod \
      mkdir -p -m 0700 /root/.ssh && \
      ssh-keyscan -t ed25519 github.com >> /root/.ssh/known_hosts && \
      git config --global url."git@github.com:".insteadOf "https://github.com/" && \
      GOPRIVATE="github.com/your-org/*" go mod download
  ```
  Invoke with `docker buildx build --ssh default .`, which forwards the SSH agent of the shell that runs the build. The `RUN --mount=type=ssh` step can use every key that `ssh-add -l` lists. To expose only this build's key, run `ssh-agent bash` in an interactive terminal, then `ssh-add <key-file>`, and run the build in that shell. To pass an unencrypted key file directly without an agent, use `--ssh default=<key-file>`; BuildKit rejects passphrase-protected keys in this form.

## Node.js

Node.js applications require the Node runtime, so use a slim base for the runtime stage.

```dockerfile
# syntax=docker/dockerfile:1

FROM node:22-alpine AS deps
WORKDIR /src
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=package-lock.json,target=package-lock.json \
    --mount=type=secret,id=npmrc,target=/root/.npmrc,required=false \
    --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev

FROM node:22-alpine AS build
WORKDIR /src
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=package-lock.json,target=package-lock.json \
    --mount=type=secret,id=npmrc,target=/root/.npmrc,required=false \
    --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN npm run build

FROM node:22-alpine AS runtime
WORKDIR /app
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 --ingroup appgroup appuser
COPY --from=deps --chown=appuser:appgroup /src/node_modules ./node_modules
COPY --from=build --chown=appuser:appgroup /src/dist ./dist
COPY --from=build --chown=appuser:appgroup /src/package.json .
USER appuser
EXPOSE 3000
ENTRYPOINT ["node", "dist/index.js"]
```

Invoke with the registry credential mounted only during `npm ci`:

```sh
docker buildx build --secret id=npmrc,src=$HOME/.npmrc .
```

Key points:

- Use a separate `deps` stage that installs only production dependencies (`--omit=dev`).
- Use a `build` stage with all dependencies for compilation/bundling.
- Copy production `node_modules` from the `deps` stage, not the `build` stage.
- Bind-mount `package.json`/`package-lock.json` into `npm ci` instead of `COPY`-ing them — `npm ci` never writes the lockfile back. Use `COPY` instead if the install command can mutate it (e.g. `npm install` without a matching lockfile).
- **Never `COPY .npmrc`** — registry credentials must be mounted with `--mount=type=secret`, not copied into a layer.
- If the project uses a bundler that produces a standalone output (e.g., Next.js standalone mode), copy only the standalone output and skip `node_modules` entirely.

## Python

Python applications use a virtual environment to isolate dependencies. Copy the venv into the runtime stage.

```dockerfile
# syntax=docker/dockerfile:1

FROM python:3.13-slim AS build
WORKDIR /src
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN --mount=type=bind,source=requirements.txt,target=requirements.txt \
    --mount=type=secret,id=pip-conf,target=/etc/pip.conf,required=false \
    --mount=type=cache,target=/root/.cache/pip \
    pip install --no-compile -r requirements.txt
COPY . .

FROM python:3.13-slim AS runtime
WORKDIR /app
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 --ingroup appgroup appuser
COPY --from=build --chown=appuser:appgroup /opt/venv /opt/venv
COPY --from=build --chown=appuser:appgroup /src /app
ENV PATH="/opt/venv/bin:$PATH"
USER appuser
EXPOSE 8000
ENTRYPOINT ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0"]
```

Key points:

- Build the virtual environment in the build stage and copy it whole into the runtime stage.
- Set `PATH` to use the venv in both stages.
- Use `--no-compile` during pip install to skip `.pyc` generation (Python will compile at first import).
- Bind-mount `requirements.txt` into the `pip install` step instead of `COPY`-ing it — `pip install -r` doesn't write the file back.
- For Poetry or PDM projects, export to `requirements.txt` first or use the tool's built-in export.
- For private package indexes, pass `pip.conf` via `--mount=type=secret,id=pip-conf,target=/etc/pip.conf` instead of `COPY pip.conf` (which would leak into a layer). Invoke with `docker buildx build --secret id=pip-conf,src=$HOME/.config/pip/pip.conf .` (XDG path, pip ≥ 19.1) or the legacy `$HOME/.pip/pip.conf`.

## Java

Java applications compile to JARs. Use a JDK for building and a JRE for runtime.

```dockerfile
# syntax=docker/dockerfile:1

FROM eclipse-temurin:21-jdk-alpine AS build
WORKDIR /src
COPY pom.xml .
COPY .mvn .mvn
COPY mvnw .
RUN --mount=type=cache,target=/root/.m2 \
    --mount=type=secret,id=maven-settings,target=/root/.m2/settings.xml,required=false \
    ./mvnw dependency:go-offline -B
COPY src ./src
RUN --mount=type=cache,target=/root/.m2 \
    --mount=type=secret,id=maven-settings,target=/root/.m2/settings.xml,required=false \
    ./mvnw package -DskipTests -B

FROM eclipse-temurin:21-jre-alpine AS runtime
WORKDIR /app
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 -G appgroup appuser
COPY --from=build --chown=appuser:appgroup /src/target/*.jar app.jar
USER appuser
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
```

Key points:

- Use `dependency:go-offline` (Maven) or a Gradle dependency resolution task to cache dependencies before copying source.
- Cache the `.m2` or `.gradle` directory with a cache mount.
- Use a JRE image (not JDK) for the runtime stage.
- For GraalVM native images, the runtime stage can use `scratch` or distroless, similar to Go.
- For private Maven repositories, pass `~/.m2/settings.xml` via `--mount=type=secret,id=maven-settings,target=/root/.m2/settings.xml` instead of `COPY settings.xml`. Invoke with `docker buildx build --secret id=maven-settings,src=$HOME/.m2/settings.xml .`.

## When to add more stages

Add intermediate stages when:

- You need separate dependency resolution (production vs. dev dependencies, as in Node.js).
- You want to run tests in a dedicated stage without polluting the build or runtime stages.
- You are generating assets (CSS, static files) in a separate tool from the main application build.

Name every stage. Never rely on numeric stage indices.

#!/usr/bin/env bash
# Verify Dockerfile build. Run from the project root.
# Usage: bash "<skill-dir>/scripts/verify-build.sh" [--help] [IMAGE_NAME]
# <skill-dir> is the directory that contains this skill's SKILL.md.
set -euo pipefail

usage() {
    echo "Usage: bash \"<skill-dir>/scripts/verify-build.sh\" [--help] [IMAGE_NAME]"
    echo "Run from the project root; <skill-dir> is the directory that contains this skill's SKILL.md."
    echo "Builds the Dockerfile, then reports image size and configured user."
}

if [[ "${1:-}" == "--help" && $# == 1 ]]; then
    usage
    exit 0
fi

if (( $# > 1 )); then
    usage >&2
    exit 2
fi

IMAGE="${1:-verify-build-test}"

echo "Building image..."
docker build -t "$IMAGE" .

echo ""
echo "Image size:"
docker images "$IMAGE" --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

echo ""
echo "User:"
docker inspect "$IMAGE" --format '{{.Config.User}}'