0xdarkmatter/claude-mods/docker-ops

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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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).

1. `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.

1. 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

Tools

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

# 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"]

What makes it right: # syntax= on line 1 (anywhere else it is a comment). Bind-mounted manifests for an install that only reads them (keep COPY when the lockfile gets written back). Cache mounts with sharing=locked, and the docker-clean hook removed so the apt cache survives (Debian and Ubuntu images delete it after every install otherwise). Exec-form CMD, so the process gets SIGTERM. A non-root USER. A healthcheck the image can actually run: slim and distroless images ship no curl. Per-language stages, multi-platform builds and base-image choice: dockerfile.md.

.dockerignore at the context root, at least: .git, .env* (then !.env.example), node_modules, *.pem, *.key, build output. Without it, COPY . . ships the history and your secrets, and every commit busts the cache.

Compose in one screen

services:
  web:
    build: .
    image: ghcr.io/acme/web:dev        # registry-qualified, so `compose pull` can't fetch a stranger's image
    ports: ["127.0.0.1:3000:3000"]
    environment:
      SESSION_SECRET: ${SESSION_SECRET:?set SESSION_SECRET}
    depends_on:
      db: {condition: service_healthy}
  db:
    image: postgres:18.6-trixie
    environment: {POSTGRES_PASSWORD_FILE: /run/secrets/db_password}
    secrets: [db_password]
    healthcheck: {test: ["CMD-SHELL", "pg_isready -U postgres"], interval: 5s}
    volumes: [dbdata:/var/lib/postgresql]
volumes: {dbdata: {}}
secrets: {db_password: {file: ./db_password.txt}}

service_healthy needs a healthcheck on the dependency, or Compose fails at start. develop.watch (docker compose watch) replaces most bind-mount dev loops. Profiles, include:, overrides and env precedence are in compose.md.

Destructive commands (summary)

system prune --volumes removes only anonymous volumes. system prune -a removes every image no container uses: the next build re-downloads everything.

Engines in one table

DOCKER_HOST beats DOCKER_CONTEXT, and both beat docker context use. A forgotten DOCKER_HOST in a shell profile is the usual reason "my context is ignored". Two engines running at once fight over ports and /var/run/docker.sock. Docker Desktop 4.59 stopped compacting its WSL data disk, so on Windows the disk only grows: disk-reclaim.md.

References