MyClub/DOCS/DOCKER_PERFORMANCE_GUIDE.md

# Docker Performance Optimization Guide

## Summary of Enhancements

### 🚀 Build Performance
- **BuildKit Cache Mounts**: Added persistent caching for Go modules, Go build cache, and npm cache
- **Layer Optimization**: Improved layer ordering to maximize cache hits
- **Build Arguments**: Added inline cache support for better CI/CD performance
- **Binary Optimization**: Added `-ldflags="-w -s"` for smaller Go binaries (~30% reduction)

### 📊 Resource Management
- **CPU Limits**: Set appropriate limits and reservations for each service
  - Backend: 2 CPUs max, 0.5 reserved
  - Frontend: 1 CPU max, 0.25 reserved
  - Database: 2 CPUs max, 0.5 reserved
- **Memory Limits**: Prevents OOM issues and resource contention
  - Backend: 1GB max, 256MB reserved
  - Frontend: 512MB max, 128MB reserved
  - Database: 2GB max, 512MB reserved

### 🗄️ Database Optimization
- **Postgres Tuning**: Production-grade configuration
  - `shared_buffers=256MB` - Memory for caching
  - `effective_cache_size=1GB` - Query planner optimization
  - `work_mem=2621kB` - Per-operation memory
  - `max_connections=200` - Connection pool sizing
  - `checkpoint_completion_target=0.9` - Smoother checkpoints
  - `wal_buffers=16MB` - Write-ahead log buffering
  - `random_page_cost=1.1` - SSD-optimized
- **tmpfs Mounts**: Fast temporary storage for `/tmp` and `/var/run/postgresql`
- **Shared Memory**: 256MB for PostgreSQL operations

### 🔄 Startup Optimization
- **Parallel Startup**: Frontend no longer waits for backend health check
- **Faster Health Checks**: Database checks every 5s (was default)

## Usage

### Enable BuildKit (Required)
```powershell
# Set environment variable for BuildKit
$env:DOCKER_BUILDKIT=1
$env:COMPOSE_DOCKER_CLI_BUILD=1

# Or add to your PowerShell profile
Add-Content $PROFILE "`n`$env:DOCKER_BUILDKIT=1"
Add-Content $PROFILE "`$env:COMPOSE_DOCKER_CLI_BUILD=1"
```

### Build with Cache
```powershell
# First build (creates cache)
docker-compose build

# Subsequent builds (uses cache, much faster)
docker-compose build

# Force rebuild without cache
docker-compose build --no-cache
```

### Resource Monitoring
```powershell
# View resource usage
docker stats

# View specific service
docker stats myclub-backend myclub-frontend myclub-db
```

## Performance Benchmarks

### Build Times (Typical)
- **Cold build** (no cache): ~5-8 minutes
- **Warm build** (with cache, no code changes): ~10-30 seconds
- **Incremental build** (small code changes): ~30-60 seconds

### Memory Usage (Expected)
- **Backend**: ~100-300MB during normal operation
- **Frontend**: ~50-100MB (nginx is lightweight)
- **Database**: ~200-800MB depending on data size

## Advanced Optimizations

### Production Deployment
For production, consider:
1. Using multi-stage builds with smaller base images
2. Enabling compression in nginx
3. Adding a reverse proxy (nginx/traefik) in front
4. Using external managed database service

### CI/CD Integration
```yaml
# Example GitHub Actions with cache
- name: Build with cache
  uses: docker/build-push-action@v4
  with:
    context: .
    cache-from: type=gha
    cache-to: type=gha,mode=max
```

### Windows-Specific Notes
- **WSL2 Backend**: Ensure Docker Desktop uses WSL2 for better performance
- **File Watching**: May be slower on Windows; consider using polling
- **Drive Mounting**: Use WSL2 filesystem for better I/O performance

## Troubleshooting

### Slow Builds
```powershell
# Check if BuildKit is enabled
docker buildx version

# Clear build cache if needed
docker builder prune -a

# Check disk space
docker system df
```

### High Memory Usage
```powershell
# Check current limits
docker-compose config

# Adjust limits in docker-compose.yml deploy.resources section
```

### Database Performance Issues
```powershell
# Connect to database
docker exec -it myclub-db psql -U postgres -d fotbal_club

# Check current settings
SHOW shared_buffers;
SHOW effective_cache_size;

# Monitor queries
SELECT * FROM pg_stat_activity;
```

## Monitoring Performance

### View Logs
```powershell
# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend
```

### Database Performance
```powershell
# Execute inside container
docker exec -it myclub-db psql -U postgres -d fotbal_club

# Analyze slow queries
SELECT query, calls, total_time, mean_time 
FROM pg_stat_statements 
ORDER BY mean_time DESC 
LIMIT 10;
```

## Next Steps

1. **Monitor**: Use `docker stats` to verify resource usage is within limits
2. **Tune**: Adjust PostgreSQL settings based on your workload
3. **Profile**: Identify bottlenecks using application profiling tools
4. **Scale**: Consider horizontal scaling for production workloads