echo6-docs/projects/arr-wiring-runbook.md

# CC Runbook: Wire ARR Stack End-to-End

## Objective

Connect all six services on the `arr` VM into a fully automated pipeline:

```
Jellyseer → Sonarr/Radarr → Prowlarr → SABnzbd → Downloads → Sonarr/Radarr catalogue → Jellyfin library → Jellyseer knows what's available
```

All containers are already running on `arr` on the `arr-net` Docker bridge network. Services can reach each other by container name (e.g., `sonarr:8989`).

---

## Phase 0: Prerequisites

### SSH Check
```bash
ssh media "echo 'SSH OK to media node'"
```
Then SSH into the `arr` VM (discover its IP from Phase 1 of the previous runbook, or check `qm list` / DHCP leases on media).

### Read Credentials File
Read the Usenet provider and indexer credentials from `./ref/services/usenet.md` on cortex. Parse and use these values throughout this runbook.

### Discover API Keys
Every service auto-generates an API key on first run. Extract them:

```bash
# Sonarr
docker exec sonarr cat /config/config.xml | grep -oP '(?<=<ApiKey>).*(?=</ApiKey>)'

# Radarr
docker exec radarr cat /config/config.xml | grep -oP '(?<=<ApiKey>).*(?=</ApiKey>)'

# Prowlarr
docker exec prowlarr cat /config/config.xml | grep -oP '(?<=<ApiKey>).*(?=</ApiKey>)'

# SABnzbd
docker exec sabnzbd cat /config/sabnzbd.ini | grep -oP '(?<=api_key = ).*'

# Jellyfin — get the API key from the admin dashboard or create one via API
```

Record all of these. They are needed for every integration below.

---

## Phase 1: SABnzbd — Configure Usenet Provider

Using credentials from `./ref/services/usenet.md`:

1. Via SABnzbd API (`http://localhost:8080/api`), configure the Usenet server:
   - Server hostname, port, SSL, username, password — all from the ref file
   - Connections: set to provider's recommended max
   - SSL verification: enable
2. Set download paths in SABnzbd:
   - Complete: `/data/downloads/complete`
   - Incomplete: `/data/downloads/incomplete`
3. Configure categories in SABnzbd:
   - `movies` → `/data/downloads/complete/movies`
   - `tv` → `/data/downloads/complete/tv`
4. Verify SABnzbd can connect to the Usenet server (test connection).

---

## Phase 2: Prowlarr — Add Indexers

Using indexer credentials from `./ref/services/usenet.md`:

1. Via Prowlarr API (`http://localhost:9696/api/v1`), add each Usenet indexer found in the ref file.
   - For each indexer: set name, URL, API key, and enable.
   - Use the Prowlarr API key discovered in Phase 0.
2. Test each indexer to confirm connectivity.

---

## Phase 3: Prowlarr — Connect to Sonarr and Radarr

Add Sonarr and Radarr as "Applications" in Prowlarr so indexers automatically sync:

### Sonarr
- Prowlarr API → Add Application:
  - Type: Sonarr
  - Prowlarr server: `http://prowlarr:9696`
  - Sonarr server: `http://sonarr:8989`
  - API key: Sonarr's API key from Phase 0
  - Sync level: Full Sync

### Radarr
- Prowlarr API → Add Application:
  - Type: Radarr
  - Prowlarr server: `http://prowlarr:9696`
  - Radarr server: `http://radarr:7878`
  - API key: Radarr's API key from Phase 0
  - Sync level: Full Sync

After adding, trigger a sync and verify indexers appear in Sonarr and Radarr.

---

## Phase 4: Sonarr — Configure Download Client and Paths

Via Sonarr API (`http://localhost:8989/api/v3`):

1. Add SABnzbd as download client:
   - Host: `sabnzbd`
   - Port: `8080`
   - API key: SABnzbd API key from Phase 0
   - Category: `tv`
   - Test connection.
2. Configure Root Folder:
   - Path: `/data/tv`
3. Configure Media Management:
   - Rename episodes: Yes
   - Use hardlinks: Yes (critical — same filesystem via NFS mount)

---

## Phase 5: Radarr — Configure Download Client and Paths

Via Radarr API (`http://localhost:7878/api/v3`):

1. Add SABnzbd as download client:
   - Host: `sabnzbd`
   - Port: `8080`
   - API key: SABnzbd API key from Phase 0
   - Category: `movies`
   - Test connection.
2. Configure Root Folder:
   - Path: `/data/movies`
3. Configure Media Management:
   - Rename movies: Yes
   - Use hardlinks: Yes

---

## Phase 6: Jellyfin — Configure Libraries

Via Jellyfin API or admin setup:

1. Create (or verify) media libraries:
   - **Movies** library → `/data/movies`
   - **TV Shows** library → `/data/tv`
2. Set libraries to scan periodically or on change.
3. Create an API key for Jellyseer to use (Admin Dashboard → API Keys → create one named `jellyseer`).

---

## Phase 7: Jellyseer — Connect Everything

Via Jellyseer's setup wizard or API:

1. **Jellyfin connection:**
   - Server URL: `http://jellyfin:8096`
   - API key: the Jellyfin API key created in Phase 6
   - Sync libraries so Jellyseer knows what Jellyfin already has.
   - Sign in with the Jellyfin admin account to link it.
2. **Sonarr connection:**
   - Server URL: `http://sonarr:8989`
   - API key: Sonarr API key from Phase 0
   - Root folder: `/data/tv`
   - Quality profile: discover available profiles from Sonarr and pick a sensible default (e.g., `Any` or `HD-1080p`)
3. **Radarr connection:**
   - Server URL: `http://radarr:7878`
   - API key: Radarr API key from Phase 0
   - Root folder: `/data/movies`
   - Quality profile: discover available profiles and pick a sensible default

---

## Phase 8: End-to-End Validation

Test the full pipeline:

1. **Prowlarr → Indexers:** Search for a common term (e.g., "test") in Prowlarr. Results should return from all configured indexers.
2. **Sonarr → Prowlarr:** In Sonarr, verify indexers are listed under Settings → Indexers (synced from Prowlarr).
3. **Radarr → Prowlarr:** Same check in Radarr.
4. **Sonarr → SABnzbd:** Verify download client is connected (Settings → Download Clients → test).
5. **Radarr → SABnzbd:** Same check.
6. **Jellyseer → Jellyfin:** Verify Jellyseer shows Jellyfin's existing library (if any).
7. **Jellyseer → Sonarr/Radarr:** Verify both are connected in Jellyseer settings.
8. **Full flow test:** If desired, use Jellyseer to request a free/public domain title and verify it flows through the entire chain: Jellyseer → Sonarr/Radarr → Prowlarr search → SABnzbd download → file lands in `/data/tv` or `/data/movies` → Jellyfin picks it up → Jellyseer shows it as available.

---

## Important Notes

- **All services communicate by Docker container name** on `arr-net` (e.g., `http://sonarr:8989`), NOT by localhost or LAN IP.
- **Hardlinks are critical.** Sonarr/Radarr and SABnzbd share the same `/data` mount from the NFS share. This means completed downloads can be hardlinked (not copied) into the media folders, avoiding double disk usage.
- **API-first approach.** Configure everything via API calls rather than manual UI interaction. This ensures repeatability and lets CC automate the full setup.
- **If any phase fails, stop and report the error.** Do not skip phases.
- **The credentials file is `./ref/services/usenet.md` on cortex.** Read it first and use its contents throughout.