docker-ops

Files (49)

• SKILL.md
• Dockerfile.template · assets/
• compose.template.yaml · assets/
• docker-facts.json · assets/
• compose.md · references/
• debugging.md · references/
• destructive-commands.md · references/
• disk-reclaim.md · references/
• dockerfile.md · references/
• ports-and-networking.md · references/
• providers-and-contexts.md · references/
• supply-chain-and-scanning.md · references/
• vmm-sharing-emulation.md · references/
• check-docker-facts.py · scripts/
• check-image-tags.py · scripts/
• docker-audit.py · scripts/
• docker-doctor.py · scripts/
• Dockerfile · tests/fixtures/bad/
• compose.yaml · tests/fixtures/bad/
• .dockerignore · tests/fixtures/clean/
• Dockerfile · tests/fixtures/clean/
• compose.yaml · tests/fixtures/clean/
• Dockerfile · tests/fixtures/coverage/
• docker-compose.yml · tests/fixtures/coverage/
• docker_stub.py · tests/fixtures/doctor/
• run_doctor.py · tests/fixtures/doctor/
• .dockerignore · tests/fixtures/edge/
• Dockerfile · tests/fixtures/edge/
• compose.yaml · tests/fixtures/edge/
• skip.Dockerfile · tests/fixtures/edge/
• desktop-release-notes.md · tests/fixtures/facts/
• eol-go.json · tests/fixtures/facts/
• eol-nodejs.json · tests/fixtures/facts/
• eol-php.json · tests/fixtures/facts/
• eol-python.json · tests/fixtures/facts/
• releases-colima.json · tests/fixtures/facts/
• releases-compose.json · tests/fixtures/facts/
• releases-gateway_api.json · tests/fixtures/facts/
• releases-helm.json · tests/fixtures/facts/
• releases-kubernetes.json · tests/fixtures/facts/
• releases-lima.json · tests/fixtures/facts/
• releases-podman.json · tests/fixtures/facts/
• releases-trivy_action.json · tests/fixtures/facts/
• releases-wsl.json · tests/fixtures/facts/
• Dockerfile · tests/fixtures/image-tags/
• answers.json · tests/fixtures/image-tags/
• compose.yaml · tests/fixtures/image-tags/
• notes.md · tests/fixtures/image-tags/
• run.sh · tests/

SKILL.md (first lines)

# Docker Operations

Docker on your machine and in your repo: the files you write (Dockerfile, .dockerignore,
compose.yaml) and the engine that runs them. Versions verified 2026-10-07 (Compose v5,
Docker Desktop 4.94, WSL 3.0, Podman 6); `scripts/check-docker-facts.py --live` re-checks
them weekly.

**Why:** the costly Docker mistakes are silent. A secret is copied into a layer, a datastore
listens on every interface, `compose config` pastes credentials into a log, a prune deletes
a volume someone needed. The rules below stop those first.

## Hard rules

1. **Say what is lost before anything destructive, and confirm a sweep.** Removing one
   stopped container the user named is fine on an explicit ask. `docker kill`, any `prune`,
   `compose down -v`, `volume rm`, and anything unscoped (`docker rm -f $(docker ps -aq)`)
   needs a confirmation that names what goes. A sweep counts as a sweep even when
   everything in it is stopped: scope beats state. Tiers: [destructive-commands.md](references/destructive-commands.md).
2. **Never run `docker compose config` bare.** It prints interpolated values and inlines
   `env_file` contents. Use `docker compose config --quiet` to validate, and add
   `--no-interpolate` when you need to read the file.
3. **No secrets in layers.** No `ARG`/`ENV` credentials, no `COPY .env` / `.npmrc` / keys.
   Use `RUN --mount=type=secret,id=x,required=true` (fails loudly when the secret is
   missing) and `--mount=type=ssh`. A later `RUN rm` does not remove a file from the
   earlier layer.
4. **Datastores and debug ports bind to loopback.** Write `127.0.0.1:5432:5432`, never `5432:5432`.
   On Docker Desktop, an unbound port is reachable from your LAN.
5. **Pin scanners and actions by commit SHA.** In March 2026, 76 of trivy-action's 77 tags
   were force-pushed to an infostealer (advisory GHSA-69fq-xp46-6x23). Use
   `aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0`.
   Vetting dependencies is supply-chain-defense's job.
6. **Current bases only.** Node.js 22 is the oldest supported line (20 ended 2026-04-30),
   Python 3.11 (3.10 ended 2026-10-01). Distroless images are `-debian13`. Pin a tag, and
   in production a digest. `assets/docker-facts.json` holds the floors the auditor checks.
7. **Verify a non-root image with `docker inspect --format '{{.Config.User}}'`** (it must be
   set and not `0` or `root`). `docker run img whoami` lies when the image has an ENTRYPOINT.
