Skip to content

sb-dev/openquant / .agents/skills/docker-build-strategies

docker-build-strategies

Flagged

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.

references/layer-caching.md

View on GitHub
# 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.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall