<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