{"title": "Docker", "content": "# Docker Build Troubleshooting Guide\n\n## The dlib Compilation Issue\n\nYour Docker build is getting stuck because `dlib` (a computer vision library) needs to be compiled from source, which is extremely resource-intensive and time-consuming.\n\n## Solutions Provided\n\n### 1. Quick Start (Recommended)\n```bash\n./build.sh\n```\nChoose option 2 or 3 for fastest builds.\n\n### 2. Manual Build Options\n\n#### Option A: Optimized Multi-Stage Build (15-20 minutes)\n```bash\ndocker build -t q_app .\n```\n- Uses the new optimized `Dockerfile`\n- Compiles dlib but with better caching\n- Full functionality including face recognition\n\n#### Option B: Fast Build Without Face Recognition (2-3 minutes)\n```bash\ndocker build -f Dockerfile.fast -t q_app .\n```\n- Skips dlib compilation\n- Face recognition features won't work\n- All other features work normally\n\n#### Option C: Minimal Build (1-2 minutes)\n```bash\n# This is handled automatically by build.sh option 3\n```\n\n### 3. If Build Still Fails\n\n#### Increase Docker Resources\n1. Open Docker Desktop\n2. Go to Settings \u2192 Resources\n3. Increase:\n   - Memory to at least 4GB (8GB recommended)\n   - CPU to at least 2 cores (4+ recommended)\n   - Disk space to at least 20GB free\n\n#### Alternative: Use Pre-built Image\n```bash\n# Remove problematic packages from requirements.txt temporarily\ncp requirements.txt requirements.backup.txt\ngrep -v \"dlib\\|face-recognition\" requirements.txt > requirements_temp.txt\nmv requirements_temp.txt requirements.txt\n\n# Build without face recognition\ndocker build -t q_app .\n\n# Restore original requirements\nmv requirements.backup.txt requirements.txt\n```\n\n### 4. Network Issues\nIf you see network-related errors:\n```bash\n# Create the required network\ndocker network create q_app_network\n\n# Then run your build\n./build.sh\n```\n\n### 5. Clean Start\nIf you have build cache issues:\n```bash\n# Clean everything\ndocker system prune -a\ndocker volume prune\ndocker network prune\n\n# Rebuild\n./build.sh\n```\n\n## Understanding the Build Process\n\n### Why dlib Takes So Long\n- `dlib` is a C++ library that needs compilation\n- It includes complex computer vision algorithms\n- Compilation can take 15-30 minutes on average hardware\n- Docker builds are slower than native compilation\n\n### What We've Optimized\n1. **Multi-stage builds**: Separate build and runtime environments\n2. **Better dependency management**: Install packages in optimal order\n3. **Improved caching**: Leverage Docker layer caching\n4. **Alternative builds**: Options without face recognition\n\n## Monitoring Build Progress\n\n### Check Build Progress\n```bash\n# In another terminal while building\ndocker system df\ndocker images\n```\n\n### If Build Seems Stuck\n- Wait at least 30 minutes before canceling\n- Check Docker Desktop for resource usage\n- Look for \"Building wheel for dlib\" message - this is normal and slow\n\n## Production Recommendations\n\n1. **Use CI/CD**: Build images in CI with more resources\n2. **Pre-built base images**: Create base images with dlib pre-compiled\n3. **Alternative libraries**: Consider lighter alternatives to face-recognition\n4. **Microservices**: Separate face recognition into its own service\n\n## Quick Commands Reference\n\n```bash\n# Start with existing image\ndocker-compose up -d\n\n# View logs\ndocker-compose logs --follow\n\n# Stop services\ndocker-compose down\n\n# Check status\ndocker-compose ps\n\n# Rebuild specific service\ndocker-compose build django_server\n\n# Clean restart\ndocker-compose down && docker-compose up -d\n```\n"}