From cde1c5df2d1c99b0aa85aea1c7f090653d89079a Mon Sep 17 00:00:00 2001
From: jeremy <jeremydanielhobbs@gmail.com>
Date: Wed, 4 Feb 2026 10:59:09 -0600
Subject: [PATCH] Add media stack documentation

---
 docs/media-stack.md | 170 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 170 insertions(+)
 create mode 100644 docs/media-stack.md

diff --git a/docs/media-stack.md b/docs/media-stack.md
new file mode 100644
index 0000000..b74aeb9
--- /dev/null
+++ b/docs/media-stack.md
@@ -0,0 +1,170 @@
+# Media Stack Documentation
+
+## Overview
+
+The media stack runs on Nomad and consists of:
+
+| Service | Port | URL | Purpose |
+|---------|------|-----|---------|
+| Jellyfin | 8096 | r2d2.hobbs.farm | Media streaming |
+| Sonarr | 8989 | sonarr.hobbs.farm | TV show management |
+| Radarr | 7878 | radarr.hobbs.farm | Movie management |
+| SABnzbd | 8082 | sabnzbd.hobbs.farm | Usenet downloads |
+| NZBHydra2 | 5076 | hydra.hobbs.farm | Indexer aggregation |
+| Jellyseerr | 5055 | requests.hobbs.farm | Media requests |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    hf-pdocker-01                            │
+├─────────────────────────────────────────────────────────────┤
+│  Nomad Job: media-stack                                     │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │ Jellyfin ←──────── /data/media ────────→ Sonarr       ││
+│  │    ↑                    ↑                    ↓          ││
+│  │    │               Radarr ←──────────→ SABnzbd        ││
+│  │    │                    ↑                    ↑          ││
+│  │    └────────────── NZBHydra2 ←────────────────┘        ││
+│  │                         ↓                               ││
+│  │                   Jellyseerr (requests)                 ││
+│  └─────────────────────────────────────────────────────────┘│
+│                                                             │
+│  Storage:                                                   │
+│  ├── /data/media/tv        (TV shows)                      │
+│  ├── /data/media/movies    (Movies)                        │
+│  ├── /data/media/downloads (Download staging)              │
+│  └── /data/config/*        (Per-service configs)           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Deployment
+
+### Deploy the stack
+
+```bash
+nomad job run nomad-jobs/media-stack.nomad.hcl
+```
+
+### Check status
+
+```bash
+nomad job status media-stack
+nomad alloc status <alloc-id>
+```
+
+### View logs
+
+```bash
+nomad alloc logs <alloc-id> jellyfin
+nomad alloc logs <alloc-id> sonarr
+```
+
+### Stop the stack
+
+```bash
+nomad job stop media-stack
+```
+
+## Storage Layout
+
+### Host Volumes (configured in Nomad)
+
+| Volume Name | Host Path | Services |
+|-------------|-----------|----------|
+| media | /data/media | Jellyfin, Sonarr, Radarr |
+| downloads | /data/media/downloads | Sonarr, Radarr, SABnzbd |
+| jellyfin-config | /data/config/jellyfin | Jellyfin |
+| sonarr-config | /data/config/sonarr | Sonarr |
+| radarr-config | /data/config/radarr | Radarr |
+| sabnzbd-config | /data/config/sabnzbd | SABnzbd |
+| nzbhydra2-config | /data/config/nzbhydra2 | NZBHydra2 |
+| jellyseerr-config | /data/config/jellyseerr | Jellyseerr |
+
+## Service Configuration
+
+### Sonarr/Radarr Setup
+
+1. Add SABnzbd as download client
+2. Add NZBHydra2 as indexer
+3. Configure media paths:
+   - Root folder: `/media/tv` (Sonarr) or `/media/movies` (Radarr)
+   - Download folder: `/downloads`
+
+### SABnzbd Setup
+
+1. Configure usenet provider credentials
+2. Set download folder to `/downloads`
+3. Create API key for Sonarr/Radarr
+
+### NZBHydra2 Setup
+
+1. Add indexer credentials
+2. Create API key for Sonarr/Radarr
+
+### Jellyseerr Setup
+
+1. Connect to Jellyfin server
+2. Connect to Sonarr/Radarr
+3. Configure user permissions
+
+## Secrets (Vault)
+
+Secrets are stored in HashiCorp Vault at `secret/media-stack/`:
+
+```
+secret/media-stack/sabnzbd
+  - usenet_server
+  - usenet_username
+  - usenet_password
+  - api_key
+
+secret/media-stack/nzbhydra2
+  - indexer_api_keys
+
+secret/media-stack/sonarr
+  - api_key
+
+secret/media-stack/radarr
+  - api_key
+```
+
+## Traefik Integration
+
+Services automatically register in Consul with Traefik tags. Traefik discovers services and creates routes based on the configured `Host()` rules.
+
+## Backup
+
+Config directories should be backed up regularly:
+
+```bash
+tar -czf media-stack-config-$(date +%Y%m%d).tar.gz /data/config/
+```
+
+## Troubleshooting
+
+### Container won't start
+
+```bash
+nomad alloc status <alloc-id>
+nomad alloc logs -stderr <alloc-id> <task>
+```
+
+### Permission issues
+
+Ensure PUID/PGID match the owner of `/data`:
+```bash
+ls -la /data/
+chown -R 1000:1000 /data/
+```
+
+### Service discovery issues
+
+Check Consul:
+```bash
+consul catalog services | grep -E 'jellyfin|sonarr|radarr'
+```
+
+---
+
+*Maintained by Pluto 🪐*