<quick_start>

1. Copy the compose.yml template below for your stack (Postgres, Redis, etc.)
2. Create a .env file with database credentials
3. Run docker compose up -d to start services
4. Use docker compose logs -f to monitor </quick_start>

<success_criteria>

• All services start with docker compose up -d and reach healthy state
• Health checks configured for every database/cache service
• Environment variables externalized to .env (no hardcoded secrets in compose.yml)
• Hot reload working for application code via volume mounts
• docker compose down -v cleanly removes all containers and volumes </success_criteria>

Docker Compose Skill

Local development environments using Docker Compose for multi-service setups.

Quick Start

Common Services

Basic compose.yml

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${DB_USER:-app}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-secret}
      POSTGRES_DB: ${DB_NAME:-app_dev}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-app}"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Essential Commands

# Start services (detached)
docker compose up -d

# Start with logs visible
docker compose up

# View logs
docker compose logs -f [service]

# Shell into container
docker compose exec db psql -U app

# Stop and remove containers
docker compose down

# Stop and remove volumes (full reset)
docker compose down -v

# Rebuild without cache
docker compose build --no-cache

Environment Variables

Create .env file in project root:

# .env
DB_USER=app
DB_PASSWORD=secret
DB_NAME=myapp_dev
REDIS_URL=redis://localhost:6379

Reference in compose.yml:

environment:
  POSTGRES_USER: ${DB_USER:-app}

Health Checks

Always add health checks for service dependencies:

services:
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-app}"]
      interval: 5s
      timeout: 5s
      retries: 5

  app:
    depends_on:
      db:
        condition: service_healthy

Hot Reload Setup

Mount source code for development:

services:
  app:
    build: .
    volumes:
      - .:/app                    # Source code
      - /app/node_modules         # Preserve node_modules
    environment:
      - NODE_ENV=development

Profiles for Optional Services

services:
  mailhog:
    image: mailhog/mailhog
    profiles: ["mail"]
    ports:
      - "8025:8025"

# Start with: docker compose --profile mail up

Reference Files

• reference/compose-patterns.md - Common compose file patterns
• reference/services.md - Database, cache, queue service configs
• reference/networking.md - Ports, networks, volumes
• reference/dev-workflow.md - Development workflow commands

Emit Outcome Sidecar

As the final step, write to ~/.claude/skill-analytics/last-outcome-docker-compose.json:

{"ts":"[UTC ISO8601]","skill":"docker-compose","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"services_configured":[n],"containers_running":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

Use status "partial" if some stages failed but results were produced. Use "error" only if no output was generated.