Architecture¶

This page explains how the stack fits together: what talks to what, which network each container lives on, where the VPN boundary runs, where data lives, and why it is built this way. It is for anyone who wants to understand the stack before changing it. The step-by-step stories (a request, a download, a boot) are in the flow pages linked below.

System context¶

The server runs one Docker Compose project. People reach it through Tailscale or, for three apps, the home network. It reaches out to the internet for downloads, searches and metadata, and only peer-to-peer traffic goes through the VPN.

flowchart LR
  you["You"]
  viewers["Viewers"]
  homedev["Home network devices"]
  server["The server (Docker Compose stack)"]

  proton["Proton VPN"]
  peers["Torrent and Soulseek peers"]
  usenet["Usenet provider"]
  indexers["Indexer sites"]
  metadata["Metadata and subtitle APIs"]
  ntfy["ntfy"]
  tailscale["Tailscale coordination"]
  registries["Image registries"]
  offsite["Offsite backup (optional)"]

  you -->|"tailnet: every port"| server
  viewers -->|"tailnet: their apps"| server
  homedev -->|"Jellyfin, Seerr, games page"| server

  server -->|"WireGuard"| proton
  proton --> peers
  server -->|"TLS, direct"| usenet
  server -->|"searches, direct"| indexers
  server --> metadata
  server -->|"alerts"| ntfy
  server --> tailscale
  server -->|"image pulls"| registries
  server -.->|"restic"| offsite

Containers and networks¶

