docker

· Write/review Dockerfiles, Compose, OCI/Podman/BuildKit builds, signing, hardening. Triggers: 'docker', 'dockerfile', 'podman', 'buildkit', 'buildah', 'skopeo', 'containerd'. Not for K8s manifests (u

SKILL.md

GitHub

Docker & Containers: Production Infrastructure

Write, review, and architect Dockerfiles, Compose stacks, and container workflows - from single-service dev setups to multi-arch production pipelines with image signing and compliance gates. The goal is minimal, secure, reproducible images that a team can maintain and a QSA can audit.

Target versions: October 2026 snapshot. Read references/target-versions.md before pinning Docker, Compose, BuildKit, containerd, Podman, Buildah, or runc.

This skill covers Dockerfiles, Compose, container hardening, supply chain, registry/CI patterns, and runtime migration across Docker, Podman, Buildah, Skopeo, and containerd.

When to use

  • Writing or reviewing Dockerfiles (single or multi-stage)
  • Setting up Docker Compose stacks (dev, staging, production)
  • Optimizing image size, build speed, or layer caching
  • Hardening containers for production or compliance
  • Setting up image signing, SBOM generation, or vulnerability scanning
  • Containerizing AI/ML workloads (Model Runner, GPU passthrough, model serving)
  • Migrating from Docker to Podman or building with Buildah
  • Reviewing container security posture for PCI-DSS 4.0 or SOC 2
  • Troubleshooting container networking, volume, or build issues
  • Using docker init to scaffold a new project

When NOT to use

  • Kubernetes manifests, Helm charts, cluster architecture (use kubernetes)
  • CI/CD pipeline design (use ci-cd)
  • Security audits of application code (use security-audit)
  • Infrastructure provisioning with Terraform (use terraform)

AI Self-Check

AI tools consistently produce the same Docker mistakes. Before returning any generated Dockerfile or Compose file, verify against this list:

  • Multi-stage build used when the app has a build step (TypeScript, Go, Rust, Java, C/C++)
  • Dependencies copied and installed BEFORE source code (layer caching)
  • Final image is slim/distroless/scratch - no build tools, no package caches
  • USER directive present - container does NOT run as root
  • No secrets in ENV, ARG, or COPY - use --mount=type=secret or runtime injection
  • Production base image resolved to a SHA256 digest; illustrative major/minor tags in templates must be resolved before release
  • Long-running production services have a meaningful health probe in the image or orchestrator; one-shot jobs use exit status
  • .dockerignore exists and excludes .git, node_modules, .env, secrets, __pycache__, test fixtures, etc.
  • No ADD for local files (use COPY - ADD auto-extracts and fetches URLs)
  • Compose: no version: field (obsolete, ignored, and emits a deprecation warning in current Compose - omit it)
  • Compose: depends_on uses condition: service_healthy, not bare ordering
  • Compose: resource limits set on production services
  • Package caches cleaned in same layer: --no-cache (apk), rm -rf /var/lib/apt/lists/* (apt). For pip: use --mount=type=cache OR --no-cache-dir, not both.
  • CMD uses exec form (JSON array), not shell form: CMD ["node", "app.js"] not CMD node app.js
  • HEALTHCHECK uses available tools: probe command uses a binary present in the final image (wget in Alpine, curl in Debian, none in scratch/distroless - use the app's own health endpoint)
  • Engine/Compose syntax checked: Dockerfile, Compose, BuildKit, and runtime flags match the installed versions
  • Image provenance considered: base images, registries, tags, SBOMs, and signatures are handled where risk warrants
  • Cross-cutting agent hygiene applied - see references/agent-hygiene.md

Performance

  • Order Dockerfile layers from stable to volatile and use cache mounts for package-manager caches where BuildKit is available.
  • Keep build contexts small with .dockerignore; accidental monorepo contexts dominate build time.
  • Use multi-stage builds and slim runtime images, but measure startup and debug needs before stripping tools aggressively.

Best Practices

  • Pin base image digests for sensitive workloads and track rebuild cadence for security updates.
  • Run as non-root and drop capabilities unless the workload genuinely needs them.
  • Preview prune and volume-removal commands; persistent data must never be collateral cleanup.

Workflow

Copy this checklist and track progress:

  • Step 1: Domain identified
  • Step 2: Context gathered (runtime, environment, base image, secrets, compliance)
  • Step 3: Dockerfile, Compose, or config built
  • Step 4: Validation clean (on any failure, fix and return to Step 3)
  • Production Checklist and AI Self-Check passed

Step 1: Determine the domain

Based on the request:

  • "Write a Dockerfile" / "containerize this app" -> Dockerfile
  • "Set up docker compose" / "multi-service stack" -> Compose
  • "Harden this" / "make PCI compliant" / "scan for vulnerabilities" -> Security
  • "Sign images" / "generate SBOM" / "CI pipeline" -> Registry & CI
  • "Use Podman" / "rootless containers" / "daemonless builds" -> Runtimes
  • "Review this Dockerfile/compose" -> Apply production checklist + AI self-check

Step 2: Gather context

Before writing anything, determine:

  • Application type: language, framework, build system
  • Runtime: Bun, Node.js, Python, Go, Rust, Java - determines base image and build pattern
  • Environment: dev (hot reload, debug) vs production (minimal, hardened)
  • Base image: Alpine (small, musl) vs Debian-slim (glibc compat) vs distroless (no shell) vs Chainguard (zero-CVE) vs scratch (static binaries)
  • Secrets: how are they injected? (env vars, mounted files, Docker secrets, vault)
  • Compliance: PCI CDE? Regulated? What scanning/signing is required?
  • Target registry: Docker Hub, GHCR, private registry, OCI-compliant?
  • AI/ML: GPU workload? Model serving? Docker Model Runner?

Step 3: Build

Follow the domain-specific section below. Before finishing, run Step 4, the ## Production Checklist, and the AI self-check.

Step 4: Validate

On any failure, fix it, return to Step 3, and rerun from docker build --check until all checks pass and no unaccepted HIGH/CRITICAL findings remain. Report any tool that was unavailable.

# Dockerfile
docker build --check .                # lint without building
docker build -t test-build .          # Use --no-cache only when investigating stale cache or clean-build reproducibility
docker history test-build --format "{{.Size}}\t{{.CreatedBy}}" | head -15

# Compose
docker compose config                 # validate and render
docker compose --dry-run up           # dry-run startup (Compose v5)

# Security (Trivy default; Grype or Docker Scout if the repo already uses them)
if command -v trivy >/dev/null; then
  trivy image --severity HIGH,CRITICAL --exit-code 1 <image>   # use v0.74.0+; never v0.69.4-6
else
  echo "trivy not installed: image scan NOT run; report it as unverified"
fi
syft <image> -o spdx-json             # generate SBOM
cosign verify --key <key> <image>     # verify signature

Dockerfile

Read references/dockerfile-patterns.md for complete, production-ready Dockerfile templates (Node.js/Bun, Python, Go, Rust, static site) and BuildKit syntax reference.

Base image selection

  • Need a shell or package manager: use slim Debian or Ubuntu bases.
  • Need the smallest static runtime: use distroless or scratch.
  • Need a hardened minimal userspace: use Chainguard or another verified Wolfi-style base.
  • Keep builders and runtimes separate; golang, rust, and other heavy toolchain images stay in build stages only.

See references/dockerfile-patterns.md for the actual language-by-language base recommendations and templates.

Key patterns

Multi-stage builds - the non-negotiable pattern for any compiled or transpiled language:

# syntax=docker/dockerfile:1
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

FROM gcr.io/distroless/nodejs22-debian12
WORKDIR /app
COPY --from=build --chown=1001:1001 /app/dist ./dist
COPY --from=build --chown=1001:1001 /app/node_modules ./node_modules
USER 1001
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD ["node", "-e", "fetch('http://localhost:3000/health').then(r=>r.ok||process.exit(1)).catch(()=>process.exit(1))"]
CMD ["dist/index.js"]

BuildKit features (require # syntax=docker/dockerfile:1 or DOCKER_BUILDKIT=1):

  • Cache mounts: RUN --mount=type=cache,target=/root/.npm npm ci - persists package cache across builds
  • Secret mounts: RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci - secrets never baked into layers
  • Heredocs: multi-line scripts without backslash hell
RUN <<EOF
set -e
apt-get update
apt-get install -y --no-install-recommends ca-certificates
rm -rf /var/lib/apt/lists/*
EOF
  • --check flag: docker build --check . validates Dockerfile without building (dry-run lint)
  • SLSA provenance: docker build --provenance=true --sbom=true . attaches attestations

docker init: scaffolds Dockerfile + compose.yaml + .dockerignore. Good starting point, always review.

What NOT to write

  • COPY . . before dependency install (busts cache on every source change)
  • ADD for local files (use COPY - ADD is only for auto-extracting .tar.gz archives into the image)
  • MAINTAINER (deprecated - use LABEL maintainer="...")
  • RUN cd /dir && ... (use WORKDIR /dir)
  • Separate RUN for each package install (chain with &&)
  • chmod 777 on anything
  • Secrets in ARG or ENV
  • FROM node:latest or FROM python (unpinned)
  • ENTRYPOINT + CMD together unless ENTRYPOINT is the binary and CMD is overridable default args (e.g., ENTRYPOINT ["/app"] + CMD ["--config", "/etc/app.yaml"])

Compose

Read references/compose-patterns.md for complete Compose v5 templates (web+db, dev override, production hardened, AI/ML stack) and network/volume patterns.

Compose v5

  • Do not use the old version: field.
  • Expect Bake-based builds, watch, dry-run validation, and newer model-oriented service wiring.
  • Keep dev and prod concerns separate; override files are still the sane default.
  • Treat healthchecks and dependency readiness as normal Compose design, not optional extras.

Key patterns

Dev/prod separation with override files:

# compose.yaml (base)
services:
  app:
    image: myapp:1.0.0
    healthcheck:
      test: ["CMD-SHELL", "wget -qO /dev/null http://localhost:3000/health || exit 1"]
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3

# compose.override.yaml (dev - auto-loaded)
services:
  app:
    build: .
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      NODE_ENV: development
    ports:
      - "9229:9229"
    command: bun run dev

Secrets: use top-level secrets: with file: or external: true, reference via _FILE env convention (e.g., POSTGRES_PASSWORD_FILE: /run/secrets/db_pass). Never hardcode secrets in environment:. See references/compose-patterns.md for the full template with secret wiring.

Health-gated dependencies: use depends_on: with condition: service_healthy - bare depends_on is ordering only, no readiness guarantee. Exception: dependencies that cannot expose a healthcheck (such as Model Runner provider services); comment the exception inline.

Compose anti-patterns

  • version: "3.8" - dead field, remove it
  • container_name on every service (breaks docker compose up --scale)
  • restart: always without healthcheck (infinite restart of broken containers)
  • network_mode: host when port mapping works (replace with a user-defined bridge network and explicit ports: mapping)
  • depends_on without condition: (ordering only, no readiness)
  • volumes: mounting entire project dir in production (dev pattern leak)
  • privileged: true on a compose service instead of the host LXC
  • 20+ inline environment: entries (use env_file:)

Security

Read references/security-and-compliance.md for the full PCI-DSS 4.0 container requirements mapping, CVE reference, runtime hardening patterns, and scanning tool comparison.

Critical vulnerabilities (2025-2026)

The full CVE table (Docker Desktop, runc, Trivy, Model Runner, BuildKit, Engine, Podman, go-archive) with impacts and fixed versions lives in references/security-and-compliance.md; read it when reviewing versions or answering a CVE question.

Action items: upgrade runc to >= 1.4.0, BuildKit to >= 0.33.1, Docker Desktop to >= 4.71.0 (prefer the current 4.93.0 snapshot), Docker Engine to >= 29.8.2, Podman to >= 6.1.3 or 5.8.8, never pull Trivy v0.69.4/5/6. Pin ALL CI tool images to SHA256 digests.

Hardened Compose baseline

Every production service should start from this, relax only what's needed:

services:
  app:
    image: myapp:1.0.0          # pinned, never :latest
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add: []                 # add ONLY what's needed (see note below)
    tmpfs:
      - /tmp
    user: "1001:1001"
    healthcheck:
      test: ["CMD-SHELL", "wget -qO /dev/null http://localhost:8080/health || exit 1"]
      interval: 30s
      timeout: 5s
      start_period: 15s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

cap_drop: ALL warning: many images (LSIO, HOTIO, official redis/postgres, anything using gosu/setpriv/su-exec) start as root and drop privileges at runtime. They need at minimum cap_add: ["SETUID", "SETGID"], and images that chown files at startup also need "CHOWN". Always read the image's entrypoint to determine required capabilities before applying blanket drops. Blind cap_drop: ALL with empty cap_add causes CrashLoopBackOff. See the security-audit skill's "No blanket capability drops" rule for detailed guidance.

For a hardened Dockerfile pattern, see references/dockerfile-patterns.md (Language Templates section).

Supply chain security

  • Sign images with cosign (Sigstore): cosign sign --key cosign.key <image>@<digest>
  • Generate SBOMs at build time: syft <image> -o spdx-json
  • Verify at deploy: cosign verify --key cosign.pub <image>@<digest>
  • Pin CI tool images to SHA256 digests. Mutable tags are a proven attack vector (Trivy March 2026, tj-actions/reviewdog March 2025).
  • Rescan published images on a schedule with the CI scanner or registry-side scanning.
  • Trivy: use v0.74.0+ from official releases for new pins. v0.69.3 was the March 2026 rollback version. v0.69.4-6 contained credential-stealing malware. If any CI pipeline ran compromised Trivy between March 19-23, 2026, rotate ALL secrets.

PCI-DSS 4.0 container requirements (summary)

PCI-DSS 4.0 is the only active version. Key container-specific requirements:

  • Req 1: Network segmentation - use user-defined bridge networks, internal: true for backend services, never expose CDE containers on default bridge
  • Req 2.2: Harden containers - non-root, drop caps, read-only rootfs, one process per container
  • Req 4: Encrypt transmissions - TLS between CDE containers in Compose (mount certs, use TLS-enabled images, or front with a TLS-terminating reverse proxy)
  • Req 5.2/5.3: Immutable images (deploy by digest), Falco for runtime detection
  • Req 6.3: Vulnerability scanning on every image before deployment (Docker Scout, Grype, Trivy v0.74.0+)
  • Req 6.3.2: SBOM for every production image
  • Req 8.6.2: No hardcoded secrets in images, compose files, or env vars
  • Req 10: Audit logging - container stdout/stderr to immutable log store
  • Req 11.5: Image digest pinning + Falco = FIM for containers

Full mapping in references/security-and-compliance.md.

Registry & CI

CI pipeline pattern

  • Build with docker build --check first, then buildx with provenance and SBOM output.
  • Scan before deploy, sign by digest, and keep an SBOM artifact even if the registry also stores one.
  • Pin CI-side tools and actions to immutable digests, not mutable tags.

Docker Model Runner (AI/ML)

Docker Model Runner (Engine 29.x, Desktop 4.50+) serves AI models via OpenAI/Ollama-compatible APIs:

# Compose integration with Model Runner
services:
  model:
    provider:
      type: model
      options:
        model: ai/llama3.2:3B-Q4_K_M
  agent:
    build: .
    environment:
      OPENAI_BASE_URL: http://model/v1

GPU containers: use deploy.resources.reservations.devices with capabilities: [gpu]. Start shm_size at 16gb for single GPU, 32gb for multi-GPU (vLLM needs shared memory for tensor ops). See references/compose-patterns.md for the full AI/ML stack template.

Production Checklist

See AI Self-Check above for the full build-time checklist (Dockerfile correctness, Compose structure, layer caching, secrets, non-root user, healthchecks, base image pinning). The items below cover deploy-time and operational additions only.

Deploy-time additions

  • runc >= 1.4.0 (CVE-2025-31133/52565/52881 patched)
  • BuildKit >= 0.33.1 (includes CVE-2026-15793, CVE-2026-33747/33748, and CVE-2026-93318 fixes)
  • Docker Desktop >= 4.71.0 (adds CVE-2026-5817/5843 Model Runner container-to-host RCE fixes; see the CVE table in references/security-and-compliance.md for the earlier CVE-2025-9074 and CVE-2026-28400 floors)
  • Trivy v0.74.0+ from official releases (v0.69.4-6 COMPROMISED)
  • Images signed with cosign, verified at deploy
  • SBOM generated for every production image
  • Vulnerability scanning in CI (Docker Scout, Grype, or Trivy v0.74.0+)
  • CI tools pinned to SHA256 digests (not mutable tags)
  • Base images rebuilt/updated regularly (weekly minimum)
  • Separate override files for dev/prod
  • Logging config with rotation (max-size, max-file)
  • read_only: true + no-new-privileges + cap_drop: ALL on production services

Compliance (PCI-DSS 4.0)

  • Containers run as non-root with minimal capabilities (Req 2.2)
  • Read-only root filesystem, one process per container (Req 2.2)
  • Images scanned for vulnerabilities before deployment (Req 6.3)
  • SBOM generated for every CDE image (Req 6.3.2)
  • No hardcoded secrets in images or compose files (Req 8.6.2)
  • Image digests pinned for immutability (Req 5/11.5)
  • Container logs shipped to immutable SIEM (Req 10)
  • Runtime detection in place (Falco/Tetragon) (Req 5.2/5.3)
  • Registry access audit-logged (Req 10.4.1.1)
  • Base images from trusted, verified sources (Req 6.2.1)

Reference Files

  • references/dockerfile-patterns.md - Dockerfile templates and build patterns
  • references/compose-patterns.md - Compose patterns and common stack layouts
  • references/security-and-compliance.md - full 2025-2026 CVE table, Trivy compromise lessons, scanning and signing, container hardening, compliance guidance, and safe public custom image publishing
  • references/alternative-runtimes.md - Podman, Buildah, Skopeo, and related runtime patterns
  • references/target-versions.md - October 2026 version snapshot for Docker, Compose, BuildKit, containerd, Podman, Buildah, and runc

Output Contract

See references/output-contract.md for the full contract.

  • Skill name: DOCKER
  • Deliverable bucket: audits
  • Mode: conditional. When invoked to analyze, review, audit, or improve existing repo content, apply the reporting size and evidence rules in references/output-contract.md and write the deliverable to docs/local/audits/docker/<YYYY-MM-DD>-<slug>.md. When invoked to answer a question, teach a concept, build a new artifact, or generate content, respond freely without the contract.
  • Severity scale: P0 | P1 | P2 | P3 | info (see shared contract; only used in audit/review mode).

Related Skills

  • kubernetes - for deploying containers to K8s clusters. Docker builds the image; kubernetes deploys it. Dockerfile optimization belongs here; K8s manifests belong there.
  • ci-cd - for pipeline design that builds and pushes images. Docker skill covers the Dockerfile and Compose patterns; ci-cd covers the pipeline stages around them.
  • security-audit - for auditing container images, scanning for CVEs, and supply chain risks. Docker skill covers hardening best practices; security-audit runs the actual audit.
  • ansible - can manage containers via community.docker, but image building and Compose design belong here.
  • databases - for database containers in Docker Compose. Docker skill owns the Compose pattern; databases skill owns the engine tuning within the container.
  • git - for git tags and version control. Docker skill handles container image tagging; git handles git tags and release workflows.

Rules

  1. Resolve production images to digests. Template tags illustrate image families; they are mutable and do not establish reproducibility.
  2. Multi-stage builds for compiled/transpiled languages. Build tools do not belong in production images.
  3. Non-root user. Every production container must run as non-root (numeric UID for K8s compat).
  4. Meaningful service healthchecks. Use Dockerfile, Compose, or orchestrator probes for long-running services; use exit status for one-shot jobs and document external monitoring.
  5. Pin CI tools to SHA256 digests. Mutable tags are compromised supply chain vectors (Trivy CVE-2026-33634 March 2026, tj-actions CVE-2025-30066 (upstream: reviewdog CVE-2025-30154) March 2025).
  6. Trivy v0.74.0+ for new pins. v0.69.3 was the March 2026 rollback version; v0.69.4-6 contained credential-stealing malware. If you ran it, rotate secrets.
  7. Resource limits on production containers. Memory and CPU limits prevent noisy neighbors and OOM cascading.