feat: v3 — multi-instance Radarr/Sonarr support, web UI redesign, setup wizard

.env.example

@@ -1,172 +1,262 @@
 # ===========================================
-# Chronarr Configuration - CORRECTED VERSION
+# Chronarr Configuration
 # ===========================================
-# Main configuration file - safe to share for debugging
-# Sensitive data (API keys, passwords) are in .env.secrets
+# Copy this file to .env and fill in your values.
+# Sensitive values (API keys, passwords) belong in .env.secrets — keep that file out of git.
+#
+# WEBHOOK URLS for your Radarr/Sonarr instances:
+#   Single instance (default):  http://chronarr:8080/radarr/webhook
+#                               http://chronarr:8080/sonarr/webhook
+#   Named instances:            http://chronarr:8080/radarr_4k/webhook
+#                               http://chronarr:8080/sonarr_4k/webhook
+#   (Webhook URLs are built automatically from instance names in this file)
 
 # ===========================================
-# MEDIA PATHS (REQUIRED) - FIXED
+# CHRONARR DATABASE
 # ===========================================
-# Container paths (what Chronarr sees inside container)
-MOVIE_PATHS=/media/Movies/movies,/media/Movies/movies6
-TV_PATHS=/media/TV/tv,/media/TV/tv6
+# Internal Chronarr database — stores your media dates and metadata.
+# PostgreSQL is strongly recommended for production.
 
-# Radarr paths (what Radarr sees on the host system) 
-RADARR_ROOT_FOLDERS=/mnt/unionfs/Media/Movies/movies,/mnt/unionfs/Media/Movies/movies6
-
-# Sonarr paths (what Sonarr sees on the host system) - FIXED VARIABLE NAME AND PATHS
-SONARR_ROOT_FOLDERS=/mnt/unionfs/Media/TV/tv,/mnt/unionfs/Media/TV/tv6
+DB_TYPE=postgresql
+DB_HOST=chronarr-db
+DB_PORT=5432
+DB_NAME=chronarr
+DB_USER=chronarr
+# DB_PASSWORD= → set in .env.secrets
 
-# Download detection paths (for identifying downloads vs existing files)
-DOWNLOAD_PATH_INDICATORS=/downloads/,/nzbget/,/completed/,/sabnzbd/,/torrents/
+# SQLite alternative (not recommended for production):
+# DB_TYPE=sqlite
+# DB_PATH=/app/data/media_dates.db
 
 # ===========================================
 # SERVER CONFIGURATION
 # ===========================================
-# Timezone for container logging and timestamps
 TZ=America/New_York
 
-# Chronarr Core API (webhooks, processing, database management)
+# Core API — handles webhooks and processing
+# This is the interface Chronarr's own core container listens ON. Leave it
+# at 0.0.0.0 unless you have a specific reason to change it — setting this
+# to a hostname will stop core listening on the addresses Docker healthchecks
+# and the web container's other internal calls use, breaking both.
 CORE_API_HOST=0.0.0.0
 CORE_API_PORT=8080
 
-# Chronarr Web Interface (dashboard, series/movie management)
-WEB_API_HOST=0.0.0.0
-WEB_API_PORT=8081
-
-# External port where web interface is accessible (for dynamic port reference)
+# Where the WEB container reaches CORE internally — a different setting from
+# the pair above. Only needed if the default hostname "chronarr" is
+# ambiguous, e.g. running more than one Chronarr deployment on the same
+# Docker network (a production stack and a local-test stack, say) — point
+# this at your core container's actual name/service in that situation.
+# CORE_INTERNAL_HOST=chronarr
+# CORE_INTERNAL_PORT=8080
+
+# Web dashboard
+WEB_HOST=0.0.0.0
+WEB_PORT=8081
+WEB_WORKERS=1
 WEB_EXTERNAL_PORT=8081
 
 # ===========================================
-# DATABASE CONFIGURATION  
+# RADARR — MAIN INSTANCE
 # ===========================================
-# Chronarr Database Configuration (PostgreSQL - v2.6+)
-# NOTE: For new installations, PostgreSQL is strongly recommended
-# Set these values in .env.secrets for security:
-# - DB_PASSWORD=your_secure_password
-# - DB_USER=chronarr (default)
-
-# PostgreSQL Database Settings
-DB_TYPE=postgresql
-DB_HOST=chronarr-db  # Container name from docker-compose
-DB_PORT=5432
-DB_NAME=chronarr
-DB_USER=chronarr
-
-# Legacy SQLite Configuration (Deprecated in v2.6+)
-# Only use for existing SQLite installations
-# DB_PATH=/app/data/media_dates.db
+# Paths: RADARR_ROOT_FOLDERS is what Radarr sees on the host (or UNC path on Windows).
+#        RADARR_MOVIE_PATHS is what Chronarr sees inside the container.
+#        Both are comma-separated.
+#
+# IMPORTANT — multi-instance users:
+#   Define paths per-instance (RADARR_MOVIE_PATHS, RADARR_4K_MOVIE_PATHS, etc.)
+#   Do NOT use the global MOVIE_PATHS key when running multiple instances —
+#   if it appears more than once in your env file, Docker only keeps the last
+#   definition and silently drops the others.
 
-# Log file directory
-LOG_DIR=/app/data/logs
+RADARR_URL=http://radarr:7878
+# RADARR_API_KEY= → set in .env.secrets
+# RADARR_WEBHOOK_SECRET= → set in .env.secrets (optional, for webhook validation)
+RADARR_ROOT_FOLDERS=/mnt/unionfs/Media/Movies/movies
+RADARR_MOVIE_PATHS=/media/movies
 
-# ===========================================
-# RADARR DATABASE CONNECTION (RECOMMENDED)
-# ===========================================
-# Direct database access for better performance
+# Radarr database (direct DB access — faster than API for large libraries)
 RADARR_DB_TYPE=postgresql
-RADARR_DB_HOST=192.168.255.50
+RADARR_DB_HOST=your-radarr-db-host
 RADARR_DB_PORT=5432
 RADARR_DB_NAME=radarr-main
 RADARR_DB_USER=postgres
+# RADARR_DB_PASSWORD= → set in .env.secrets
 
-# Alternative: SQLite (if Radarr uses SQLite)
+# SQLite alternative:
 # RADARR_DB_TYPE=sqlite
 # RADARR_DB_PATH=/path/to/radarr.db
 
 # ===========================================
-# SONARR DATABASE CONNECTION (RECOMMENDED)
+# RADARR — ADDITIONAL INSTANCES (OPTIONAL)
+# ===========================================
+# Add a block per extra Radarr instance. The name between RADARR_ and _URL
+# becomes part of the webhook URL: RADARR_4K_URL → /radarr_4k/webhook
+# Names must be uppercase letters, digits, and underscores only — no hyphens
+# (a shell/env-var limitation). RADARR_4K and RADARR_STRM_BOX are fine;
+# RADARR-4K is not. The URL *value* has no such restriction — it can contain
+# hyphens and a full domain name, e.g. RADARR_STRM_URL=http://radarr-strm.yourdomain.com:7878
+#
+# Each instance defines ALL of its own settings here — URL, API key, paths,
+# and database access. Do NOT set MOVIE_PATHS again in this block; use
+# RADARR_4K_MOVIE_PATHS instead. If MOVIE_PATHS appears twice in your env
+# file, Docker only keeps the last value and silently drops the first.
+#
+# After configuring instances, visit http://your-server:8081/setup
+# for the exact webhook URLs to paste into each Radarr instance.
+
+# RADARR_4K_URL=http://radarr4k:7878
+# RADARR_4K_API_KEY= → set in .env.secrets
+# RADARR_4K_WEBHOOK_SECRET= → set in .env.secrets (optional)
+# RADARR_4K_ROOT_FOLDERS=/mnt/unionfs/Media/Movies/movies4k
+# RADARR_4K_MOVIE_PATHS=/media/movies4k   ← per-instance paths, NOT MOVIE_PATHS
+# RADARR_4K_DB_TYPE=postgresql
+# RADARR_4K_DB_HOST=your-radarr-4k-db-host
+# RADARR_4K_DB_PORT=5432
+# RADARR_4K_DB_NAME=radarr-4k
+# RADARR_4K_DB_USER=postgres
+# RADARR_4K_DB_PASSWORD= → set in .env.secrets
+# SQLite: RADARR_4K_DB_TYPE=sqlite / RADARR_4K_DB_PATH=/radarr-4k-data/radarr.db
+
+# ===========================================
+# SONARR — MAIN INSTANCE
 # ===========================================
