liamvibecodes/mac-media-stack-advanced: Advanced self-hosted media server for macOS. Auto-healing, transcoding (Tdarr), quality profiles (Recyclarr), metadata automation (Kometa), download watchdog, VPN failover, and automated backups. · GitHub

Fully automated, self-healing media server for macOS
Everything from the basic stack, plus transcoding, quality profiles, metadata automation, download watchdog, VPN failover, and automated backups.

There are dozens of *arr stack Docker Compose repos on GitHub. Almost all of them dump a compose file and leave you to figure out the rest. This one is different:

• One command to install. Clone, configure, and start everything with a single curl | bash. No 45-minute manual setup.
• Auto-configures itself. The configure script wires up the core request/download stack via API (qBittorrent, Prowlarr, Radarr, Sonarr, Seerr). No clicking through those web UIs.
• Auto-wires keys. The configure script also writes Radarr/Sonarr API keys into Recyclarr and Unpackerr automatically.
• Built for macOS. Native paths, launchd instead of systemd, OrbStack or Docker Desktop instead of bare Docker. Not a Linux guide with "should work on Mac" in the footnotes.
• Self-healing. Hourly health checks, download watchdog, VPN failover between providers. Runs unattended.
• Quality automation. TRaSH Guides profiles filter out bad releases. Kometa keeps Plex metadata clean. Tdarr runs native-first on macOS with a quality-preserving flow preset.

New to self-hosted media? Start with the basic version first.

Default is Plex. To use Jellyfin, pass --jellyfin to the bootstrap command.

When running with MEDIA_SERVER=jellyfin, the stack includes these extras that close the gap with Plex Pass users:

Intro Skipper and TMDb Box Sets are auto-installed as Jellyfin plugins by configure.sh. Jellystat runs as a separate Docker service behind the jellyfin profile.

After the stack is running:

1. Open http://localhost:3000
2. Create an admin account
3. Connect to your Jellyfin server: http://jellyfin:8096
4. Enter your Jellyfin API key (Administration > API Keys)

Jellystat will start tracking watch history, user activity, and library statistics automatically.

Transparent cloud/local or NAS/local merged library. rclone FUSE-mounts your remote storage inside Docker (where FUSE works natively on macOS), mergerfs overlays it with local storage, and all existing services see a single unified path. Local-first writes keep downloads fast; a periodic upload script moves stable media to the remote.

Supports Google Drive, S3, Backblaze B2, Dropbox, NAS via SFTP (TrueNAS, Synology, Unraid), and 40+ other providers.

• Set MEDIA_SERVER=jellyfin for cloud-backed playback.
• Set TDARR_MODE=docker if you use Tdarr with cloud storage.
• Native macOS apps (like Plex app and native Tdarr) cannot read Docker FUSE merged mounts directly.

bash scripts/setup-cloud-storage.sh
docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile jellyfin --profile tdarr-docker up -d

If you also use optional profiles, append them to the same command (example: --profile jellyfin, --profile music, --profile tdarr-docker).

Or include it in bootstrap:

bash bootstrap.sh --jellyfin --cloud-storage

bash scripts/setup-cloud-storage.sh --storage-type nas
docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile jellyfin --profile tdarr-docker up -d

Or include it in bootstrap:

bash bootstrap.sh --jellyfin --nas-storage

rclone-mount  -->  FUSE mounts cloud provider to /cloud
mergerfs      -->  overlays /local + /cloud into /merged
Radarr/Sonarr -->  read/write /merged (local-first writes)
cloud-upload  -->  periodically moves stable files to remote (6h/24h for cloud, 2h for NAS)

• Jellyfin (Docker): keep /data/movies and /data/tvshows (override maps those to merged paths).
• Tdarr Docker mode: keep /movies and /tv (override maps those to merged paths).

Platform notes:

• TrueNAS: Media path is typically /mnt/pool/dataset/media
• Synology: Path is /volume1/media. The setup wizard auto-adds a path_override config (equivalent to --sftp-path-override) for SFTP chroot compatibility.
• Unraid: Path is /mnt/user/media

Performance: rclone SFTP delivers ~100MB/s on Gigabit LAN, adequate for multiple concurrent 4K streams.

Cloud mode note: Use TDARR_MODE=docker when cloud storage is enabled. Native Tdarr cannot access merged Docker FUSE mounts on macOS.

Music services use Docker Compose profiles and are not started by default. To enable:

bash scripts/setup-music.sh
docker compose --profile music up -d

If cloud storage is enabled, use:

docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile music up -d

Then open Tidarr at http://localhost:8484 to authenticate with your Tidal account, and Lidarr at http://localhost:8686 to configure your music library. See the Music Setup section below for details.

