docker/readme.md

# 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`