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