Docker Compose Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: docker-compose for comprehensive documentation.

Full Stack Example

docker-compose.yml

services: app: build: context: . dockerfile: Dockerfile ports: - "3000:3000" environment: - DATABASE_URL=postgresql://user:pass@db:5432/mydb - REDIS_URL=redis://redis:6379 depends_on: db: condition: service_healthy redis: condition: service_started volumes: - ./src:/app/src # Dev hot reload networks: - app-network

db: image: postgres:16-alpine environment: POSTGRES_USER: user POSTGRES_PASSWORD: pass POSTGRES_DB: mydb volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U user -d mydb"] interval: 5s timeout: 5s retries: 5 networks: - app-network

redis: image: redis:7-alpine volumes: - redis_data:/data networks: - app-network

volumes: postgres_data: redis_data:

networks: app-network: driver: bridge

Common Commands

Start services

docker-compose up -d docker-compose up --build # Rebuild images

Stop

docker-compose down docker-compose down -v # Remove volumes too

Logs

docker-compose logs -f app docker-compose logs --tail=100 app

Execute

docker-compose exec app sh docker-compose exec db psql -U user mydb

Scale

docker-compose up -d --scale app=3

Override for Dev

docker-compose.override.yml (auto-loaded)

services: app: build: target: development volumes: - .:/app - /app/node_modules command: npm run dev

Environment Files

services: app: env_file: - .env - .env.local

When NOT to Use This Skill

Skip this skill when:

• Creating single-container Dockerfiles - use docker skill

• Deploying to production Kubernetes clusters - use kubernetes skill

• Setting up CI/CD workflows - use github-actions skill

• Working with Docker Swarm (deprecated) - use kubernetes skill

• Building Docker images only (no orchestration needed) - use docker skill

Anti-Patterns

Anti-Pattern Problem Solution

Hardcoding ports in compose Port conflicts, inflexible Use ${PORT:-3000}:3000 with env vars

No health checks Services start before ready Add healthcheck and depends_on.condition

Exposing all ports publicly Security risk Bind to 127.0.0.1:port for local only

Using latest tags Unpredictable behavior Pin specific versions postgres:16-alpine

Storing secrets in compose file Secret exposure Use Docker secrets or env files (gitignored)

No resource limits Resource exhaustion Set deploy.resources.limits

Mixing dev and prod config Configuration drift Use docker-compose.override.yml and .prod.yml

Not using named volumes Data loss on recreation Use named volumes for persistence

Services on default network No isolation Create custom networks per tier

Running as root Security vulnerability Set user: "1000:1000" or use Dockerfile USER

Quick Troubleshooting

Issue Diagnosis Fix

Service won't start Dependency not ready Add depends_on with condition: service_healthy

Port already in use Another service using port Change port mapping or stop conflicting service

Database connection refused Service name wrong, network issue Use service name as host: db:5432 not localhost

Changes not reflected Old containers running Run docker-compose down && docker-compose up --build

Volume data not persisting Using anonymous volumes Use named volumes in top-level volumes:

"network not found" Network removed or wrong name Run docker-compose up to recreate networks

Can't connect between services Different networks Put services on same network

Environment variables not working Wrong syntax, not loaded Use ${VAR:-default} and check .env file

"service unhealthy" Health check failing Check docker-compose logs and fix health endpoint

Slow startup on Mac/Windows Volume mounting overhead Use named volumes instead of bind mounts for dependencies

Production Readiness

Security Configuration

docker-compose.prod.yml

services: app: image: myapp:${VERSION:-latest} security_opt: - no-new-privileges:true read_only: true tmpfs: - /tmp cap_drop: - ALL cap_add: - NET_BIND_SERVICE user: "1000:1000" deploy: resources: limits: cpus: '2' memory: 2G reservations: cpus: '0.5' memory: 512M

db: image: postgres:16-alpine environment: POSTGRES_PASSWORD_FILE: /run/secrets/db_password secrets: - db_password volumes: - postgres_data:/var/lib/postgresql/data:Z

secrets: db_password: file: ./secrets/db_password.txt

Health Checks

services: app: healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3000/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s

db: healthcheck: test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER -d $POSTGRES_DB"] interval: 10s timeout: 5s retries: 5

redis: healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 10s timeout: 5s retries: 3

Networking

services: app: networks: - frontend - backend ports: - "127.0.0.1:3000:3000" # Only localhost

db: networks: - backend # No ports exposed externally

nginx: networks: - frontend ports: - "80:80" - "443:443"

networks: frontend: driver: bridge backend: driver: bridge internal: true # No internet access

Logging

services: app: logging: driver: json-file options: max-size: "10m" max-file: "3" labels: "service,environment" labels: - "service=app" - "environment=production"

Or use external logging

app: logging: driver: fluentd options: fluentd-address: localhost:24224 tag: "docker.{{.Name}}"

Restart Policies

services: app: restart: unless-stopped deploy: restart_policy: condition: on-failure delay: 5s max_attempts: 3 window: 120s

db: restart: always

Backup Strategy

services: backup: image: postgres:16-alpine entrypoint: /bin/sh command: -c "pg_dump -h db -U $$POSTGRES_USER $$POSTGRES_DB | gzip > /backups/backup_$$(date +%Y%m%d_%H%M%S).sql.gz" environment: PGPASSWORD_FILE: /run/secrets/db_password secrets: - db_password volumes: - ./backups:/backups depends_on: db: condition: service_healthy profiles: - backup

Testing

docker-compose.test.yml

services: test: build: context: . target: test environment: - DATABASE_URL=postgresql://test:test@db-test:5432/testdb depends_on: db-test: condition: service_healthy command: npm test

db-test: image: postgres:16-alpine environment: POSTGRES_USER: test POSTGRES_PASSWORD: test POSTGRES_DB: testdb tmpfs: - /var/lib/postgresql/data # In-memory for speed

Run tests

docker-compose -f docker-compose.test.yml up --abort-on-container-exit --exit-code-from test

Monitoring Metrics

Metric Target

Container uptime

99.9%

Health check pass rate 100%

Restart count < 1/day

Memory usage < 80% limit

Checklist

• Security opts (no-new-privileges, read_only)

• Resource limits (CPU, memory)

• Health checks on all services

• Internal networks for databases

• Secrets management (not env vars)

• Logging with rotation

• Restart policies configured

• Backup strategy defined

• Test compose file

• Production override file

Reference Documentation

• Networking

• Production Setup