Docker

Docker — Docker Mastery

Activate When

• User invokes /godmode:docker
• User says "Dockerfile", "docker compose", "container image", "multi-stage build"
• User says "image size", "docker security", "container optimization"
• User needs to containerize an application for the first time
• User wants to optimize an existing Docker setup
• User needs local development environment with Docker Compose
• Pre-ship check identifies Docker configuration issues
• Godmode orchestrator detects Dockerfile anti-patterns during /godmode:review

Workflow

Step 1: Assess Docker Context

Understand the project and its containerization needs:

DOCKER CONTEXT ASSESSMENT:
Project:
  Language/Runtime: <Node.js | Python | Go | Java | Rust | multi-language>
  Framework: <Express | Django | Spring | etc.>
  Build system: <npm | pip | gradle | cargo | make>
  Entry point: <main file or command>

Current Docker state:
  Dockerfile: <exists | missing | multiple>
  Docker Compose: <exists | missing>
  .dockerignore: <exists | missing | incomplete>
  Base image: <image:tag>
  Image size: <current size>
  Build time: <current build time>
  Layers: <number of layers>

Step 2: Dockerfile Best Practices

Create or optimize the Dockerfile using production-grade patterns:

Multi-Stage Build Pattern

# --- Stage 1: Dependencies (cached separately from source code)
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production

# --- Stage 2: Build (compile/transpile source code)
FROM node:20-alpine AS build
WORKDIR /app

Layer Caching Strategy

LAYER CACHING RULES:
| Rule | Why |
|--|--|
| COPY dependency files first | Dependencies change less |
|  | often than source code |
| RUN install BEFORE COPY src | Bust cache only when deps |
|  | actually change |
| Order instructions by change | Least-changing layers first, |
| frequency | most-changing layers last |
| Combine related RUN commands | Fewer layers, smaller image |
| Use .dockerignore | Exclude node_modules, .git, |
|  | test files from build context |

Language-Specific Patterns

MULTI-STAGE BUILD BY LANGUAGE:
| Language | Build Image | Runtime Image | Size |
|--|--|--|--|
| Node.js | node:20-alpine | node:20-alpine | ~120MB |
| Python | python:3.12-slim | python:3.12-slim | ~150MB |
| Go | golang:1.22-alpine | scratch/distroless | ~10MB |
| Rust | rust:1.77-alpine | scratch/distroless | ~5MB |
| Java | eclipse-temurin:21 | eclipse-temurin: | ~200MB |
|  |  | 21-jre-alpine |  |
| .NET | mcr.microsoft.com/ | mcr.microsoft.com | ~100MB |
|  | dotnet/sdk:8.0 | /dotnet/aspnet: |  |
|  |  | 8.0-alpine |  |

Step 3: Docker Compose for Local Development

Set up a complete local development environment:

# docker-compose.yml — Local development
version: "3.9"

services:
  app:
    build:

DOCKER COMPOSE PATTERNS:
| Pattern | Purpose |
|--|--|
| depends_on + health | Start order with readiness check |
| target: development | Use dev stage of multi-stage build |
| bind mount + anon vol | Hot reload without overwriting deps |
| named volumes | Persist data across restarts |
| profiles | Optional services (monitoring, debug) |
| env_file | Keep secrets out of compose file |

Step 4: Image Size Optimization

Reduce image size systematically:

IMAGE SIZE OPTIMIZATION CHECKLIST:
| Technique | Typical Savings |
|--|--|
| Multi-stage build | 50-90% reduction |
| Alpine/distroless base | 60-80% vs debian/ubuntu |
| .dockerignore (exclude .git, | 10-50% build context |
| node_modules, tests, docs) | reduction |
| Combine RUN commands | 5-20% fewer layers |
| Remove package manager cache | 10-50MB savings |
| (rm -rf /var/cache/apk/*) |  |
| --no-install-recommends (apt) | 10-30% package reduction |
| npm ci --only=production | 30-70% node_modules |
| Strip debug symbols (Go/Rust) | 20-40% binary size |
| UPX compression (Go/Rust) | 50-70% binary size |

Step 5: Security Scanning and Hardening

Scan images for vulnerabilities and apply security best practices:

SECURITY SCANNING TOOLS:
| Tool | Command |
|--|--|
| Trivy | trivy image <image:tag> |
| Snyk | snyk container test <image:tag> |
| Docker Scout | docker scout cves <image:tag> |
| Grype | grype <image:tag> |
| Dockle | dockle <image:tag> |

TRIVY SCANNING (recommended):
  # Scan for vulnerabilities
  trivy image --severity HIGH,CRITICAL <image:tag>

Step 6: Docker Networking and Volumes

Configure networking and persistent storage:

DOCKER NETWORKING:
| Network Type | Use Case |
|--|--|
| bridge (default) | Containers on same host communicate |
| host | Container shares host network (no isolation) |
| overlay | Multi-host communication (Swarm/K8s) |
| macvlan | Container gets its own MAC address |
| none | No networking (isolated workloads) |

COMPOSE NETWORKING PATTERNS:
  # Isolated networks for microservices
  networks:
    frontend:          # Public-facing services

Step 7: BuildKit Features and Build Arguments

Use advanced build capabilities:

BUILDKIT FEATURES:
| Feature | Syntax / Usage |
|--|--|
| Enable BuildKit | DOCKER_BUILDKIT=1 docker build . |
| Cache mounts | RUN --mount=type=cache,target=/root |
|  | /.cache/pip pip install -r req.txt |
| Secret mounts | RUN --mount=type=secret,id=mysecret |
|  | cat /run/secrets/mysecret |
| SSH mounts | RUN --mount=type=ssh git clone ... |
| Heredocs | RUN <<EOF |
|  | apt-get update |
|  | apt-get install -y curl |
|  | EOF |
| Multi-platform builds | docker buildx build --platform |

Step 8: Docker Report

  DOCKER CONFIGURATION REPORT
  Dockerfile: <created | optimized | validated>
  Build type: <single-stage | multi-stage>
  Base image: <image:tag>
  Final image size: <size>
  Layers: <N>
  Docker Compose: <created | updated | N/A>
  Services: <list>
  Volumes: <list>
  Networks: <list>
  Security:

Step 9: Commit and Transition

1. Commit Dockerfile: "build(docker): Dockerfile — multi-stage <language> with <base image>"
2. Commit Compose: "build(docker): docker-compose — <N services> for local dev"
3. After Docker setup: "Docker configured. Use /godmode:k8s for Kubernetes deployment or /godmode:deploy to ship."

Key Behaviors

Never ask to continue. Loop autonomously until done.

# Docker diagnostics
docker build --target test -t myapp:test .
docker images myapp --format "table {{.Tag}}\t{{.Size}}"
trivy image --severity CRITICAL,HIGH myapp:latest
docker history myapp:latest --no-trunc | head -20

IF image size > 200MB (Node/Python) or > 50MB (Go/Rust): optimize with multi-stage and alpine. WHEN trivy reports > 0 CRITICAL CVEs: update base image before deploying. IF build time > 5 minutes: audit layer caching order and .dockerignore.

1. Multi-stage builds are non-negotiable. Build stage never appears in final image.
2. Layer caching first. Deps cached separately from source. Saves minutes per build.
3. Security is not optional. Non-root, .dockerignore, vulnerability scanning. No secrets in layers.
4. Compose is for development. Production uses K8s or managed container services.
5. Smaller images = faster + safer. Target the smallest base image for your runtime.
6. BuildKit is the default. Cache mounts, secret mounts, heredocs.
7. .dockerignore before Dockerfile. Missing .dockerignore = bloated images + leaked secrets.

Flags & Options

HARD RULES

• NEVER use latest tag for base images — pin to specific version (e.g., node:20.11-alpine)
• NEVER run containers as root in production — always add a non-root USER directive
• NEVER store secrets in ENV, ARG, or COPY in Dockerfile layers — use BuildKit secret mounts or runtime env
• NEVER use ADD when COPY suffices — ADD has URL fetch and tar extraction side effects
• NEVER skip .dockerignore — without it, .git, node_modules, .env are sent as build context
• ALL production Dockerfiles MUST use multi-stage builds — build tools never appear in the final image
• ALL container images MUST pass vulnerability scanning (Trivy/Snyk) with zero CRITICAL findings before deployment
• ALL images MUST include a HEALTHCHECK directive

Keep/Discard Discipline

KEEP if: image size decreased AND 0 new CVEs AND container starts successfully
DISCARD if: image size increased OR new critical CVE OR container fails to start
Never keep a size optimization that introduces a critical CVE.

Stop Conditions

STOP when: multi-stage + non-root + healthcheck + 0 critical CVEs + size within target.
Targets: Go <50MB, Node <200MB, Python <200MB. Max 10 iterations.
On failure: git reset --hard HEAD~1.

Auto-Detection

1. Scan for Dockerfile*, docker-compose*, .dockerignore
2. Detect language: package.json→Node, pyproject.toml→Python, go.mod→Go, Cargo.toml→Rust
3. Check image quality: FROM tag, USER, HEALTHCHECK, multi-stage. State: missing | unoptimized | production-ready

Output Format

Print on completion: Docker: {image_count} images optimized. Size: {before_size} → {after_size} (-{savings}%). Layers: {layer_count}. Security: {vuln_count} vulnerabilities ({critical} critical). Build: {build_time}. Verdict: {verdict}.

TSV Logging

Log to .godmode/docker-results.tsv:

iteration	image	size_before	size_after	layers	vulns_critical	vulns_high	build_time_s	status

Success Criteria

• Multi-stage builds, Alpine/distroless base, pinned tags, non-root user, HEALTHCHECK.
• .dockerignore excludes .git, node_modules, .env. No secrets in layers.
• Zero critical CVEs. Build cache optimized (deps before source).

Error Recovery