-# Direct database access for better performance
-# Phase 7: High-performance TV episode import date detection
+# Same paths rule as Radarr: use SONARR_TV_PATHS here, not the global TV_PATHS,
+# so each instance's paths stay self-contained.
+SONARR_URL=http://sonarr:8989
+# SONARR_API_KEY= → set in .env.secrets
+# SONARR_WEBHOOK_SECRET= → set in .env.secrets (optional)
+SONARR_ROOT_FOLDERS=/mnt/unionfs/Media/TV/tv
+SONARR_TV_PATHS=/media/tv
+
+# Sonarr database
 SONARR_DB_TYPE=postgresql
-SONARR_DB_HOST=192.168.255.50
+SONARR_DB_HOST=your-sonarr-db-host
 SONARR_DB_PORT=5432
 SONARR_DB_NAME=sonarr-main
 SONARR_DB_USER=postgres
+# SONARR_DB_PASSWORD= → set in .env.secrets
 
-# Alternative: SQLite (if Sonarr uses SQLite)
+# SQLite alternative:
 # SONARR_DB_TYPE=sqlite
 # SONARR_DB_PATH=/path/to/sonarr.db
 
 # ===========================================
-# API CONNECTIONS (OPTIONAL)
+# SONARR — ADDITIONAL INSTANCES (OPTIONAL)
 # ===========================================
-# API keys are stored in .env.secrets for security
-RADARR_URL=http://radarr:7878
-SONARR_URL=http://sonarr:8989
+# Same rule: use SONARR_4K_TV_PATHS, NOT TV_PATHS, in additional instance blocks.
+# SONARR_4K_URL=http://sonarr4k:8989
+# SONARR_4K_API_KEY= → set in .env.secrets
+# SONARR_4K_WEBHOOK_SECRET= → set in .env.secrets (optional)
+# SONARR_4K_ROOT_FOLDERS=/mnt/unionfs/Media/TV/tv4k
+# SONARR_4K_TV_PATHS=/media/tv4k              ← per-instance paths, NOT TV_PATHS
+# SONARR_4K_DB_TYPE=postgresql
+# SONARR_4K_DB_HOST=your-sonarr-4k-db-host
+# SONARR_4K_DB_PORT=5432
+# SONARR_4K_DB_NAME=sonarr-4k
+# SONARR_4K_DB_USER=postgres
+# SONARR_4K_DB_PASSWORD= → set in .env.secrets
+
+# ===========================================
+# EXTERNAL APIs (OPTIONAL)
+# ===========================================
+# Jellyseerr — for request tracking
+# JELLYSEERR_URL=http://jellyseerr:5055
+# JELLYSEERR_API_KEY= → set in .env.secrets
+
+# TMDB — for release date and metadata lookup
+# TMDB_API_KEY= → set in .env.secrets
+TMDB_COUNTRY=US
+# TMDB_TYPE_PRIORITY=movie,tv
+
+# TVDB — for TV episode air dates
+# TVDB_API_KEY= → set in .env.secrets
+# DISABLE_TVDB=false
+
+# OMDB — fallback metadata source
+# OMDB_API_KEY= → set in .env.secrets
 
 # ===========================================
-# RELEASE DATE PROCESSING
+# MOVIE PROCESSING
 # ===========================================
-# Priority order for release date fallbacks (digital, physical, theatrical)
+# Priority for determining which date to use
+# Options: import_then_digital, digital_only, theatrical_only
+MOVIE_PRIORITY=import_then_digital
+
+# Order to check release date types
 RELEASE_DATE_PRIORITY=digital,physical,theatrical
-#RELEASE_DATE_PRIORITY=digital,theatrical,physical
-ENABLE_SMART_DATE_VALIDATION=true
-MAX_RELEASE_DATE_GAP_YEARS=10
 
-# Prefer API release dates over file modification dates for manual imports
+# Prefer API release dates over file modification dates
 PREFER_RELEASE_DATES_OVER_FILE_DATES=true
 
-# Disable file date fallback completely (recommended for clean imports)
+# Allow file modification date as a last-resort fallback
 ALLOW_FILE_DATE_FALLBACK=false
 
-# TMDB country for regional release date preferences
-TMDB_COUNTRY=US
+# How to handle existing dates in the database
+# Options: backfill_only (fill missing), overwrite (always update)
+MOVIE_DATE_UPDATE_MODE=backfill_only
 
+# When to poll for movie date data
+# Options: always, missing_only, never
+MOVIE_POLL_MODE=always
+
+# Smart date validation — rejects dates that seem implausible
+ENABLE_SMART_DATE_VALIDATION=true
+MAX_RELEASE_DATE_GAP_YEARS=10
+
+# Remove movies from DB that have been missing for N days (0 = disabled)
+PURGE_MISSING_MOVIES_DAYS=0
 
 # ===========================================
-# PROCESSING BEHAVIOR
+# TV PROCESSING
 # ===========================================
-# Movie date update strategy
-MOVIE_DATE_UPDATE_MODE=overwrite
-MOVIE_PRESERVE_EXISTING=false
-
-# When to update existing dates (always, missing_only, never)
-UPDATE_MODE=always
+TV_WEBHOOK_PROCESSING_MODE=targeted
 
-# File modification time behavior (update, leave_alone)
-MTIME_BEHAVIOR=update
+# Season directory naming — must match your actual folder names
+TV_SEASON_DIR_FORMAT=Season {season:02d}
+TV_SEASON_DIR_PATTERN=season
 
-# Manual scan priority: use existing NFO dates for speed vs check APIs for accuracy
-# false (default) = Check external APIs first, use NFO as fallback (slower but accurate)
-# true = Use NFO dates immediately without API checks (faster but may use wrong dates)
-MANUAL_SCAN_PRIORITIZE_NFO=false
+# Remove TV shows from DB that have been missing for N days (0 = disabled)
+PURGE_MISSING_TV_DAYS=0
 
 # ===========================================
 # PERFORMANCE & BATCHING
 # ===========================================
-# Delay before processing batched events (seconds)
 BATCH_DELAY=5.0
-
-# Maximum concurrent series processing
 MAX_CONCURRENT_SERIES=3
-
-# Sequential processing delay for bulk downloads (seconds)
-# When multiple episodes are downloaded at once, process them one by one with this delay
-# Set to 0 to disable sequential processing (parallel mode)
 SEQUENTIAL_DELAY=20.0
-
-# API timeout in seconds
 TIMEOUT_SECONDS=45
 
+# ===========================================
+# WEB INTERFACE
+# ===========================================
+WEB_AUTH_ENABLED=false
+# WEB_AUTH_USERNAME=admin
+# WEB_AUTH_PASSWORD= → set in .env.secrets
+WEB_AUTH_SESSION_TIMEOUT=3600
+
+# Dashboard display
+# APP_TITLE=Chronarr
+# APP_SUBTITLE=Database Management & Reporting
+PAGINATION_LIMIT=50
+REFRESH_INTERVAL=30
+
 # ===========================================
 # DEBUGGING
 # ===========================================
-# Enable verbose logging (true/false)
 DEBUG=false
-
-# Enable path mapping debug output (true/false)
 PATH_DEBUG=false
-
-# Suppress TVDB API warnings (true/false) - TVDB failures are common and non-critical
-SUPPRESS_TVDB_WARNINGS=true
+LOG_DIR=/app/data/logs
 
 # ===========================================
-# WEB INTERFACE AUTHENTICATION
+# LEGACY — PENDING REMOVAL
 # ===========================================
-# Enable web interface authentication (default: false)
-WEB_AUTH_ENABLED=false
-
-# Session timeout in seconds (default: 3600 = 1 hour)
-WEB_AUTH_SESSION_TIMEOUT=3600
+# These settings controlled NFO file writing, which was the original mechanism
+# for pushing dates into Emby/Jellyfin. The Emby/Jellyfin plugins now read
+# directly from Chronarr's database, making this code path obsolete.
+# These vars and the code behind them will be removed in a future release.
+# Changing these values currently has no meaningful effect.
+#
+# MANAGE_NFO=true
+# FIX_DIR_MTIMES=true
+# LOCK_METADATA=true
+# MANUAL_SCAN_PRIORITIZE_NFO=false