Sanitized mirror from private repository - 2026-04-19 08:15:48 UTC

docs/services/individual/download-priority.md

@@ -0,0 +1,130 @@
+# Download Priority: NZB-First / Torrent Fallback
+
+## Overview
+
+Sonarr and Radarr are configured to exhaust all Usenet (NZB) sources before falling back to
+torrents. A torrent is only used if:
+
+1. No working NZB is found, **and**
+2. 120 minutes have elapsed since the item was first wanted
+
+This prevents noisy torrent grabs when a perfectly good NZB exists but takes a moment to be
+indexed.
+
+## How It Works
+
+### Delay Profile (both Sonarr and Radarr)
+
+| Setting | Value | Reason |
+|---------|-------|--------|
+| `preferredProtocol` | `usenet` | SABnzbd is tried first |
+| `usenetDelay` | 0 min | Grab NZBs immediately |
+| `torrentDelay` | **120 min** | Wait 2 hours before allowing torrent grabs |
+| `bypassIfHighestQuality` | **false** | Never skip the torrent delay, even for top-quality releases |
+
+`bypassIfHighestQuality: false` is critical. Without it, any torrent matching the highest quality
+tier would bypass the 120-minute wait entirely.
+
+### Download Clients
+
+| Client | Protocol | Priority | Service |
+|--------|----------|----------|---------|
+| SABnzbd | Usenet | **1** (highest) | Sonarr + Radarr |
+| Deluge | Torrent | **50** (lower) | Sonarr + Radarr |
+
+Lower priority number = higher precedence. SABnzbd at priority 1 always wins when both protocols
+are eligible.
+
+### End-to-End Flow
+
+```
+Item goes Wanted
+    │
+    ▼
+Sonarr/Radarr searches indexers immediately
+    │
+    ├─ NZB found? ──► SABnzbd downloads it ──► Done
+    │
+    └─ No NZB found
+           │
+           ▼
+       Wait 120 min (torrent delay)
+           │
+           ▼
+       Search again → Torrent found? ──► Deluge downloads it ──► Done
+```
+
+Failed download handling is enabled on both services: if SABnzbd reports a failed download
+(missing blocks, password-protected, etc.), the *arr app marks it failed and re-searches,
+eventually falling through to Deluge after the delay.
+
+## Configuration Details
+
+### Deluge
+
+Deluge runs inside the gluetun VPN container (network_mode: `service:gluetun`), so all torrent
+traffic is routed through the VPN.
+
+- **Host:** `gluetun` (Docker service name, shared network with gluetun)
+- **Port:** `8112`
+- **Config on Atlantis:** `/volume2/metadata/docker2/deluge/`
+- **Default password:** `deluge` (linuxserver/deluge image default)
+
+### SABnzbd
+
+- **Host:** `192.168.0.200`
+- **Port:** `8080`
+- **Categories:** `tv` (Sonarr), `movies` (Radarr)
+
+## Adjusting the Torrent Delay
+
+To change the 120-minute torrent delay via API:
+
+**Sonarr:**
+```bash
+curl -X PUT "http://192.168.0.200:8989/api/v3/delayprofile/1" \
+  -H "X-Api-Key: "REDACTED_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"id":1,"enableUsenet":true,"enableTorrent":true,"preferredProtocol":"usenet",
+       "usenetDelay":0,"torrentDelay":120,"bypassIfHighestQuality":false,
+       "bypassIfAboveCustomFormatScore":false,"minimumCustomFormatScore":0,
+       "order":2147483647,"tags":[]}'
+```
+
+**Radarr:**
+```bash
+curl -X PUT "http://192.168.0.200:7878/api/v3/delayprofile/1" \
+  -H "X-Api-Key: "REDACTED_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"id":1,"enableUsenet":true,"enableTorrent":true,"preferredProtocol":"usenet",
+       "usenetDelay":0,"torrentDelay":120,"bypassIfHighestQuality":false,
+       "bypassIfAboveCustomFormatScore":false,"minimumCustomFormatScore":0,
+       "order":2147483647,"tags":[]}'
+```
+
+Replace `120` with any value in minutes (e.g. `0` to disable the wait, `60` for 1 hour).
+
+## Verifying the Configuration
+
+```bash
+# Check delay profiles
+curl -s "http://192.168.0.200:8989/api/v3/delayprofile" \
+  -H "X-Api-Key: "REDACTED_API_KEY" | python3 -m json.tool
+curl -s "http://192.168.0.200:7878/api/v3/delayprofile" \
+  -H "X-Api-Key: "REDACTED_API_KEY" | python3 -m json.tool
+
+# Check download clients
+curl -s "http://192.168.0.200:8989/api/v3/downloadclient" \
+  -H "X-Api-Key: "REDACTED_API_KEY" | python3 -m json.tool
+curl -s "http://192.168.0.200:7878/api/v3/downloadclient" \
+  -H "X-Api-Key: "REDACTED_API_KEY" | python3 -m json.tool
+```
+
+Expected results:
+- Both delay profiles: `torrentDelay=120`, `bypassIfHighestQuality=false`
+- Sonarr clients: SABnzbd `enable=true priority=1`, Deluge `enable=true priority=50`
+- Radarr clients: SABnzbd `enable=true priority=1`, Deluge `enable=true priority=50`
+
+## Scope
+
+This configuration applies to **Sonarr and Radarr only**. Lidarr and Whisparr are out of scope.