docker
Build reproducible container images with BuildKit, wire Compose service graphs with real readiness gates, and debug networking, volumes, and layer-cache failures agents routinely miss.
SKILL.mdskills/docker/SKILL.md
GitHubDocker Containers & Compose AI Skill Guide (Claude)
Overview & Engine Architecture
Docker packages apps as immutable images and runs them as ephemeral containers on a host engine (containerd/Moby). BuildKit builds images with cache mounts and multi-stage targets; Compose declares multi-container graphs on a single host. Agents should treat images as versioned artifacts (digest-pinned bases), Compose as startup-order contracts (not “wait forever”), and secrets as runtime mounts—never committed layers.
┌─────────────────────────────────────────────────────────────┐
│ Docker build → run loop │
│ │
│ Build (BuildKit / buildx) │
│ ├── Multi-stage: deps → build → runner (non-root) │
│ ├── Cache: lockfiles first; RUN --mount=type=cache │
│ └── SBOM/scan gate before push (pair with @trivy) │
│ │
│ Runtime │
│ ├── Namespaces: net / pid / mnt; USER in final stage │
│ ├── Volumes: named > bind (UID/GID traps on bind) │
│ └── HEALTHCHECK + Compose condition: service_healthy │
│ │
│ Compose orchestration (single host) │
│ ├── depends_on + healthcheck (startup only, not runtime) │
│ └── Internal DNS: <service> on user-defined network │
└─────────────────────────────────────────────────────────────┘
When to use / when not to
Use when
- Authoring Dockerfiles,
.dockerignore, andcompose.yamlfor local/staging parity. - Debugging “works on my machine” via container logs, healthchecks, and network aliases.
- Optimizing image size, layer cache, and non-root runtime hardening.
Do not use when
- You need multi-node scheduling, rolling updates, or cluster RBAC →
@kubernetes/@helm. - The task is host-level syslog/logging-driver plugins that must exist before any container starts on daemon reboot (Compose cannot order daemon-wide plugins) → host OS service instead.
- Someone asks to bake API keys into
ENVorARGdefaults → refuse; use secrets mounts or external secret stores (@vault).
Operational Capabilities & Agent Directives
- Pin bases by digest in production Dockerfiles; tag drift (
node:20-alpinetoday ≠ tomorrow) breaks reproducibility and CVE response. - Multi-stage by default: compile in builder; copy only artifacts + prod deps into
runner; run as non-root with explicitUSER. - Compose readiness: use
depends_on.condition: service_healthywith healthchecks that prove application readiness (pg_isready, HTTP/health), not “process started”. - Tune healthcheck
start_period+ retries: Compose stops startup if dependency goesunhealthyafter retries—it does not wait indefinitely. - BuildKit secrets:
RUN --mount=type=secretfor npm/pip tokens; neverCOPY .envorENV TOKEN=. - Idempotent compose: document
docker compose up --buildvspullpolicy; use named volumes for stateful data. - Platform builds:
docker buildx build --platform linux/amd64,linux/arm64when CI arch ≠ laptop (Apple Silicon → amd64 deploy traps).
Production Example: API + Postgres with real readiness
Dockerfile (excerpt):
# syntax=docker/dockerfile:1
FROM node:20-alpine@sha256:<pin-digest> AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
FROM node:20-alpine@sha256:<pin-digest> AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -S app && adduser -S app -G app
COPY --from=deps /app/node_modules ./node_modules
COPY --chown=app:app dist ./dist
USER app
EXPOSE 3000
HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=3 \
CMD wget -qO- http://127.0.0.1:3000/health || exit 1
CMD ["node", "dist/server.js"]
compose.yaml:
services:
api:
build:
context: .
target: runner
ports: ["3000:3000"]
environment:
DATABASE_URL: postgres://app@db:5432/app
secrets: [db_password]
depends_on:
db:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/health"]
interval: 10s
start_period: 30s
retries: 5
db:
image: postgres:16-alpine@sha256:<pin-digest>
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
POSTGRES_DB: app
secrets: [db_password]
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d app"]
interval: 5s
timeout: 5s
retries: 10
start_period: 30s
volumes: [pgdata:/var/lib/postgresql/data]
secrets:
db_password:
file: ./secrets/db_password.txt # gitignored
volumes:
pgdata:
Validation loop:
docker compose config
docker buildx build -t myorg/api:$(git rev-parse --short HEAD) --target runner .
docker compose up --build -d
docker compose ps
docker inspect --format='{{json .State.Health}}' "$(docker compose ps -q api)"
Technical Troubleshooting Matrix
| Signature | Likely cause | Fix path |
|---|---|---|
Dependency unhealthy, compose aborts startup |
Healthcheck too aggressive vs slow boot | Increase start_period, fix test command, verify port inside container |
connection refused to db:5432 on first boot only |
Short-form depends_on without service_healthy |
Add condition: service_healthy |
| After host reboot, logging driver / syslog race | Engine starts containers without Compose ordering | Do not model engine plugins as Compose services; use host syslog |
permission denied on bind mount |
UID/GID mismatch (USER app vs host root-owned dir) |
Named volume, or chown host path, or align UID |
| Image 2GB+ | Build tools in final stage | Multi-stage; .dockerignore; npm prune --omit=dev |
no matching manifest for linux/amd64 |
arm64-only image on amd64 cluster | buildx --platform or pin correct base |
Secrets in docker history |
ENV/ARG for credentials |
BuildKit secrets; runtime env from orchestrator |
| Nginx/upstream “host not found” at start | Static upstream DNS at boot | Pair with @nginx resolver pattern in frontends |
Best Practices
.dockerignore:.git,node_modules,*.pem,.env*, test fixtures.- One process per container; use Compose for sidecars on single host only.
- Tag images with git SHA; promote digests to prod manifests (
@kubernetes,@github-actions). - Run
docker scout cvesor@trivyin CI before push. - Prefer
read_only: true+ tmpfs for stateless services when feasible. - Document required env vars in README; fail fast in entrypoint if missing.
Limitations
- Compose is not Kubernetes: no PodDisruptionBudgets, no cluster autoscaler, no cross-host networking without Swarm (deprecated path).
- Healthchecks are startup ordering helpers; they do not restart failed dependencies after boot—apps need retry/backoff.
- Rootless Docker and file permission edge cases vary by host OS.
- Stop and ask if registry credentials, prod compose files, or data migration steps are missing.
Related Skills
@kubernetes— production orchestration beyond single-host Compose@github-actions— build/push images with OIDC to cloud registries@nginx— reverse proxy in front of compose stacks@trivy— image vulnerability gates@vault— dynamic secrets instead of compose secret files in prod
Agent Operational Directive
MANDATORY: Pin base image digests for production paths. Never put secrets in image layers or committed compose env. Use
depends_onwithservice_healthyand healthchecks that reflect real readiness; tunestart_periodso slow deps are not marked unhealthy during boot. Validate withdocker compose configandnginx -t-equivalent (docker build+ container health) before declaring success.