8. **Never start, stop or reconfigure the engine on the user's behalf.** Report that it is
   down and give the start command. Propose a settings change; don't apply it. A setting
   their admin locked is the admin's call (`docker-doctor.py` reports locks).
9. **`compose.yaml`, no `version:` line.** Compose ignores `version:` and prints a warning.
   Since Compose v5 (2025-12; v3 and v4 were skipped), builds go through Bake.
10. **Run this skill's scripts by path from the project root.** Use
    `python "<skill-dir>/scripts/x.py"`; never `cd` into the skill or call `scripts/x.py`
    relative to the project.

## Routing

| The task | Where |
|---|---|
| Dockerfile, multi-stage, BuildKit, base images, multi-platform | here + [dockerfile.md](references/dockerfile.md) |
| compose.yaml, healthchecks, profiles, watch, secrets | here + [compose.md](references/compose.md) |
| Scanning, SBOM, provenance, signing, digest pins | [supply-chain-and-scanning.md](references/supply-chain-and-scanning.md); vetting packages: supply-chain-defense |
| Which engine am I talking to, contexts, sockets, credential helpers | [providers-and-contexts.md](references/providers-and-contexts.md) |
| Port clashes, host.docker.internal, VPN subnets, reserved ports | [ports-and-networking.md](references/ports-and-networking.md) |
| The VM disk keeps growing | [disk-reclaim.md](references/disk-reclaim.md) |
| Slow bind mounts, VirtioFS, Rosetta, arm64 vs amd64 | [vmm-sharing-emulation.md](references/vmm-sharing-emulation.md) |
| A container that won't start, exits, or can't be debugged | [debugging.md](references/debugging.md) |
| Kubernetes, Helm, Gateway API, ECS | kubernetes-ops |
| A project with a `.ddev/` folder | ddev-ops (its extra services use Compose syntax from here) |
| `.wslconfig`, WSL networking modes, WSL disks in general | windows-ops ([wsl.md](../windows-ops/references/wsl.md)) |
| `npm ci` vs `npm install`, lockfiles inside a RUN | package-manager-ops |
| CI pipelines that build and push | ci-cd-ops |
| Go or Rust build specifics (CGO, static and musl binaries, toolchain caches) | go-ops, rust-ops |

## Tools

```bash
docker build --check .                                       # BuildKit's own checks first (needs the daemon)
python "<skill-dir>/scripts/docker-audit.py" .               # repo: Dockerfiles + Compose (exit 10 = findings)
python "<skill-dir>/scripts/docker-doctor.py" --ports 80,5432   # machine: engine, provider, disk, ports (read-only)
python "<skill-dir>/scripts/check-image-tags.py" --live .     # do the pinned tags exist for amd64+arm64?
python "<skill-dir>/scripts/check-docker-facts.py" --offline  # are this skill's version facts still stated?
```

- `scripts/docker-audit.py` checks Dockerfile families D1-D11 (base pinning and EOL, user,
  secrets, TLS bypasses, package hygiene, instruction semantics, pipes, build context,
  directives, healthcheck tooling, labels) and Compose families C1-C9 (obsolete `version:`,
  build+image squatting, floating tags, literal secrets, published ports, host escapes,
  hardening, readiness, undeclared resources). `--list-checks` shows each check with its
  hadolint / BuildKit / Trivy / Checkov IDs. Suppress a finding inline with
  `# docker-audit ignore=CHECK reason="..." until=YYYY-MM-DD`; a missing reason suppresses
  nothing. `--production` adds digest pins and Compose hardening.
- `scripts/docker-doctor.py` resolves the endpoint (DOCKER_HOST > DOCKER_CONTEXT > the stored
  context), names the provider from the socket or pipe path, and reports: the engine down
  or hung, two providers running, a missing credential helper, a VM disk far bigger than
  what the engine holds, Windows-reserved ports, ports held inside running WSL, admin locks.
  It never starts, prunes or compacts anything.
- `scripts/check-image-tags.py` inventories every FROM / `COPY --from=` / `image:` reference
  (Markdown code fences included). `--live` asks the registries: missing exits 10, uncertain
  (Docker Hub's 429s) exits 7.
- `scripts/check-docker-facts.py` keeps `assets/docker-facts.json` true: `--offline` in PR
  CI, `--live` weekly.

## Dockerfile in one screen

```dockerfile
# syntax=docker/dockerfile:1
FROM node:24-slim AS deps
WORKDIR /app
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,sharing=locked \
    npm ci --omit=dev

FROM node:24-slim
WORKDIR /app
RUN rm -f /etc/apt/apt.conf.d/docker-clean \
 && echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' > /etc/apt/apt.conf.d/keep-cache
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 tini
COPY --link --from=deps /app/node_modules ./node_modules
COPY --chown=node:node . .
USER node
HEALTHCHECK CMD ["node", "healthcheck.js"]
ENTRYPOINT ["tini", "--"]
CMD ["node", "server.js"]
```

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods