nfoguard/DEPLOYMENT.md

NFOGuard Deployment Guide

🚀 Quick Start for Docker Deployment

Step 1: Environment Configuration

# Copy the environment template
cp .env.template .env

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

Key variables to customize in .env:

# 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

# Start NFOGuard
docker-compose up -d

# Check logs
docker-compose logs -f nfoguard

Step 3: Test Database Connection

# 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

# 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

# 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

curl -X POST "http://localhost:8080/manual/scan?scan_type=movies"

2. Bulk Update All Movies

curl -X POST "http://localhost:8080/bulk/update"

3. System Health Check

curl "http://localhost:8080/health"

4. Database Statistics

curl "http://localhost:8080/stats"

5. Debug Specific Movie

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:

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

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