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 ```