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

GitHub

Docker 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, and compose.yaml for 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 ENV or ARG defaults → refuse; use secrets mounts or external secret stores (@vault).

Operational Capabilities & Agent Directives

  1. Pin bases by digest in production Dockerfiles; tag drift (node:20-alpine today ≠ tomorrow) breaks reproducibility and CVE response.
  2. Multi-stage by default: compile in builder; copy only artifacts + prod deps into runner; run as non-root with explicit USER.
  3. Compose readiness: use depends_on.condition: service_healthy with healthchecks that prove application readiness (pg_isready, HTTP /health), not “process started”.
  4. Tune healthcheck start_period + retries: Compose stops startup if dependency goes unhealthy after retries—it does not wait indefinitely.
  5. BuildKit secrets: RUN --mount=type=secret for npm/pip tokens; never COPY .env or ENV TOKEN=.
  6. Idempotent compose: document docker compose up --build vs pull policy; use named volumes for stateful data.
  7. Platform builds: docker buildx build --platform linux/amd64,linux/arm64 when 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

  1. .dockerignore: .git, node_modules, *.pem, .env*, test fixtures.
  2. One process per container; use Compose for sidecars on single host only.
  3. Tag images with git SHA; promote digests to prod manifests (@kubernetes, @github-actions).
  4. Run docker scout cves or @trivy in CI before push.
  5. Prefer read_only: true + tmpfs for stateless services when feasible.
  6. 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_on with service_healthy and healthchecks that reflect real readiness; tune start_period so slow deps are not marked unhealthy during boot. Validate with docker compose config and nginx -t-equivalent (docker build + container health) before declaring success.


Source anchors (research)