Create docker/readme.md

docker/readme.md

@@ -0,0 +1,316 @@
+# BackgroundFX Pro Docker Deployment
+
+This directory contains Docker configurations for deploying BackgroundFX Pro in various environments.
+
+## Quick Start
+
+### Prerequisites
+
+- Docker 20.10+ installed
+- Docker Compose 2.0+ installed
+- NVIDIA Docker runtime (for GPU support)
+- At least 16GB RAM
+- 20GB+ free disk space
+
+### GPU Deployment (Recommended)
+
+```bash
+# Build and run with GPU support
+make build
+make run
+
+# Or using docker-compose directly
+docker-compose up -d backgroundfx-gpu
+```
+
+Access the application at http://localhost:7860
+
+### CPU-Only Deployment
+
+```bash
+# Build and run CPU version
+make build-cpu
+make run-cpu
+
+# Or using docker-compose
+docker-compose --profile cpu up -d backgroundfx-cpu
+```
+
+Access at http://localhost:7861
+
+## Available Docker Images
+
+### 1. GPU Image (Dockerfile)
+- **Base**: nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu20.04
+- **Features**: Full GPU acceleration, all models supported
+- **Use case**: Production deployment with NVIDIA GPU
+
+### 2. Production Image (Dockerfile.prod)
+- **Type**: Multi-stage optimized build
+- **Features**: Minimal size, pre-compiled Python, security hardening
+- **Use case**: Production deployment with high performance requirements
+
+### 3. CPU Image (Dockerfile.cpu)
+- **Base**: python:3.10-slim
+- **Features**: CPU-optimized, smaller footprint
+- **Use case**: Development, testing, or CPU-only servers
+
+## Docker Compose Services
+
+### Core Services
+
+- **backgroundfx-gpu**: Main application with GPU support
+- **backgroundfx-cpu**: CPU-only variant
+- **redis**: Cache and job queue
+- **nginx**: Reverse proxy (production profile)
+
+### Support Services
+
+- **model-downloader**: Pre-download models (setup profile)
+- **prometheus**: Metrics collection (monitoring profile)
+- **grafana**: Metrics visualization (monitoring profile)
+
+## Configuration
+
+### Environment Variables
+
+Copy the example environment file and customize:
+
+```bash
+cp docker/.env.example docker/.env
+```
+
+Key settings:
+- `DEVICE`: auto, cuda, or cpu
+- `MODEL_CACHE_DIR`: Model storage location
+- `MAX_MEMORY_GB`: Memory limit
+- `QUALITY_PRESET`: low, medium, high, ultra
+
+### Volumes
+
+- `model-cache`: Cached ML models (~2-5GB)
+- `uploads`: Uploaded files
+- `outputs`: Processed results
+- `redis-data`: Redis persistence
+
+## Makefile Commands
+
+```bash
+# Building
+make build          # Build GPU image
+make build-cpu      # Build CPU image
+make build-all      # Build all variants
+make build-nocache  # Build without cache
+
+# Running
+make run            # Run GPU version
+make run-cpu        # Run CPU version
+make run-dev        # Development mode
+make run-prod       # Production with monitoring
+
+# Management
+make stop           # Stop containers
+make restart        # Restart containers
+make clean          # Clean up
+make logs           # View logs
+make shell          # Container shell
+
+# Models
+make download-models  # Download all models
+make list-models      # List available models
+
+# Monitoring
+make status         # Container status
+make stats          # Resource usage
+make health         # Health checks
+```
+
+## Production Deployment
+
+### 1. Build Production Image
+
+```bash
+make build-prod
+```
+
+### 2. Configure Environment
+
+Edit `docker/.env` with production settings:
+- Set secure `AUTH_SECRET_KEY`
+- Configure `REDIS_PASSWORD`
+- Adjust resource limits
+- Enable authentication if needed
+
+### 3. Deploy with Monitoring
+
+```bash
+make run-prod
+```
+
+This starts:
+- Main application (port 7860)
+- API server (port 8000)
+- Nginx proxy (ports 80/443)
+- Redis cache
+- Prometheus + Grafana monitoring
+
+### 4. SSL/TLS Setup
+
+Place certificates in `nginx/ssl/`:
+- `nginx/ssl/cert.pem`
+- `nginx/ssl/key.pem`
+
+### 5. Scaling
+
+For horizontal scaling:
+
+```bash
+docker-compose up -d --scale backgroundfx-gpu=3
+```
+
+## GPU Support
+
+### Check GPU Availability
+
+```bash
+make gpu-check
+# Or
+docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu20.04 nvidia-smi
+```
+
+### Install NVIDIA Docker Runtime
+
+Ubuntu/Debian:
+```bash
+distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
+curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
+curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
+sudo apt-get update && sudo apt-get install -y nvidia-docker2
+sudo systemctl restart docker
+```
+
+## Troubleshooting
+
+### Out of Memory
+
+Adjust memory limits in `docker-compose.yml`:
+```yaml
+deploy:
+  resources:
+    limits:
+      memory: 8G  # Reduce if needed
+```
+
+### Models Not Loading
+
+Pre-download models:
+```bash
+make download-models
+```
+
+### Permission Issues
+
+Fix ownership:
+```bash
+docker-compose exec -u root backgroundfx-gpu chown -R appuser:appuser /app
+```
+
+### Slow Processing
+
+- Ensure GPU is detected: `make gpu-check`
+- Check resource usage: `make stats`
+- Adjust quality preset in `.env`
+
+## Development
+
+### Local Development with Docker
+
+```bash
+# Mount local code for live reload
+docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
+```
+
+### Running Tests
+
+```bash
+make test
+```
+
+### Building Custom Images
+
+```bash
+# With custom registry
+make push REGISTRY=myregistry.com VERSION=1.0.0
+```
+
+## Monitoring
+
+### Grafana Dashboard
+
+Access at http://localhost:3000 (admin/admin)
+
+Pre-configured dashboards:
+- Container metrics
+- GPU utilization
+- Processing statistics
+- Error rates
+
+### Prometheus Metrics
+
+Access at http://localhost:9090
+
+Available metrics:
+- `processing_time_seconds`
+- `frames_processed_total`
+- `model_load_time_seconds`
+- `memory_usage_bytes`
+
+## Backup and Restore
+
+### Backup Volumes
+
+```bash
+make backup
+```
+
+Creates timestamped backups in `./backups/`
+
+### Restore from Backup
+
+```bash
+make restore BACKUP_FILE=models-20240101-120000.tar.gz
+```
+
+## Security Considerations
+
+1. **Change default passwords** in production
+2. **Enable authentication** via AUTH_ENABLED=true
+3. **Configure CORS** appropriately
+4. **Use SSL/TLS** in production
+5. **Limit exposed ports** using firewall rules
+6. **Regular security updates**: `docker pull` base images
+
+## Performance Optimization
+
+### GPU Optimization
+- Use TensorRT models when available
+- Enable mixed precision with FP16
+- Adjust batch size based on GPU memory
+
+### CPU Optimization
+- Use quantized models
+- Enable OpenMP threading
+- Adjust worker count based on cores
+
+### Memory Optimization
+- Enable swap for large videos
+- Use frame skipping for preview
+- Implement progressive processing
+
+## Support
+
+For issues or questions:
+1. Check logs: `make logs`
+2. Verify health: `make health`
+3. Review configuration: `docker-compose config`
+4. Check system requirements: `make gpu-check`