From c47615a7517326f7adfda329b1d867330f5f7e2e Mon Sep 17 00:00:00 2001 From: Nick Yeoman Date: Mon, 2 Nov 2026 22:23:37 +0000 Subject: [PATCH] updated documentation and whisparr --- bazarr_dev/README.md | 12 +++++ jellyfin/README.md | 17 +++++--- lidarr_dev/README.md | 12 +++++ qbittorrent/README.md | 12 +++++ radarr/README.md | 58 +++++++++++++++++++++---- readarr_dev/README.md | 12 +++++ sonarr/README.md | 12 +++++ stash/README.md | 3 ++ {whisparr_dev => whisparr}/README.md | 31 +++++++++---- {whisparr_dev => whisparr}/compose.yaml | 0 {whisparr_dev => whisparr}/sample.env | 0 11 files changed, 147 insertions(+), 22 deletions(-) rename {whisparr_dev => whisparr}/README.md (61%) rename {whisparr_dev => whisparr}/compose.yaml (100%) rename {whisparr_dev => whisparr}/sample.env (100%) diff --git a/bazarr_dev/README.md b/bazarr_dev/README.md index 95d0bb2..da2f8fa 100644 --- a/bazarr_dev/README.md +++ b/bazarr_dev/README.md @@ -12,6 +12,18 @@ Bazarr is a subtitle management companion for Sonarr and Radarr. It automaticall ## Getting Started +### Prepare the shared media folder (once per host) + +All media apps run as user `1000` and share `/data/media`. If Docker creates the folder itself it's owned by root, and the apps fail with *"Folder '/media/' is not writable by user 'hotio'"*. Create it with the right owner before first start: + +```bash +sudo mkdir -p /data/media/{downloads/prowlarr,movies,shows,music,books} +sudo chown -R 1000:1000 /data/media +sudo chmod -R u+rwX,g+rwX /data/media +``` + +Check with `ls -ln /data/media` — the owner should be `1000 1000`. + Open http://localhost:6767 in your browser and complete the initial setup: 1. **Configure subtitle languages** — select your preferred languages (e.g., English, French) diff --git a/jellyfin/README.md b/jellyfin/README.md index ed3c2bd..297ce7a 100644 --- a/jellyfin/README.md +++ b/jellyfin/README.md @@ -12,6 +12,18 @@ Jellyfin is a free, open-source media server. It organizes your movies, shows, m ## Getting Started +### Prepare the shared media folder (once per host) + +All media apps run as user `1000` and share `/data/media`. If Docker creates the folder itself it's owned by root, and the apps fail with *"Folder '/media/' is not writable by user 'hotio'"*. Create it with the right owner before first start: + +```bash +sudo mkdir -p /data/media/{downloads/prowlarr,movies,shows,music,books} +sudo chown -R 1000:1000 /data/media +sudo chmod -R u+rwX,g+rwX /data/media +``` + +Check with `ls -ln /data/media` — the owner should be `1000 1000`. + Open http://localhost:8096 in your browser and complete the setup wizard: 1. **Create your admin account** @@ -82,11 +94,6 @@ docker run -d \ ## Additional Notes / Gotchas -- **Create the library folders first.** If `/data/media/movies` etc. don't exist, Docker creates them owned by root and Sonarr/Radarr (PUID 1000) can't write to them: - ```bash - mkdir -p /data/media/{downloads/prowlarr,movies,shows,music,books} - chown -R 1000:1000 /data/media - ``` - **Only port 8096 is published.** HTTPS (8920) is handled by Nginx Proxy Manager. Local network auto-discovery (UDP 1900/7359) won't work through the bridge network, so add the server to clients by URL. - **Photos** are left out on purpose — use the Immich stack for photo libraries. - **Hardware transcoding** needs the GPU passed into the container (e.g. `devices: [/dev/dri:/dev/dri]` for Intel/AMD). It's not included by default. diff --git a/lidarr_dev/README.md b/lidarr_dev/README.md index 7e0e0c8..b201235 100644 --- a/lidarr_dev/README.md +++ b/lidarr_dev/README.md @@ -12,6 +12,18 @@ Lidarr is a music collection manager for Usenet and BitTorrent users. It automat ## Getting Started +### Prepare the shared media folder (once per host) + +All media apps run as user `1000` and share `/data/media`. If Docker creates the folder itself it's owned by root, and the apps fail with *"Folder '/media/' is not writable by user 'hotio'"*. Create it with the right owner before first start: + +```bash +sudo mkdir -p /data/media/{downloads/prowlarr,movies,shows,music,books} +sudo chown -R 1000:1000 /data/media +sudo chmod -R u+rwX,g+rwX /data/media +``` + +Check with `ls -ln /data/media` — the owner should be `1000 1000`. + Open http://localhost:8686 in your browser and complete the initial setup wizard: 1. **Choose your UI language** diff --git a/qbittorrent/README.md b/qbittorrent/README.md index 2f8c2cb..7fcc8c7 100644 --- a/qbittorrent/README.md +++ b/qbittorrent/README.md @@ -17,6 +17,18 @@ BitTorrent client with a full-featured web UI. ## Getting Started +### Prepare the shared media folder (once per host) + +All media apps run as user `1000` and share `/data/media`. If Docker creates the folder itself it's owned by root, and the apps fail with *"Folder '/media/' is not writable by user 'hotio'"*. Create it with the right owner before first start: + +```bash +sudo mkdir -p /data/media/{downloads/prowlarr,movies,shows,music,books} +sudo chown -R 1000:1000 /data/media +sudo chmod -R u+rwX,g+rwX /data/media +``` + +Check with `ls -ln /data/media` — the owner should be `1000 1000`. + 1. Start the container: `docker compose up -d` 2. Open http://localhost:8080 in your browser 3. Follow the initial setup wizard to configure the application diff --git a/radarr/README.md b/radarr/README.md index 453b198..9f8dc51 100644 --- a/radarr/README.md +++ b/radarr/README.md @@ -12,17 +12,59 @@ Radarr is an automated movie collection manager for Usenet and BitTorrent users. ## Getting Started -Open http://localhost:7878 in your browser and complete the initial setup wizard: +### Prepare the shared media folder (once per host) -1. **Choose your UI language** -2. **Add a download client** — select qBittorrent, enter its host/port/credentials -3. **Add an indexer** — or connect to Prowlarr for automatic indexer sync +All media apps run as user `1000` and share `/data/media`. If Docker creates the folder itself it's owned by root, and the apps fail with *"Folder '/media/' is not writable by user 'hotio'"*. Create it with the right owner before first start: -Once the wizard finishes, you'll see an empty library. To populate it: +```bash +sudo mkdir -p /data/media/{downloads/prowlarr,movies,shows,music,books} +sudo chown -R 1000:1000 /data/media +sudo chmod -R u+rwX,g+rwX /data/media +``` -- Go to **Settings → Media Management** and add a **Root Folder** (e.g., `/media/movies`) — this is where your organized movie library will live -- Click **Add Movie** and search by title — Radarr fetches metadata, posters, and available releases -- Optionally connect a **List** (Trakt, IMDb, etc.) to auto-import movies from your watchlists +Check with `ls -ln /data/media` — the owner should be `1000 1000`. + +Open http://localhost:7878 in your browser. Do these in order: the qBittorrent download client and Prowlarr need to be connected before you add movies. + +1. **Create the admin account.** On first boot Radarr shows an *Authentication Required* dialog. Set **Authentication Method** to `Forms (Login Page)`, choose a username and password, click **Save**, and sign in. +2. **Copy Radarr's API key.** Go to **Settings → General → Security** and copy the **API Key**. Prowlarr needs it in step 4. +3. **Add the root folder.** Go to **Settings → Media Management → Add Root Folder** and choose `/media/movies`. Under **Importing**, turn on **Use Hardlinks instead of Copy** (click **Show Advanced** at the top if you don't see it). +4. **Connect Prowlarr.** This step is done in **Prowlarr** (http://localhost:9696), not Radarr. Go to **Settings → Apps → `+` → Radarr** and fill in: + + | Field | Value | + |---|---| + | Name | `Radarr` | + | Sync Level | `Full Sync` | + | Prowlarr Server | `http://prowlarr:9696` | + | Radarr Server | `http://radarr:7878` | + | API Key | the key from step 2 | + | Sync Categories | leave the defaults (Movies, `2000`-range) | + + Click **Test**. A green check means both directions work. Click **Save**. + + Then in Prowlarr, go to **Settings → Apps** and click **Sync App Indexers**. Back in Radarr, **Settings → Indexers** should now list every Prowlarr indexer, each named ` (Prowlarr)`. Don't add or edit indexers in Radarr. Prowlarr owns them and overwrites changes on the next sync. +5. **Add qBittorrent as the download client.** In Radarr, go to **Settings → Download Clients → `+` → qBittorrent**: + + | Field | Value | + |---|---| + | Name | `qBittorrent` | + | Host | `qbittorrent` | + | Port | `8080` | + | Username | `admin` | + | Password | `QBT_PASS` from the qBittorrent stack | + | Category | `prowlarr` | + + Click **Test**, then **Save**. The category makes qBittorrent save Radarr's downloads to `/media/downloads/prowlarr`, which Radarr can see at the same path. +6. **Add a movie.** Click **Add New**, search for a title, pick the root folder `/media/movies` and a quality profile, tick **Start search for missing movie**, then **Add Movie**. Check progress under **Activity → Queue**. + +Optionally connect a **List** (Trakt, IMDb, etc.) under **Settings → Lists** to auto-add movies from your watchlists. + +#### If the Prowlarr test fails + +- **"Unable to connect to Radarr"**: Prowlarr and Radarr must both be on the `proxy` network. Use container names, never `localhost`. Inside a container, `localhost` is the container itself. +- **"Unauthorized" or 401**: the API key is wrong. Copy it again from Radarr's **Settings → General**. +- **Test passes but no indexers show up in Radarr**: click **Sync App Indexers** in Prowlarr, and check that the indexers in Prowlarr support movie categories (`2000`-range). +- **Searches find nothing**: check **System → Status** in both apps for indexer health warnings. A Cloudflare-protected indexer needs the `flaresolverr` tag in Prowlarr (see the Prowlarr README). ### Download flow diff --git a/readarr_dev/README.md b/readarr_dev/README.md index d995858..2ad660f 100644 --- a/readarr_dev/README.md +++ b/readarr_dev/README.md @@ -12,6 +12,18 @@ Readarr is an automated eBook and audiobook collection manager for Usenet and Bi ## Getting Started +### Prepare the shared media folder (once per host) + +All media apps run as user `1000` and share `/data/media`. If Docker creates the folder itself it's owned by root, and the apps fail with *"Folder '/media/' is not writable by user 'hotio'"*. Create it with the right owner before first start: + +```bash +sudo mkdir -p /data/media/{downloads/prowlarr,movies,shows,music,books} +sudo chown -R 1000:1000 /data/media +sudo chmod -R u+rwX,g+rwX /data/media +``` + +Check with `ls -ln /data/media` — the owner should be `1000 1000`. + Open http://localhost:8787 in your browser and complete the initial setup wizard: 1. **Choose your UI language** diff --git a/sonarr/README.md b/sonarr/README.md index ea44929..88d72d9 100644 --- a/sonarr/README.md +++ b/sonarr/README.md @@ -12,6 +12,18 @@ Sonarr is an automated TV series collection manager for Usenet and BitTorrent us ## Getting Started +### Prepare the shared media folder (once per host) + +All media apps run as user `1000` and share `/data/media`. If Docker creates the folder itself it's owned by root, and the apps fail with *"Folder '/media/' is not writable by user 'hotio'"*. Create it with the right owner before first start: + +```bash +sudo mkdir -p /data/media/{downloads/prowlarr,movies,shows,music,books} +sudo chown -R 1000:1000 /data/media +sudo chmod -R u+rwX,g+rwX /data/media +``` + +Check with `ls -ln /data/media` — the owner should be `1000 1000`. + Open http://localhost:8989 in your browser and complete the initial setup wizard: 1. **Choose your UI language** diff --git a/stash/README.md b/stash/README.md index 62c1358..546292c 100644 --- a/stash/README.md +++ b/stash/README.md @@ -33,6 +33,7 @@ This Docker Compose configuration sets up the Stash application using Docker con /metadata – host path /data/stash/metadata /root/.stash – host path /data/stash/root /data – host path /data/stash + /adult – host path /data/media/adult (Whisparr's root folder) ## Network Notes @@ -57,6 +58,8 @@ See compose.yaml for the full set of environment variables. Point STASH_CONTENT_PATH at your library; first-run wizard configures the library paths. +If you use Whisparr, also add `/adult` as a library path. It's the same folder Whisparr imports into (`/data/media/adult` on the host), so turn on a scheduled scan to pick up new files. + ## Dockhand Stack, Deploy from Git Cookbooks Repository diff --git a/whisparr_dev/README.md b/whisparr/README.md similarity index 61% rename from whisparr_dev/README.md rename to whisparr/README.md index 51ee72e..01e5f48 100644 --- a/whisparr_dev/README.md +++ b/whisparr/README.md @@ -12,6 +12,18 @@ Whisparr is an automated adult content collection manager for Usenet and BitTorr ## Getting Started +### Prepare the shared media folder (once per host) + +All media apps run as user `1000` and share `/data/media`. If Docker creates the folder itself it's owned by root, and the apps fail with *"Folder '/media/' is not writable by user 'hotio'"*. Create it with the right owner before first start: + +```bash +sudo mkdir -p /data/media/{downloads/prowlarr,movies,shows,music,books,adult} +sudo chown -R 1000:1000 /data/media +sudo chmod -R u+rwX,g+rwX /data/media +``` + +Check with `ls -ln /data/media` — the owner should be `1000 1000`. + Open http://localhost:6969 in your browser and complete the initial setup wizard: 1. **Choose your UI language** @@ -20,7 +32,7 @@ Open http://localhost:6969 in your browser and complete the initial setup wizard Once the wizard finishes, you'll see an empty library. To populate it: -- Go to **Settings → Media Management** and add a **Root Folder** (e.g., `/media/adult`) — this is where your organized library will live +- Go to **Settings → Media Management** and add a **Root Folder** `/media/adult` — Stash sees this same folder at `/adult` - Click **Add Movie** and search by title — Whisparr fetches metadata and available releases - Optionally connect a **List** to auto-import from your watchlists @@ -36,7 +48,7 @@ qBittorrent downloads to `/media/downloads/prowlarr` → Whisparr picks it up, r | `WHISPARR_RESTART` | Restart policy (default: `unless-stopped`) | | `WHISPARR_PORT` | Published port for the web UI (default: `6969`) | | `VOL_PATH` | Base path for persistent data volumes (default: `/data`) | -| `WHISPARR_MEDIA` | Shared media root on the host (default: `/data/media`), mounted at `/media`. Must be the same folder qBittorrent, Sonarr, Radarr and Jellyfin use | +| `WHISPARR_MEDIA` | Shared media root on the host (default: `/data/media`), mounted at `/media`. Downloads land in `/media/downloads/prowlarr`, library in `/media/adult` | | `TZ` | Container timezone (default: `America/Vancouver`) | ## Volume Notes @@ -44,7 +56,7 @@ qBittorrent downloads to `/media/downloads/prowlarr` → Whisparr picks it up, r | Volume | Purpose | |---|---| | `${VOL_PATH:-/data}/whisparr/config` | Application configuration and database | -| `${WHISPARR_MEDIA:-/data/media}` → `/media` | Shared media root: downloads in `/media/downloads`, library in `/media/adult` | +| `${WHISPARR_MEDIA:-/data/media}` → `/media` | Shared media root: downloads in `/media/downloads/prowlarr`, library in `/media/adult` | ## Network Notes @@ -73,15 +85,16 @@ docker run -d \ ## Additional Notes / Gotchas -- **One shared media folder.** qBittorrent, Sonarr, Radarr, Whisparr and Jellyfin all use `/data/media` on the host, mounted at `/media`, so a download has the same path in every container: no Remote Path Mapping needed, and imports can use hardlinks. Enable **Settings → Media Management → Use Hardlinks instead of Copy**. -- **Layout:** `/data/media/downloads/prowlarr` (qBittorrent category `prowlarr`), `/data/media/adult` (Whisparr root, not mounted by Jellyfin by default). +- **Works with Stash, not Jellyfin.** Whisparr's library is `/data/media/adult` on the host. The Stash stack mounts that same folder at `/adult` (`STASH_ADULT_PATH`), so in Stash add **`/adult`** as a library path (Settings → Library). Jellyfin doesn't mount it. +- **One shared media folder.** qBittorrent and Whisparr both mount `/data/media` at `/media`, so download paths match (no Remote Path Mapping) and imports can use hardlinks. Enable **Settings → Media Management → Use Hardlinks instead of Copy**. +- **Rescan after import.** Turn on a scheduled library scan in Stash (or scan manually) so new imports show up. - In the qBittorrent download client settings, set **Category** to `prowlarr`. ## Dockhand Stack, Deploy from Git - **Cookbooks Repository** -- **stackname:** whisparr_dev -- **Compose file path:** whisparr_dev/compose.yaml -- **Additional env file (optional):** whisparr_dev/sample.env +- **stackname:** whisparr +- **Compose file path:** whisparr/compose.yaml +- **Additional env file (optional):** whisparr/sample.env -Load `whisparr_dev/sample.env` into the Environment variables in Dockhand, then create the Stack. +Load `whisparr/sample.env` into the Environment variables in Dockhand, then create the Stack. diff --git a/whisparr_dev/compose.yaml b/whisparr/compose.yaml similarity index 100% rename from whisparr_dev/compose.yaml rename to whisparr/compose.yaml diff --git a/whisparr_dev/sample.env b/whisparr/sample.env similarity index 100% rename from whisparr_dev/sample.env rename to whisparr/sample.env