nfoguard/DEPLOYMENT.md

# NFOGuard Deployment Guide

## 🚀 Quick Start for Docker Deployment

### Step 1: Environment Configuration
```bash
# Copy the environment template
cp .env.template .env

# Edit with your specific paths and database credentials
nano .env
```

**Key variables to customize in `.env`**:
```bash
# YOUR MEDIA PATHS (adjust these to your setup)
TV_PATHS=/media/TV/tv,/media/TV/tv6
MOVIE_PATHS=/media/Movies/movies,/media/Movies/movies6
HOST_MEDIA_PATH=/mnt/unionfs/Media

# YOUR RADARR DATABASE PASSWORD
RADARR_DB_PASSWORD=your_actual_password_here
```

### Step 2: Deploy with Docker Compose
```bash
# Start NFOGuard
docker-compose up -d

# Check logs
docker-compose logs -f nfoguard
```

### Step 3: Test Database Connection
```bash
# Test Radarr database connectivity
curl -X POST "http://localhost:8080/test/bulk-update"

# Expected response:
# {"status": "success", "movies_with_imdb": 1500, "database_type": "postgresql"}
```

### Step 4: Test Movie Discovery
```bash
# Test that your movie paths are correctly configured
curl -X POST "http://localhost:8080/test/movie-scan"

# Expected response:
# {"status": "success", "message": "Movie scan test found 1500 movies", 
#  "path_results": [{"path": "/media/Movies/movies", "exists": true, "movies_found": 800}, ...]}
```

### Step 5: Validate Database Performance
```bash
# Test the optimized database query performance
curl "http://localhost:8080/debug/movie/tt1674782"

# Expected response with July 2025 date:
# {"detected_import_date": "2025-07-08T03:30:04+00:00", "import_source": "radarr:history.import"}
```

## 📊 Production Workflow

### Manual Operations (via webhooks)

**1. Manual Movie Scan**
```bash
curl -X POST "http://localhost:8080/manual/scan?scan_type=movies"
```

**2. Bulk Update All Movies**
```bash
curl -X POST "http://localhost:8080/bulk/update"
```

**3. System Health Check**
```bash
curl "http://localhost:8080/health"
```

**4. Database Statistics**
```bash
curl "http://localhost:8080/stats"
```

**5. Debug Specific Movie**
```bash
curl "http://localhost:8080/debug/movie/tt1674782"
```

### Radarr Webhook Integration

**Add to Radarr → Settings → Connect → Webhook:**
- **Name**: NFOGuard
- **URL**: `http://nfoguard:8080/webhook/radarr`
- **Method**: POST
- **Events**: On Download, On Upgrade, On Rename

NFOGuard will automatically process movies when Radarr sends webhooks.

## 🔧 Environment Variables Reference

### Required Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `MOVIE_PATHS` | Comma-separated movie directories | `/media/Movies/movies,/media/Movies/movies6` |
| `TV_PATHS` | Comma-separated TV directories | `/media/TV/tv,/media/TV/tv6` |
| `RADARR_DB_HOST` | Radarr PostgreSQL host | `radarr-postgres` |
| `RADARR_DB_PASSWORD` | Radarr database password | `your_password` |

### Optional Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `HOST_MEDIA_PATH` | `/mnt/unionfs/Media` | Host path mounted to `/media` |
| `DB_PATH` | `/app/data/media_dates.db` | NFOGuard database location |
| `MANAGE_NFO` | `true` | Create/update .nfo files |
| `FIX_DIR_MTIMES` | `true` | Fix file modification times |
| `MOVIE_PRIORITY` | `import_then_digital` | Date preference strategy |
| `DEBUG` | `false` | Enable debug logging |

## 🏗 Docker Compose Customization

**For different media structures:**
```yaml
# Example: Different media structure
services:
  nfoguard:
    environment:
      - TV_PATHS=/storage/tv_shows,/storage/anime
      - MOVIE_PATHS=/storage/movies
    volumes:
      - "/storage:/storage:rw"
      - "./data:/app/data"
```

**For external database networks:**
```yaml
# Example: Connect to existing Radarr network
services:
  nfoguard:
    networks:
      - radarr_network

networks:
  radarr_network:
    external: true
```

## 🛠 Troubleshooting

### "0 movies processed"
1. Check paths: `curl -X POST "http://localhost:8080/test/movie-scan"`
2. Verify environment variables in `.env`
3. Ensure directories exist and have IMDb tags: `Movie Name [imdb-tt1234567] (2023)`

### Database connection errors
1. Test connection: `curl -X POST "http://localhost:8080/test/bulk-update"`
2. Verify `RADARR_DB_*` variables
3. Check Docker network connectivity

### Performance issues
1. Check health: `curl "http://localhost:8080/health"`
2. Monitor logs: `docker-compose logs -f nfoguard`
3. Verify database query performance: `curl "http://localhost:8080/debug/movie/tt1674782"`

## 📈 Monitoring

**Health Check Endpoint**: `GET /health`
- Server status and uptime
- Database connectivity
- Radarr database status

**Statistics Endpoint**: `GET /stats`  
- Movie/TV counts
- Processing statistics

**Batch Queue Status**: `GET /batch/status`
- Pending webhook events
- Processing queue status

This deployment approach ensures NFOGuard can be easily configured for any media server setup while maintaining the database-only performance optimizations.