Franchise sorting is kept manual by default because it requires your Plex token: PLEX_TOKEN=... python3 scripts/franchise-sort.py

• Default is TDARR_MODE=native (recommended on macOS).
• Native Tdarr is installed and managed by scripts/setup-tdarr-native.sh (launchd server + node).
• Docker Tdarr remains available via TDARR_MODE=docker and --profile tdarr-docker.
• The stack preloads this Tdarr flow preset: Quality-First HEVC (Resolution Preserving).
  • No resolution downscale
  • No hard bitrate cap
  • H.264 -> H.265 (CRF 19, preset slow)
  • Replace only when output size ratio stays within 25-99%

The download watchdog reads qBittorrent credentials and behavior settings from environment variables or automatically detects them from your config files. Optional environment variables:

• QBIT_USERNAME (default: admin)
• QBIT_PASSWORD (auto-detected from qBittorrent config if not set)
• WATCHDOG_STALL_SECONDS (default: 1800 — how long a torrent must be stalled before auto-swap)
• WATCHDOG_SLOW_SECONDS (default: 1200 — how long a torrent must be slow before auto-swap)
• WATCHDOG_MIN_SPEED_BPS (default: 307200 — 300 KB/s minimum speed threshold)
• WATCHDOG_MAX_SWAP_PROGRESS (default: 0.25 — never swap torrents past 25% complete)

Set these in .env or your shell environment if you need to customize watchdog behavior.

Requires OrbStack (or Docker Desktop) and either Plex installed or the --jellyfin flag. Handles everything else.

curl -fsSL https://raw.githubusercontent.com/liamvibecodes/mac-media-stack-advanced/main/bootstrap.sh | bash

Optional flags when running from a local clone:

bash bootstrap.sh --media-dir /Volumes/T9/Media --install-dir ~/mac-media-stack-advanced --non-interactive

Use Docker-based Tdarr instead of native Tdarr:

bash bootstrap.sh --tdarr-docker

To use Jellyfin instead of Plex:

bash bootstrap.sh --jellyfin

NAS storage via SFTP (TrueNAS, Synology, Unraid):

bash bootstrap.sh --jellyfin --nas-storage

Already cloned an older version and want the latest release tag without reinstalling?

One-liner (run inside your existing clone directory):

bash <(curl -fsSL https://raw.githubusercontent.com/liamvibecodes/mac-media-stack-advanced/main/scripts/update-to-latest-release.sh)

Local script (once present):

bash scripts/update-to-latest-release.sh

Already running mac-media-stack and want to keep your existing library/configs?

Use the one-shot upgrader: UPGRADE.md

bash scripts/upgrade-from-basic.sh

If you prefer to run each step yourself:

git clone https://github.com/liamvibecodes/mac-media-stack-advanced.git
cd mac-media-stack-advanced
bash scripts/setup.sh            # or: bash scripts/setup.sh --media-dir /Volumes/T9/Media
# edit .env with VPN keys
bash scripts/doctor.sh           # preflight validation before first boot
docker compose up -d
# if MEDIA_SERVER=jellyfin in .env:
docker compose --profile jellyfin up -d
# if TDARR_MODE=docker in .env:
docker compose --profile tdarr-docker up -d
# if TDARR_MODE=native in .env (default):
bash scripts/setup-tdarr-native.sh
docker compose --profile autoupdate up -d watchtower  # optional auto-updates
bash scripts/configure.sh
bash scripts/install-launchd-jobs.sh

The watchtower line above enables automatic container image updates (scheduled daily at 04:00 in compose). It's optional but recommended so your services stay patched without manual pulls.

See SETUP.md for the complete walkthrough. Upgrading from basic? See UPGRADE.md. Pinned digest matrix: IMAGE_LOCK.md

By default, Seerr is bound to 127.0.0.1 for safer local-only access. Set SEERR_BIND_IP=0.0.0.0 in .env only if you intentionally want LAN exposure.

Seerr (request) -> Radarr/Sonarr -> Prowlarr (search) -> qBittorrent (via VPN) -> Plex or Jellyfin (watch)
                                                           |
                                     Unpackerr (extract) --+
                                     Bazarr (subtitles) ----+
                                     Tdarr (transcode) -----+
                                     Kometa (metadata) ------> Plex
                                     Recyclarr (quality) ----> Radarr/Sonarr

Optional music:
                   Lidarr (music management) -> Prowlarr / Tidarr -> Plex (listen)
                   Tidarr (Tidal FLAC downloads) ----^

All download traffic routes through ProtonVPN (with optional NordVPN failover). Gluetun's built-in kill switch blocks traffic if the VPN drops, so your real IP is never exposed through the tunnel. Everything else uses your normal connection. All services auto-start on boot and self-heal if they go down.

To manually switch providers after creating .env.nord from .env.nord.example:

bash scripts/vpn-mode.sh nord

Pre-configured templates in configs/ (copy to your Media folder after first boot):

• recyclarr.yml - TRaSH Guides quality profiles for Radarr and Sonarr
• kometa.yml - Plex metadata automation (franchise collections, resolution overlays)
• tdarr-flow-quality-first-hevc.json - Quality-first H.264 -> H.265 flow preset loaded by scripts/tdarr-apply-quality-flow.sh

Recyclarr API keys are auto-injected by scripts/configure.sh. Kometa still needs your manual Plex token + TMDB API key.

Music is optional and uses Docker Compose profiles. The core stack works without it.

• Lidarr manages your music library the same way Radarr handles movies. It monitors artists, searches for albums via Prowlarr, and imports downloads into your Plex music folder.
• Tidarr downloads FLAC directly from Tidal (up to 24-bit/192kHz Hi-Res). It has a web UI for manual downloads and also acts as an indexer + download client for Lidarr, so Lidarr can search and download from Tidal automatically.

# 1. Create music directories and config
bash scripts/setup-music.sh

# 2. Start the music services
docker compose --profile music up -d

# 3. Authenticate with Tidal
#    Open http://localhost:8484 and follow the OAuth device flow

# 4. Configure Lidarr
#    Open http://localhost:8686
#    - Settings > Media Management > Add root folder: /music
#    - Settings > Download Clients > Add SABnzbd:
#        Host: tidarr, Port: 8484, URL Base: /api/sabnzbd
#    - Settings > Indexers > Add Newznab:
#        URL: http://tidarr:8484, API Path: /api/lidarr
#        Categories: 3000, 3010, 3040
#    - Settings > Download Clients > Add qBittorrent (for torrent fallback):
#        Host: gluetun, Port: 8080

If cloud storage is enabled, use this start command in step 2 instead:

docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile music up -d

The setup script creates a default tiddl config at <MEDIA_DIR>/config/tidarr/.tiddl/config.toml (default <MEDIA_DIR> is ~/Media). Key settings:

• Quality: max (24-bit Hi-Res FLAC when available, falls back to 16-bit/44.1kHz)
• Download path: Your Plex music folder (files go directly to the library)
• Skip existing: Won't re-download albums you already have
• File template: Artist/Album/01 Track Title.flac (Plex-compatible naming)

If your music files have inconsistent metadata (different featuring formats, year suffixes in folder names, missing album artist tags), the cleanup script fixes common issues:

# Preview what would change (dry run, nothing is modified)
python3 scripts/music-cleanup.py

# Apply fixes
python3 scripts/music-cleanup.py --apply

# Custom music directory
python3 scripts/music-cleanup.py --path /Volumes/External/Music

Requires mutagen: pip install mutagen

# Start music services
docker compose --profile music up -d

# Stop only music services (keeps everything else running)
docker compose --profile music stop lidarr tidarr

# Include music in all future docker compose commands
# Add to your shell profile:
export COMPOSE_PROFILES=music

If cloud storage is enabled, include both compose files and profiles when starting music services:

docker compose -f docker-compose.yml -f docker-compose.cloud-storage.yml --profile cloud-storage --profile music up -d

If you're running out of space on your primary drive, the archive script moves old or watched media to an external drive. Dry-run by default so you can preview what would be moved before committing.

# Preview candidates (nothing gets moved)
bash scripts/archive-media.sh --archive /Volumes/External/Media-Archive

# Archive movies older than 6 months that are 8GB+
bash scripts/archive-media.sh --execute --archive /Volumes/External/Media-Archive --type movies

# Only archive stuff you've already watched (uses Plex watch state)
bash scripts/archive-media.sh --execute --archive /Volumes/External/Media-Archive --only-watched

# Jellyfin users: pass your API key for watched-state filtering
bash scripts/archive-media.sh --execute --archive /Volumes/External/Media-Archive --only-watched --jellyfin-api-key YOUR_KEY

Protecting favorites: scripts/setup.sh creates <MEDIA_DIR>/config/archive-exceptions.txt for you (default <MEDIA_DIR> is ~/Media). Add one title per line and anything listed won't be archived regardless of age or size. See configs/archive-exceptions.txt.example for the format.

The script verifies file counts after copying and only deletes the source if the counts match. If verification fails, your original files are untouched.

Built by @liamvibecodes

MIT