Docker Compose

--- name: Docker Compose description: Define multi-container applications with proper dependency handling, networking, and volume management. metadata: {"clawdbot":{"emoji":"🐳","requires":{"anyBins":["docker-compose","docker"]},"os":["linux","darwin","win32"]}} ---

depends_on Ready Condition

• depends_on: alone only waits for container start—service likely not ready yet
• Add healthcheck + condition for actual readiness:

depends_on:
  db:
    condition: service_healthy

• Without healthcheck defined on target service, service_healthy fails

Healthcheck start_period

healthcheck:
  test: ["CMD", "pg_isready"]
  start_period: 30s

• start_period: initial grace period—health failures don't count during this time
• Slow-starting services (databases, Java apps) need adequate start_period
• Without it, container marked unhealthy before it finishes initializing

Volume Destruction

• docker compose down preserves volumes
• docker compose down -v DELETES ALL VOLUMES—data loss
• -v often added by habit from tutorials—catastrophic in production
• Named volumes survive down; anonymous volumes deleted on down

Resource Limits in Development

deploy:
  resources:
    limits:
      memory: 512M

• Set limits during development—catches memory issues early
• Unlimited container can consume all host memory—kills other processes
• Copy limits to production config—don't discover limits in prod

.dockerignore

• Without it: node_modules, .git, secrets copied into image
• Mirrors .gitignore syntax—create at same level as Dockerfile
• Large build context = slow builds, large images, potential security issues
• At minimum: .git, node_modules, .env, *.log, build artifacts

Override File Pattern

• docker-compose.yml: base config that works everywhere
• docker-compose.override.yml: auto-loaded, development-specific (mounts, ports)
• Production: docker compose -f docker-compose.yml -f docker-compose.prod.yml up
• Keep secrets and environment-specific config in override files, not base

Profiles for Optional Services

services:
  mailhog:
    profiles: [dev]

• Services with profiles don't start by default—cleaner docker compose up
• Enable with --profile dev
• Use for: test databases, debug tools, mock services, admin interfaces

Environment Variable Precedence

1. Shell environment (highest)
2. .env file in compose directory
3. env_file: directive
4. environment: in compose file (lowest for that var)

• .env must be exactly .env—.env.local not auto-loaded
• Debug with docker compose config—shows resolved values