Docker Compose — SKILL.md

---
name: "Docker Compose"
description: "Skill for Docker Compose — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "infrastructure"
agents: ["claude-code", "codex", "gemini"]
tags: ["docker-compose", "infrastructure", "auto-generated"]
---

# Docker Compose

---
name: Docker Compose
description: Use this skill when you need to define and manage multi-container Docker applications using YAML configuration files. Essential for local development environments, microservices orchestration, and simplified container deployment workflows.
metadata:
  author: skynet
  version: 1.0.0
category: infrastructure
---

# Docker Compose

## Core Commands

### Basic Operations
```bash
# Start services defined in docker-compose.yml
docker-compose up

# Start services in background (detached mode)
docker-compose up -d

# Start specific services only
docker-compose up web db

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v

# Stop and remove everything (containers, networks, images)
docker-compose down --rmi all --volumes --remove-orphans
```

### Service Management
```bash
# View running services
docker-compose ps

# View service logs
docker-compose logs
docker-compose logs -f web  # Follow logs for web service
docker-compose logs --tail=50 db  # Last 50 lines from db service

# Execute commands in running containers
docker-compose exec web bash
docker-compose exec db psql -U postgres

# Run one-time commands
docker-compose run web python manage.py migrate
docker-compose run --rm web npm install  # Remove container after run
```

### Build and Update Operations
```bash
# Build or rebuild services
docker-compose build
docker-compose build --no-cache web  # Build without cache

# Pull latest images
docker-compose pull

# Restart services
docker-compose restart
docker-compose restart web  # Restart specific service

# Scale services
docker-compose up -d --scale web=3  # Run 3 instances of web service
```

## Essential docker-compose.yml Structure

### Basic Multi-Service Setup
```yaml
version: '3.8'

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DEBUG=1
      - DATABASE_URL=postgresql://user:pass@db:5432/myapp
    depends_on:
      - db
      - redis
    volumes:
      - .:/app
      - static_volume:/app/static
    networks:
      - app-network

  db:
    image: postgres:13
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - app-network

  redis:
    image: redis:alpine
    networks:
      - app-network

volumes:
  postgres_data:
  static_volume:

networks:
  app-network:
    driver: bridge
```

### Production-Ready Configuration
```yaml
version: '3.8'

services:
  web:
    image: myapp:latest
    restart: unless-stopped
    environment:
      - NODE_ENV=production
    ports:
      - "80:3000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M
```

## Decision Trees

### Choose Configuration Strategy
```
Need multiple environments?
├── Yes → Use .env files + docker-compose.override.yml
│   ├── Development → docker-compose.yml + docker-compose.override.yml
│   ├── Production → docker-compose.yml + docker-compose.prod.yml
│   └── Testing → docker-compose.yml + docker-compose.test.yml
└── No → Single docker-compose.yml with environment variables

Data persistence needed?
├── Yes → Define named volumes or bind mounts
│   ├── Database data → Named volumes
│   ├── Development files → Bind mounts (./src:/app/src)
│   └── Shared data → Named volumes with multiple services
└── No → Use container filesystem (data lost on restart)
```

### Networking Strategy
```
Services need to communicate?
├── Yes → Define custom network
│   ├── Simple setup → Single bridge network
│   ├── Multiple apps → Multiple networks with external: true
│   └── External services → Use external networks
└── No → Use default network

External access needed?
├── Yes → Expose ports (8080:80)
│   ├── Load balancer → Port 80/443
│   ├── Development → High ports (3000:3000)
│   └── Database access → Be careful! (5432:5432)
└── No → Internal communication only
```

## Environment Management

### Using .env Files
```bash
# .env file
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
REDIS_URL=redis://localhost:6379
DEBUG=true
API_KEY=your-secret-key
```

```yaml
# docker-compose.yml
version: '3.8'
services:
  web:
    build: .
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - DEBUG=${DEBUG}
      - API_KEY=${API_KEY}
    # Or use env_file
    env_file:
      - .env
```

### Multiple Environment Files
```bash
# Override for different environments
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# Using environment-specific files
docker-compose --env-file .env.production up -d
```

## Advanced Patterns

### Health Checks and Dependencies
```yaml
services:
  web:
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://localhost:8000/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
  
  db:
    image: postgres:13
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
```

### Init Containers and Setup
```yaml
services:
  db-migration:
    build: .
    command: python manage.py migrate
    depends_on:
      db:
        condition: service_healthy
    restart: "no"
  
  web:
    build: .
    depends_on:
      - db-migration
```

## Troubleshooting

### Common Error Messages and Fixes

**"Port already in use"**
```bash
# Error: bind: address already in use
# Fix: Change port mapping or stop conflicting service
docker-compose ps  # Check what's running
sudo lsof -i :8000  # Find what's using port 8000
# Change port in docker-compose.yml: "8001:8000"
```

**"Service failed to build"**
```bash
# Error: failed to solve with frontend dockerfile.v0
# Fix: Check Dockerfile and build context
docker-compose build --no-cache
docker-compose logs web  # Check build logs
# Ensure Dockerfile exists in build context
```

**"Network not found"**
```bash
# Error: network myapp_default not found
# Fix: Create network or check configuration
docker network ls
docker-compose down
docker-compose up  # Recreates network
```

**"Volume mount failed"**
```bash
# Error: invalid mount config for type "bind"
# Fix: Check file paths and permissions
ls -la ./data  # Verify source path exists
# Use absolute paths or ensure relative paths are correct
# Windows: Use forward slashes or escape backslashes
```

### Debug Commands
```bash
# Validate compose file
docker-compose config

# View effective configuration
docker-compose config --services

# Check resource usage
docker-compose top

# View container processes
docker-compose exec web ps aux

# Inspect networks
docker network inspect $(docker-compose config --services | head -1)_default
```

### Performance Issues
```bash
# Monitor resource usage
docker stats $(docker-compose ps -q)

# Check container logs for errors
docker-compose logs --tail=100 -f

# Restart hanging services
docker-compose restart web

# Clean up resources
docker system prune
docker volume prune
```