Docker

---
name: Docker & Docker Compose
description: Container orchestration, multi-service development, and deployment patterns
---

# Docker & Docker Compose

## Dockerfile Best Practices

### Multi-Stage Build
```dockerfile
# Stage 1: Build
FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Stage 2: Runtime
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### Layer Optimization
```dockerfile
# Copy dependencies first (cacheable)
COPY requirements.txt .
RUN pip install -r requirements.txt

# Then copy frequently changing source code
COPY . .
```

## Docker Compose

### Service Definition
```yaml
version: "3.8"
services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://...
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:
```

### Network Modes
```yaml
services:
  app:
    networks:
      - frontend
      - backend

  db:
    networks:
      - backend  # Not accessible from frontend

networks:
  frontend:
  backend:
```

## Essential Commands

```bash
# Lifecycle
docker-compose up -d              # Start detached
docker-compose down               # Stop and remove containers
docker-compose down -v            # Also remove volumes (clean slate)

# Development
docker-compose build              # Rebuild images
docker-compose build --no-cache   # Force full rebuild
docker-compose up --build         # Build and start
docker-compose restart api        # Restart single service

# Debugging
docker-compose logs -f api        # Follow logs
docker-compose logs --tail 50     # Last 50 lines
docker-compose exec api bash      # Shell into container
docker-compose ps                 # List running containers

# Cleanup
docker system prune -a            # Remove all unused resources
docker volume prune               # Remove unused volumes
```

## Health Checks

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

## Environment Variables

```yaml
# From file
env_file:
  - .env
  - .env.local

# Inline
environment:
  - DEBUG=false
  - DATABASE_URL=${DATABASE_URL}  # From shell
```

## Volume Mounts

```yaml
volumes:
  # Named volume (persistent)
  - postgres_data:/var/lib/postgresql/data

  # Bind mount (development)
  - ./app:/app/app:ro   # Read-only source mount

  # Anonymous volume
  - /app/node_modules   # Exclude from bind mount
```

## This Project
```bash
# Start all services
docker-compose up -d

# Run tests
docker-compose exec -T api pytest tests/ -q

# View logs
docker-compose logs -f api worker
```

Services: api, worker, beat, db, redis, rabbitmq, flower