Almost every container sits on one Docker bridge network, arr (172.18.0.0/16), and reaches the others by name (http://radarr:7878). Four things differ: the VPN pair lives inside gluetun's network namespace, Plex uses the host's network, Needle is published only on the loopback address for Tailscale Serve, and nothing but socket-proxy touches the Docker socket.

flowchart TB
  subgraph host["Host network"]
    plex["Plex :32400"]
    serve["Tailscale Serve :4535 (HTTPS)"]
    sock[("docker.sock")]
  end

  subgraph arrnet["Docker network arr, 172.18.0.0/16"]
    subgraph gns["gluetun network namespace"]
      gluetun["gluetun"]
      qbit["qBittorrent :8080"]
      slskd["slskd :5030"]
    end

    arrapps["Radarr, Sonarr, Lidarr"]
    prowlarr["Prowlarr (fixed IP)"]
    byparr["Byparr :8191"]
    sab["SABnzbd"]
    front["Seerr, Questarr, Bazarr, Cleanuparr"]
    jellyfin["Jellyfin"]
    navidrome["Navidrome"]
    needle["Needle (127.0.0.1:4535)"]
    dash["Homepage, Glance, Dozzle"]
    proxy["socket-proxy (read-only)"]
    metrics["Prometheus, Scraparr, node-exporter"]
  end

  arrapps -->|"gluetun:8080"| qbit
  arrapps -->|"gluetun:5030"| slskd
  arrapps --> sab
  arrapps --> prowlarr
  front --> arrapps
  prowlarr --> byparr
  needle --> navidrome
  needle -->|"gluetun:5030"| slskd
  needle --> arrapps
  serve --> needle
  dash -->|"socket-proxy:2375"| proxy
  proxy --> sock
  metrics --> arrapps

• gluetun's namespace. qBittorrent and slskd use network_mode: "service:gluetun": they have no network of their own. Other containers reach them at gluetun:8080 and gluetun:5030, and gluetun publishes those two ports for you. See The VPN boundary.
• Prowlarr's fixed address (PROWLARR_IP, default 172.18.0.200). Questarr trusts Prowlarr's download links only when their host matches the indexer URL it was given, and Prowlarr writes the address it was called on into those links. Questarr connects by IP, so that IP must never change.
• Plex and node-exporter on the host network (network_mode: host). Plex's port 32400 is the host's own, and node-exporter needs the host's network to count the server's traffic rather than its own container's. Uptime Kuma and Prometheus reach them at host.docker.internal; the firewall keeps port 9100 off the home network.
• Needle publishes 127.0.0.1:4535 only. Tailscale Serve takes port 4535 on the tailnet addresses and serves it over HTTPS with a Tailscale certificate, so HTTPS is the only way in. Offline downloads, the iPhone home-screen app and Spotify need that HTTPS address.
• socket-proxy is the only container with the Docker socket. Homepage, Glance and Dozzle read container state through it (why).
• Docker only. Byparr (byparr:8191), Scraparr (scraparr:7100), jellystat-db, socket-proxy (socket-proxy:2375) and gluetun's control server (port 8000) publish nothing. The control server opens exactly one route without credentials, GET /v1/portforward, so Uptime Kuma can alert on a lost forwarded port.

Books module¶

The optional books profile adds Shelfmark for search/requests and Calibre-Web Automated for the library and reader. Both publish loopback-only ports until configured behind Tailscale Serve. Shelfmark reuses Prowlarr, SABnzbd and VPN-bound qBittorrent; only completed copies enter CWA's consuming ingest folder. See books for first-run authentication, storage ownership, backups and deployment checks.

The VPN boundary¶

The boundary is a network namespace, not a setting inside each app. gluetun owns the namespace, brings up the WireGuard tunnel (tun0) and runs a firewall that lets traffic leave only through the tunnel. The one exception is replies to LAN_CIDR and the tailnet (100.64.0.0/10, gluetun's FIREWALL_OUTBOUND_SUBNETS), so the web UIs answer you.

flowchart LR
  subgraph ns["gluetun network namespace"]
    qbit["qBittorrent, bound to tun0"]
    slskd["slskd"]
    fw{"gluetun firewall"}
    tun["tun0 (WireGuard)"]
  end

  qbit & slskd --> fw
  fw -->|"peers and trackers"| tun
  tun --> proton["Proton VPN exit"]
  fw -->|"replies to LAN_CIDR and the tailnet"| ui["Web UI clients"]
  fw -.->|"anything else"| drop["dropped: no route"]

  sab["SABnzbd"] -->|"direct, TLS"| usenet["Usenet provider"]
  others["Everything else"] -->|"direct"| internet["Internet"]

• Fail closed. If the tunnel drops, qBittorrent and slskd have no route out, and IPv6 is off in the namespace, so nothing leaks over it either. qBittorrent is also bound to the tunnel interface itself.
• One forwarded port. Proton forwards a single port. gluetun pushes it into qBittorrent whenever it changes, and vpn-port-sync reconciles it every 15 minutes.
• Outside the boundary: the host, Tailscale, SABnzbd, the arr apps, Prowlarr (so indexer searches go out directly), Jellyfin and Plex. Your own streams stay direct and fast.

Every gluetun setting and its reason, the recovery when Proton stops giving a port, and the leak test are in VPN and ports.

Storage layout¶

Two places hold data. The media disk, mounted at STORAGE_MOUNT, holds downloads, the library and the backup repository. The system disk holds the OS, Docker, the repository and every app's settings, so the stack's state survives the media disk being switched off.

flowchart TD
  subgraph media["Media disk: STORAGE_MOUNT"]
    data["DATA_ROOT, e.g. data/"]
    torrents["torrents/: movies, tv, music, games"]
    usenetdir["usenet/: incomplete, complete"]
    soulseek["soulseek/: downloads, incomplete"]
    lib["media/: movies, tv, music, singles, games"]
    backups["backups/: restic, RESTIC_PASSWORD"]
    data --> torrents & usenetdir & soulseek & lib
  end

  subgraph system["System disk"]
    repo["the repository, e.g. ~/homelab-media-stack"]
    config["CONFIG_ROOT: one folder per app"]
    state["state/, next to CONFIG_ROOT"]
    mirror["/var/backups/arr-stack/restic"]
  end

  torrents -.->|"hardlink on import"| lib
  usenetdir -.->|"move on import"| lib
  soulseek -.->|"import"| lib
  config -->|"nightly restic"| backups
  backups -->|"copy"| mirror

Every container sees the same paths, so they all agree on where a file is:

When Radarr says /data/media/movies, that is the media disk. Lidarr owns media/music; Needle writes only to media/singles, Navidrome's second library, so Lidarr never manages Needle's single songs. Backups are covered in Backups.

Why one filesystem¶

A hardlink is a second name for the same file, and it only works within one filesystem. Because torrents/ and media/ sit under one DATA_ROOT on one disk, Radarr and Sonarr import a finished torrent by hardlinking it into the library: the file appears in both places, uses its disk space once, and qBittorrent keeps seeding it. Split them across two mounts and every import becomes a copy, so every title costs double. Moves are instant for the same reason.

This is why DATA_ROOT must be inside STORAGE_MOUNT, why the health check tests a hardlink across data/ on every run, and why Cleanuparr's orphan cleanup stays off: seeding costs no extra space here. Don't delete files from torrents/ by hand; let Radarr and Sonarr manage them.

Services¶

This is the one list of every service. "Reachable from" follows the firewall and the Tailscale policy: home is the home network, you is your own devices on the tailnet, viewers is the people in group:viewers, and Docker only means no published port. Logins in capitals are keys in .env.

Radarr handles movies and Sonarr TV; they are companions, not alternatives. Lidarr handles music. Readarr (books) and Whisparr are left out on purpose. Which apps you will actually open is covered in the using pages.

Service notes¶

Settings in docker-compose.yml whose reason is not obvious from the file:

Design decisions¶

VPN confinement through network_mode¶

qBittorrent and slskd join gluetun's network namespace instead of each configuring a proxy or a VPN client. An app cannot leak what it cannot route: there is no interface to fall back to, so a dropped tunnel means no traffic rather than traffic from your home IP. A VPN on the host would have routed everything, including Jellyfin streams and Tailscale, through Proton.

The cost is a coupling: when gluetun is restarted or recreated, qBittorrent and slskd keep "running" with a dead network until they are recreated too. Compose's depends_on: {condition: service_healthy, restart: true} covers restarts, and scripts/stack-up and scripts/vpn-port-sync re-attach them whenever their web UIs stop answering.

Usenet outside the VPN¶

The VPN exists because a torrent swarm shows your IP to every peer and you upload to them. Usenet has neither problem: SABnzbd downloads from your provider over TLS and shares nothing. Keeping it outside the tunnel gives it the full line speed and keeps WireGuard's CPU cost off it (on a Raspberry Pi 5, the VPN alone kept the CPU about 90% busy at 40 MB/s). The arr apps' delay profile prefers Usenet and waits before falling back to torrents.

A host firewall hooked into DOCKER-USER¶

Docker publishes a port by rewriting packets before they reach the host's INPUT chain, so a rule in INPUT (and a tool like ufw that writes there) never sees traffic to a published container port. scripts/host-firewall therefore installs the same policy twice: in INPUT for the host's own services and in DOCKER-USER for containers, for IPv4 and IPv6. One script owning the rules is also why ufw and firewalld must be off. Details are in Security: the firewall.

The real mount point gate¶

The media disk can be switched off by hand, and a missing disk must never turn into media quietly filling the system disk. So the stack refuses to run without it at every layer:

• arr-stack.service checks mountpoint -q STORAGE_MOUNT before starting, and scripts/stack-up checks again.
• The service is bound to the mount unit (BindsTo=), so unmounting stops the stack.
• The media bind mounts use create_host_path: false: a missing folder stops the container instead of Docker creating an empty one.
• The empty mount point is made immutable (chattr +i) while unmounted, so nothing can write there in the disk's place.
• The timers that need the disk (arr-backup, arr-health, arr-watch, arr-throttle) skip their run while it is not mounted.

On a machine with one disk, a bind mount onto STORAGE_MOUNT passes the same gate. The power cycle itself is in Storage and boot.

Config outside the repo¶

CONFIG_ROOT sits outside the git repository, so a stray git add -A cannot capture an API key that was never inside it. The repository holds only configuration as code and templates; files rendered with live keys (Scraparr's config, for example) are written to CONFIG_ROOT. Keeping settings on the system disk also means they survive, and can be backed up, while the media disk is off.

1080p and direct play¶

A Raspberry Pi 5 has no hardware video encoder: the Pi 4's H.264 encoder is gone, and only an HEVC decoder remains. Live transcoding is close to impossible, so everything is tuned so that nothing needs it:

• Quality profiles target 1080p. x265 is allowed (scored 0) because the Apple TV and iPhone decode HEVC, 10-bit included, in hardware, so it plays directly. Desktop browsers may not, and then Jellyfin would have to transcode. If HEVC causes trouble, set the x265 score back to -10000 in apps/recyclarr/recyclarr.yml.
• Bazarr fetches sidecar .srt subtitles even when a file has embedded ones: a browser can show embedded subtitles only after Jellyfin reads the whole file to extract them, and burned-in subtitles force a full re-encode.
• Plex counts the tailnet (100.64.0.0/10) as local (configure-plex.py sets it); otherwise it caps tailnet clients' bitrate and forces a transcode.
• Real-time folder watching is off in Jellyfin and Plex so the drive can sleep; the arr apps tell Jellyfin to rescan on every import instead.
• activity-watch sends an alert when a stream is being transcoded anyway.

A typical home upload also limits streaming away from home to about 1080p, so both limits point the same way. With Intel or AMD graphics on an x86-64 machine, compose.gpu.yml and HWACCEL give Jellyfin and Plex hardware transcoding, and browsers and odd formats stop being a problem. The profiles still aim at 1080p unless you change apps/recyclarr/recyclarr.yml (Getting started).

socket-proxy instead of the Docker socket¶

Anything that can reach /var/run/docker.sock controls Docker, which is root on the server. Mounting the socket read-only (:ro) does not change that: it only makes the socket file read-only, not the API behind it. Homepage has no login, so it must never hold the real socket. socket-proxy holds it instead and answers only container list, inspect, stats and logs, plus read-only system information for Dozzle; every write (POST=0) is refused. It publishes no port, so only containers on the arr network can ask it. The health check confirms that a write is refused, that log reads work, and that Homepage and Glance hold no socket.

Repository layout¶

The repository is the stack's source; runtime data never lives in it (Config outside the repo).

• One compose file, not one per app. The services share YAML anchors (*common, *hc, *nnp), which don't cross files, so a split would repeat them in every file. Each module has its own section in the file instead.
• scripts/ stays flat. The units run @REPO@/scripts/<name>, the Python scripts import stack_env from their own folder, and the skills find the repository through scripts/stack-health; names that start with their area keep related scripts together.
• apps/, not config/. config/ is ignored anywhere in the tree and would read as $CONFIG_ROOT, the runtime data.

Idempotent configure scripts¶

Every configure-*.py script reads the current state first and changes only what differs, so a second run prints only = lines. That makes them safe to re-run after an update, a restore or a change to .env, and it turns them into a check: a + on a re-run means something drifted. They talk to each app's API wherever there is one, and edit a config file only where the API cannot do it, with the app stopped while the file is written (Plex's preferences, SABnzbd's list of local networks).