MyClub/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)

# 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

# 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

# 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

# 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

# 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

# Check current limits
docker-compose config

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

Database Performance Issues

# 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

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend

Database Performance

# 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