Skip to content

Commit 173e5c4

Browse files
bcanfieldbcanfield
committed
docs
1 parent cadd915 commit 173e5c4

6 files changed

Lines changed: 150 additions & 171 deletions

File tree

‎README.md‎

Lines changed: 31 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,6 @@
22

33
Automated media management stack running on Docker. Handles requesting, downloading, organizing, and subtitling media — with Jellyfin running on a separate server for playback.
44

5-
## Key Files
6-
7-
- `docker-compose.yml` — core service definitions
8-
- `extras/docker-compose.yml` — optional services (dashboard, library maintenance, audiobooks)
9-
- `.env` / `.env.example` — Docker Compose environment variables (paths, PUID/PGID, timezone)
10-
115
## Architecture
126

137
```mermaid
@@ -19,187 +13,53 @@ graph LR
1913
Storage --> Jellyfin
2014
```
2115

22-
## Core Services
23-
24-
| Service | Port | Purpose | Setup Guide |
25-
| ------------------------------------------------- | ---- | ------------------------------------------------------------- | -------------------------------------- |
26-
| [Seerr](https://github.com/seerr-team/seerr) | 5055 | User-facing request portal for movies and TV | [docs/seerr.md](docs/seerr.md) |
27-
| [Sonarr](https://wiki.servarr.com/sonarr) | 8989 | TV show management and automation | [docs/sonarr.md](docs/sonarr.md) |
28-
| [Radarr](https://wiki.servarr.com/radarr) | 7878 | Movie management and automation | [docs/radarr.md](docs/radarr.md) |
29-
| [SABnzbd](https://sabnzbd.org/wiki/) | 8080 | Usenet download client | [docs/sabnzbd.md](docs/sabnzbd.md) |
30-
| [Bazarr](https://wiki.bazarr.media/) | 6767 | Automatic subtitle downloading | [docs/bazarr.md](docs/bazarr.md) |
31-
| [Prowlarr](https://wiki.servarr.com/prowlarr) | 9696 | Centralized indexer management, syncs to Sonarr/Radarr | [docs/prowlarr.md](docs/prowlarr.md) |
32-
| [Recyclarr](https://recyclarr.dev/) | — | Syncs TRaSH quality profiles to Sonarr/Radarr on a daily cron | [docs/recyclarr.md](docs/recyclarr.md) |
33-
| [Tailscale](https://tailscale.com/kb/1282/docker) | — | Private VPN for secure remote access without port forwarding | — |
34-
35-
## Extras (Optional)
16+
## Services
3617

37-
| Service | Port | Purpose | Setup Guide |
38-
| ----------------------------------------------------- | ----- | ---------------------------------------------- | ------------------------------------------------ |
39-
| [Homepage](https://gethomepage.dev/) | 3000 | YAML-configured dashboard with service widgets | [docs/homepage.md](docs/homepage.md) |
40-
| [Maintainerr](https://docs.maintainerr.info/) | 6246 | Automated library maintenance based on rules | [docs/maintainerr.md](docs/maintainerr.md) |
41-
| [LazyLibrarian](https://lazylibrarian.gitlab.io/) | 5299 | Book/audiobook search and download management | [docs/lazylibrarian.md](docs/lazylibrarian.md) |
42-
| [Audiobookshelf](https://www.audiobookshelf.org/docs) | 13378 | Self-hosted audiobook server with mobile apps | [docs/audiobookshelf.md](docs/audiobookshelf.md) |
18+
| Service | Port | Purpose | Guide |
19+
| --- | --- | --- | --- |
20+
| [Seerr](https://github.com/seerr-team/seerr) | 5055 | Media request portal | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/Seerr) |
21+
| [Sonarr](https://wiki.servarr.com/sonarr) | 8989 | TV show management | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/Sonarr) |
22+
| [Radarr](https://wiki.servarr.com/radarr) | 7878 | Movie management | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/Radarr) |
23+
| [SABnzbd](https://sabnzbd.org/wiki/) | 8080 | Usenet downloader | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/SABnzbd) |
24+
| [Bazarr](https://wiki.bazarr.media/) | 6767 | Automatic subtitles | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/Bazarr) |
25+
| [Prowlarr](https://wiki.servarr.com/prowlarr) | 9696 | Indexer management | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/Prowlarr) |
26+
| [Recyclarr](https://recyclarr.dev/) | — | TRaSH quality profile sync | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/Recyclarr) |
27+
| [Tailscale](https://tailscale.com/kb/1282/docker) | — | VPN for remote access | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/Tailscale) |
4328

44-
## Why Run Jellyfin on a Separate Server?
45-
46-
Jellyfin handles real-time transcoding which is CPU/GPU intensive. Running it on a dedicated VM or machine means:
47-
48-
- **Transcoding doesn't starve downloads** — SABnzbd and the *arr apps keep running at full speed during heavy playback.
49-
- **Independent scaling** — give the playback server a GPU or more RAM without over-provisioning the automation stack.
50-
- **Isolation** — a Jellyfin crash or update doesn't take down your download pipeline (and vice versa).
51-
52-
Both servers just need access to the same shared media storage (NFS, SMB, etc.).
29+
### Extras (Optional)
5330

54-
## Setup
31+
| Service | Port | Purpose | Guide |
32+
| --- | --- | --- | --- |
33+
| [Homepage](https://gethomepage.dev/) | 3000 | Dashboard with service widgets | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/Homepage) |
34+
| [Maintainerr](https://docs.maintainerr.info/) | 6246 | Automated library maintenance | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/Maintainerr) |
35+
| [LazyLibrarian](https://lazylibrarian.gitlab.io/) | 5299 | Book/audiobook management | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/LazyLibrarian) |
36+
| [Audiobookshelf](https://www.audiobookshelf.org/docs) | 13378 | Audiobook server + mobile apps | [Wiki](https://github.com/bcanfield/docker-media-server/wiki/Audiobookshelf) |
5537

56-
1. Clone the repo and copy the example env file:
38+
## Quick Start
5739

5840
```bash
5941
git clone https://github.com/bcanfield/docker-media-server.git
6042
cd docker-media-server
61-
cp .env.example .env
62-
```
63-
64-
2. Edit `.env` with your values:
65-
66-
```env
67-
TZ=America/New_York # Your timezone
68-
PUID=1000 # id $USER
69-
PGID=1000
70-
MEDIA_ROOT=/mnt/media # Where downloads and organized media live
71-
CONFIG_ROOT=/opt/config-root # Where app configs are stored
72-
SABNZBD_TEMP=/opt/sabnzbd-temp # SSD-backed path for SABnzbd temp downloads
73-
```
74-
75-
3. Start the core stack:
76-
77-
```bash
43+
cp .env.example .env # edit with your paths, timezone, and Tailscale key
7844
docker compose up -d
7945
```
8046

81-
4. Configure each service through its web UI (see the [setup guides](docs/) for each service):
82-
- Point Sonarr/Radarr to SABnzbd as the download client
83-
- Point Seerr to Sonarr/Radarr
84-
- Point Bazarr to Sonarr/Radarr for subtitle fetching
85-
- Add indexers in Prowlarr and sync to Sonarr/Radarr
86-
87-
### Extras (Optional)
47+
Then configure each service through its web UI — see the [wiki](https://github.com/bcanfield/docker-media-server/wiki) for per-service setup guides.
8848

89-
To run the optional services alongside the core stack:
49+
### Extras
9050

9151
```bash
9252
cd extras
93-
cp .env.example .env # edit with your values
94-
cp -r homepage/ ${CONFIG_ROOT}/config/homepage/ # starter dashboard config
53+
cp .env.example .env
54+
cp -r homepage/ ${CONFIG_ROOT}/config/homepage/
9555
docker compose --env-file ../.env --env-file .env up -d
9656
```
9757

98-
The extras compose uses the same `sofa-squad` network as the core stack, so all services can communicate.
99-
100-
## Remote Access with Tailscale
101-
102-
[Tailscale](https://tailscale.com/) creates a private VPN (tailnet) between your devices, letting you securely access all your services from anywhere — no port forwarding or exposing anything to the public internet.
103-
104-
### Setup
105-
106-
1. **Create a Tailscale account** at [tailscale.com](https://tailscale.com/) (free for personal use, up to 100 devices).
107-
108-
2. **Install Tailscale on your client devices** (phone, laptop, etc.) from [tailscale.com/download](https://tailscale.com/download).
109-
110-
3. **Generate an auth key** at [Admin Console > Settings > Keys](https://login.tailscale.com/admin/settings/keys). Use a **reusable** key so the container can re-authenticate after restarts.
111-
112-
4. **Add the key to your `.env`:**
113-
114-
```env
115-
TS_AUTHKEY=tskey-auth-your-key-here
116-
TS_HOSTNAME=media-server
117-
```
118-
119-
5. **Start (or restart) the stack:**
120-
121-
```bash
122-
docker compose up -d
123-
```
124-
125-
6. **Approve the node** in the [Tailscale Admin Console](https://login.tailscale.com/admin/machines) if prompted.
126-
127-
### Accessing Services Remotely
128-
129-
Once Tailscale is running on both your server and your client device, access services using your Tailscale hostname:
130-
131-
| Service | Remote URL |
132-
| -------------- | --------------------------- |
133-
| Seerr | `http://media-server:5055` |
134-
| Sonarr | `http://media-server:8989` |
135-
| Radarr | `http://media-server:7878` |
136-
| SABnzbd | `http://media-server:8080` |
137-
| Bazarr | `http://media-server:6767` |
138-
| Prowlarr | `http://media-server:9696` |
139-
| Homepage | `http://media-server:3000` |
140-
| LazyLibrarian | `http://media-server:5299` |
141-
| Audiobookshelf | `http://media-server:13378` |
142-
143-
Replace `media-server` with whatever you set `TS_HOSTNAME` to. You can also use the Tailscale IP shown in the admin console.
144-
145-
### Enabling HTTPS (Optional)
146-
147-
Tailscale can provision [automatic HTTPS certificates](https://tailscale.com/kb/1153/enabling-https) for your tailnet:
148-
149-
1. Enable HTTPS in [Admin Console > DNS](https://login.tailscale.com/admin/dns).
150-
2. Access services at `https://media-server.your-tailnet.ts.net:<port>`.
151-
152-
### Enabling MagicDNS
153-
154-
With [MagicDNS](https://tailscale.com/kb/1081/magicdns) enabled (on by default), you can use short hostnames like `media-server` instead of full IPs across your tailnet.
155-
156-
## Backups
157-
158-
`extras/backup/` backs up service configs to S3-compatible storage (e.g., DigitalOcean Spaces) using [restic](https://restic.net/). Safely snapshots SQLite databases before backup.
159-
160-
```bash
161-
# Install dependencies
162-
apt install -y restic sqlite3
163-
164-
# Configure
165-
cd extras/backup
166-
cp .env.example .env # fill in your S3 credentials, restic password, and backup path
167-
168-
# Initialize restic repo (once)
169-
set -a && source .env && set +a
170-
restic init
171-
172-
# Test a backup
173-
./backup-config.sh
174-
175-
# Schedule daily at 3 AM
176-
(crontab -l 2>/dev/null; echo "0 3 * * * $(pwd)/backup-config.sh >> /var/log/restic-backup.log 2>&1") | crontab -
177-
```
178-
179-
Restore:
180-
```bash
181-
cd extras/backup
182-
set -a && source .env && set +a
183-
restic snapshots # list snapshots
184-
restic restore latest --target /tmp/restore # restore latest
185-
```
186-
187-
## Recommended Usenet Indexers
188-
189-
Managed via Prowlarr. Running multiple indexers improves coverage — each has different sources and retention depths. 2-3 indexers is the sweet spot.
190-
191-
| Indexer | Registration | Cost | Strength |
192-
| --------------------------------------- | ------------ | --------------------------- | -------------------------------------------------------------- |
193-
| [NZBgeek](https://nzbgeek.info/) | Open | ~$12/year | Reliable all-rounder, great for current content |
194-
| [NZBPlanet](https://nzbplanet.net/) | Open (paid) | 8 EUR/year | Largest index (~3M NZBs), strong for older/obscure content |
195-
| [NZBFinder](https://nzbfinder.ws/) | Open | Free tier / ~15-35 EUR/year | Always-open registration, fast indexing, good free tier |
196-
| [DrunkenSlug](https://drunkenslug.com/) | Invite-only | ~10-20 EUR/year | Top-tier quality, watch r/usenet for open registration windows |
197-
| [DOGnzb](https://dognzb.cr/) | Invite-only | $37/year | 4,800+ days retention, IMDb/Trakt watchlist sync |
198-
199-
**Currently using:** NZBgeek, NZBPlanet, NZBFinder
200-
201-
## Resources
58+
## More
20259

203-
- [LinuxServer.io](https://docs.linuxserver.io/) — maintains most of the Docker images used here
204-
- [TRaSH Guides](https://trash-guides.info/) — quality profile recommendations (synced via Recyclarr)
205-
- [Servarr Wiki](https://wiki.servarr.com/) — docs for Sonarr, Radarr, and related apps
60+
- [Tailscale / Remote Access](https://github.com/bcanfield/docker-media-server/wiki/Tailscale)
61+
- [Backups](https://github.com/bcanfield/docker-media-server/wiki/Backups)
62+
- [Usenet Indexers](https://github.com/bcanfield/docker-media-server/wiki/Usenet-Indexers)
63+
- [TRaSH Guides](https://trash-guides.info/) — quality profile recommendations
64+
- [Servarr Wiki](https://wiki.servarr.com/) — Sonarr, Radarr, Prowlarr docs
65+
- [LinuxServer.io](https://docs.linuxserver.io/) — Docker image maintainers

‎docs/Home.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,9 @@ Setup guides for each service in the stack. See the [README](https://github.com/
1818
- [Maintainerr](Maintainerr) — library maintenance
1919
- [LazyLibrarian](LazyLibrarian) — book management
2020
- [Audiobookshelf](Audiobookshelf) — audiobook server
21+
22+
## Guides
23+
24+
- [Tailscale / Remote Access](Tailscale) — VPN setup for accessing services from anywhere
25+
- [Backups](Backups) — S3-compatible config backups with restic
26+
- [Usenet Indexers](Usenet-Indexers) — recommended indexers for Prowlarr

‎docs/_Sidebar.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,8 @@
1212
- [Maintainerr](Maintainerr)
1313
- [LazyLibrarian](LazyLibrarian)
1414
- [Audiobookshelf](Audiobookshelf)
15+
16+
**Guides**
17+
- [Tailscale / Remote Access](Tailscale)
18+
- [Backups](Backups)
19+
- [Usenet Indexers](Usenet-Indexers)

‎docs/backups.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Backups
2+
3+
`extras/backup/` backs up service configs to S3-compatible storage (e.g., DigitalOcean Spaces) using [restic](https://restic.net/). Safely snapshots SQLite databases before backup.
4+
5+
## Setup
6+
7+
```bash
8+
# Install dependencies
9+
apt install -y restic sqlite3
10+
11+
# Configure
12+
cd extras/backup
13+
cp .env.example .env # fill in your S3 credentials, restic password, and backup path
14+
15+
# Initialize restic repo (once)
16+
set -a && source .env && set +a
17+
restic init
18+
19+
# Test a backup
20+
./backup-config.sh
21+
22+
# Schedule daily at 3 AM
23+
(crontab -l 2>/dev/null; echo "0 3 * * * $(pwd)/backup-config.sh >> /var/log/restic-backup.log 2>&1") | crontab -
24+
```
25+
26+
## Restore
27+
28+
```bash
29+
cd extras/backup
30+
set -a && source .env && set +a
31+
restic snapshots # list snapshots
32+
restic restore latest --target /tmp/restore # restore latest
33+
```
34+
35+
## What It Does
36+
37+
- Snapshots all SQLite `.db` files to `.db.bak` before backing up (prevents corruption)
38+
- Excludes live database files and journals (only the safe `.bak` copies are backed up)
39+
- Prunes old snapshots: keeps 7 daily, 4 weekly, 3 monthly
40+
- Cleans up `.bak` files after backup completes

‎docs/tailscale.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Remote Access with Tailscale
2+
3+
[Tailscale](https://tailscale.com/) creates a private VPN (tailnet) between your devices, letting you securely access all your services from anywhere — no port forwarding or exposing anything to the public internet.
4+
5+
## Setup
6+
7+
1. **Create a Tailscale account** at [tailscale.com](https://tailscale.com/) (free for personal use, up to 100 devices).
8+
9+
2. **Install Tailscale on your client devices** (phone, laptop, etc.) from [tailscale.com/download](https://tailscale.com/download).
10+
11+
3. **Generate an auth key** at [Admin Console > Settings > Keys](https://login.tailscale.com/admin/settings/keys). Use a **reusable** key so the container can re-authenticate after restarts.
12+
13+
4. **Add the key to your `.env`:**
14+
15+
```env
16+
TS_AUTHKEY=tskey-auth-your-key-here
17+
TS_HOSTNAME=media-server
18+
```
19+
20+
5. **Start (or restart) the stack:**
21+
22+
```bash
23+
docker compose up -d
24+
```
25+
26+
6. **Approve the node** in the [Tailscale Admin Console](https://login.tailscale.com/admin/machines) if prompted.
27+
28+
## Accessing Services Remotely
29+
30+
Once Tailscale is running on both your server and your client device, access services using your Tailscale hostname:
31+
32+
| Service | Remote URL |
33+
| -------------- | --------------------------- |
34+
| Seerr | `http://media-server:5055` |
35+
| Sonarr | `http://media-server:8989` |
36+
| Radarr | `http://media-server:7878` |
37+
| SABnzbd | `http://media-server:8080` |
38+
| Bazarr | `http://media-server:6767` |
39+
| Prowlarr | `http://media-server:9696` |
40+
| Homepage | `http://media-server:3000` |
41+
| LazyLibrarian | `http://media-server:5299` |
42+
| Audiobookshelf | `http://media-server:13378` |
43+
44+
Replace `media-server` with whatever you set `TS_HOSTNAME` to. You can also use the Tailscale IP shown in the admin console.
45+
46+
## Enabling HTTPS (Optional)
47+
48+
Tailscale can provision [automatic HTTPS certificates](https://tailscale.com/kb/1153/enabling-https) for your tailnet:
49+
50+
1. Enable HTTPS in [Admin Console > DNS](https://login.tailscale.com/admin/dns).
51+
2. Access services at `https://media-server.your-tailnet.ts.net:<port>`.
52+
53+
## Enabling MagicDNS
54+
55+
With [MagicDNS](https://tailscale.com/kb/1081/magicdns) enabled (on by default), you can use short hostnames like `media-server` instead of full IPs across your tailnet.

‎docs/usenet-indexers.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Recommended Usenet Indexers
2+
3+
Managed via Prowlarr. Running multiple indexers improves coverage — each has different sources and retention depths. 2-3 indexers is the sweet spot.
4+
5+
| Indexer | Registration | Cost | Strength |
6+
| --------------------------------------- | ------------ | --------------------------- | -------------------------------------------------------------- |
7+
| [NZBgeek](https://nzbgeek.info/) | Open | ~$12/year | Reliable all-rounder, great for current content |
8+
| [NZBPlanet](https://nzbplanet.net/) | Open (paid) | 8 EUR/year | Largest index (~3M NZBs), strong for older/obscure content |
9+
| [NZBFinder](https://nzbfinder.ws/) | Open | Free tier / ~15-35 EUR/year | Always-open registration, fast indexing, good free tier |
10+
| [DrunkenSlug](https://drunkenslug.com/) | Invite-only | ~10-20 EUR/year | Top-tier quality, watch r/usenet for open registration windows |
11+
| [DOGnzb](https://dognzb.cr/) | Invite-only | $37/year | 4,800+ days retention, IMDb/Trakt watchlist sync |
12+
13+
**Currently using:** NZBgeek, NZBPlanet, NZBFinder

0 commit comments

Comments
 (0)