This is the version meant to be followed.
The goal is to start with a Linux host that already has Docker Engine and the Docker Compose plugin, build the stack in a deliberate order, and end with a deployment whose important assumptions can be tested.
The worked example uses Gluetun, ProtonVPN over OpenVPN, qBittorrent, Jackett, FlareSolverr, Sonarr, Radarr, Recyclarr, Cleanuparr, and Tdarr.
Scope: The values below are sanitized. Replace placeholders and host paths for your environment. Do not publish private addresses, credentials, API keys, VPN account data, or real media names.
Internet
|
VPN provider
|
Gluetun
VPN / firewall / tun0
|
+--------------+--------------+
| | |
qBittorrent Jackett FlareSolverr
Docker project network
├── gluetun
├── sonarr -> gluetun:8080 -> qBittorrent
├── radarr -> gluetun:8080 -> qBittorrent
├── recyclarr -> sonarr:8989 / radarr:7878
└── cleanuparr -> sonarr / radarr / gluetun
Separate bridge
└── tdarr
├── /media read-only
└── /temp writable
Only qBittorrent, Jackett, and FlareSolverr share Gluetun’s network namespace. Sonarr, Radarr, Recyclarr, and Cleanuparr stay on the normal Compose network so the control plane remains available when the VPN itself is unhealthy.
Docker’s service-name DNS is what makes that split practical: Sonarr and Radarr can reach services inside the Gluetun namespace through gluetun:<port> rather than a changing container IP.
This guide assumes:
Linux host
Docker Engine
Docker Compose plugin
curl
jq
filesystem with hardlink support
VPN provider supported by Gluetun
Check Docker:
docker version
docker compose version
The example is ProtonVPN-specific where noted. If you use another provider, keep the architecture but use that provider’s current Gluetun settings.
Hardlinks require the completed download and final media library to live on the same filesystem.
Use one canonical container-visible tree:
/srv/media-stack
├── torrents
│ ├── incomplete
│ ├── tv
│ └── movies
└── media
├── tv
└── movies
Keep application state separate:
/srv/arr
├── appdata
├── secrets
├── .env
└── docker-compose.yml
Create it:
sudo mkdir -p \
/srv/arr/appdata/{gluetun,qbittorrent,jackett,sonarr,radarr,recyclarr,cleanuparr,tdarr/{server,configs,logs}} \
/srv/arr/secrets \
/srv/media-stack/torrents/{incomplete,tv,movies} \
/srv/media-stack/media/{tv,movies} \
/srv/media-stack/.tdarr-temp
sudo chown -R "$(id -u):$(id -g)" \
/srv/arr \
/srv/media-stack
chmod 700 /srv/arr/secrets
Verify the data trees are on the same filesystem:
stat -c 'device=%d path=%n' \
/srv/media-stack/torrents \
/srv/media-stack/media
The device IDs must match.
If they do not, fix the storage design before configuring Sonarr or Radarr.
Create /srv/arr/.env:
cd /srv/arr
cat > .env <<'EOF'
ARR_BIND_IP=127.0.0.1
PUID=1000
PGID=1000
TZ=Etc/UTC
APPDATA_ROOT=/srv/arr/appdata
DATA_ROOT=/srv/media-stack
VPN_COUNTRY=United States
EOF
chmod 600 .env
Set the UID/GID to the account that should own the files:
id -u
id -g
ARR_BIND_IP=127.0.0.1 is deliberate. If direct LAN access is required, use the host’s trusted management address instead of 0.0.0.0.
For ProtonVPN port forwarding over OpenVPN, Gluetun’s current provider documentation requires the OpenVPN username to end in +pmp.
cd /srv/arr
read -r -p 'Proton OpenVPN username (include +pmp): ' SECRET
printf '%s' "$SECRET" > secrets/openvpn_user
unset SECRET
read -r -s -p 'Proton OpenVPN password: ' SECRET
echo
printf '%s' "$SECRET" > secrets/openvpn_password
unset SECRET
read -r -p 'qBittorrent WebUI username: ' SECRET
printf '%s' "$SECRET" > secrets/qbit_username
unset SECRET
read -r -s -p 'qBittorrent WebUI password: ' SECRET
echo
printf '%s' "$SECRET" > secrets/qbit_password
unset SECRET
chmod 600 secrets/*
grep -q '+pmp$' secrets/openvpn_user \
&& echo 'PASS: Proton username has +pmp' \
|| echo 'FAIL: Proton username is missing +pmp'
If you use a different VPN provider, do not copy the +pmp requirement; use that provider’s current Gluetun instructions instead.
Compose file-backed secrets keep credentials out of the YAML, but the files are still plaintext on the host. Protect and back them up accordingly.
The invariant we want is:
VPN provider forwarded port
==
qBittorrent listen port
A Docker 6881:6881 mapping does not create a VPN-provider port forward.
Gluetun can run commands when provider-side port forwarding comes up or goes down. The following adapter updates qBittorrent through its authenticated Web API.
This implementation assumes qBittorrent 5.2.0 or newer.
Create /srv/arr/appdata/gluetun/qbit-port.sh:
cat > /srv/arr/appdata/gluetun/qbit-port.sh <<'EOF'
#!/bin/sh
set -u
ACTION="${1:-}"
PORT="${2:-}"
VPN_IFACE="${3:-tun0}"
QBIT_URL="http://127.0.0.1:8080"
USER_FILE="/run/secrets/qbit_username"
PASS_FILE="/run/secrets/qbit_password"
log() {
printf '%s\n' "$*"
}
load_auth() {
if [ ! -r "$USER_FILE" ] || [ ! -r "$PASS_FILE" ]; then
log "ERROR: qBittorrent credential secrets unavailable"
return 1
fi
USER="$(cat "$USER_FILE")"
PASS="$(cat "$PASS_FILE")"
AUTH="$(
printf '%s:%s' "$USER" "$PASS" |
base64 |
tr -d '\n'
)"
unset USER PASS
}
wait_for_webui() {
attempt=1
while [ "$attempt" -le 60 ]; do
RESPONSE="$(
wget -S -O /dev/null \
--header="Authorization: Basic $AUTH" \
--header="Referer: $QBIT_URL" \
"$QBIT_URL/api/v2/app/version" \
2>&1 || true
)"
if printf '%s\n' "$RESPONSE" |
grep -qE 'HTTP/1\.[01] 200'; then
return 0
fi
sleep 1
attempt=$((attempt + 1))
done
return 1
}
set_preferences() {
JSON="$1"
RESPONSE="$(
wget -S -O /dev/null \
--header="Authorization: Basic $AUTH" \
--header="Referer: $QBIT_URL" \
--post-data="json=${JSON}" \
"$QBIT_URL/api/v2/app/setPreferences" \
2>&1 || true
)"
if printf '%s\n' "$RESPONSE" |
grep -qE 'HTTP/1\.[01] 200'; then
return 0
fi
log "ERROR: qBittorrent setPreferences request failed"
printf '%s\n' "$RESPONSE" |
grep -E 'HTTP/|ERROR|Forbidden|Unauthorized' ||
true
return 1
}
get_preferences() {
wget -qO- \
--header="Authorization: Basic $AUTH" \
--header="Referer: $QBIT_URL" \
"$QBIT_URL/api/v2/app/preferences"
}
set_vpn_port() {
WANTED="$1"
IFACE="$2"
case "$WANTED" in
''|*[!0-9]*)
log "ERROR: invalid port: $WANTED"
return 1
;;
esac
if [ "$WANTED" -lt 1 ] || [ "$WANTED" -gt 65535 ]; then
log "ERROR: port out of range: $WANTED"
return 1
fi
load_auth || return 1
if ! wait_for_webui; then
log "ERROR: qBittorrent WebUI did not become available"
return 1
fi
JSON="{\"listen_port\":${WANTED},\"current_network_interface\":\"${IFACE}\",\"random_port\":false,\"upnp\":false}"
log "Setting qBittorrent listen port to $WANTED on $IFACE"
set_preferences "$JSON" || return 1
PREFS="$(get_preferences 2>/dev/null || true)"
ACTUAL="$(
printf '%s\n' "$PREFS" |
sed -n 's/.*"listen_port":\([0-9][0-9]*\).*/\1/p'
)"
if [ "$ACTUAL" != "$WANTED" ]; then
log "ERROR: requested=$WANTED actual=${ACTUAL:-unknown}"
return 1
fi
log "qBittorrent listen port verified: $ACTUAL"
}
reset_vpn_port() {
load_auth || return 1
if ! wait_for_webui; then
log "qBittorrent WebUI unavailable during teardown"
return 0
fi
JSON='{"listen_port":0,"current_network_interface":"lo","random_port":false,"upnp":false}'
log "Resetting qBittorrent peer listener"
set_preferences "$JSON" ||
log "WARNING: qBittorrent listener reset failed"
return 0
}
case "$ACTION" in
up|set)
[ -n "$PORT" ] || {
log "ERROR: usage: $0 {up|set} PORT [VPN_INTERFACE]"
exit 2
}
set_vpn_port "$PORT" "$VPN_IFACE"
;;
down)
reset_vpn_port
;;
*)
log "ERROR: usage: $0 {up|set} PORT [VPN_INTERFACE] | down"
exit 2
;;
esac
EOF
chmod 755 /srv/arr/appdata/gluetun/qbit-port.sh
sh -n /srv/arr/appdata/gluetun/qbit-port.sh &&
echo 'PASS: qbit-port.sh syntax'
Do not enable qBittorrent’s localhost-authentication bypass. qBittorrent, Jackett, and FlareSolverr share Gluetun’s namespace and should be treated as mutually adjacent services.
Create /srv/arr/docker-compose.yml:
services:
gluetun:
image: qmcgaw/gluetun
restart: unless-stopped
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
VPN_SERVICE_PROVIDER: protonvpn
VPN_TYPE: openvpn
SERVER_COUNTRIES: "${VPN_COUNTRY:-United States}"
OPENVPN_USER_SECRETFILE: /run/secrets/openvpn_user
OPENVPN_PASSWORD_SECRETFILE: /run/secrets/openvpn_password
VPN_PORT_FORWARDING: "on"
VPN_PORT_FORWARDING_UP_COMMAND: >-
/bin/sh -c '/gluetun/qbit-port.sh up "{{PORT}}" tun0'
VPN_PORT_FORWARDING_DOWN_COMMAND: >-
/bin/sh -c '/gluetun/qbit-port.sh down'
FIREWALL: "on"
FIREWALL_INPUT_PORTS: 8080,9117
VPN_INTERFACE: tun0
IPV6: "off"
secrets:
- openvpn_user
- openvpn_password
- qbit_username
- qbit_password
security_opt:
- no-new-privileges:true
ports:
- "${ARR_BIND_IP:-127.0.0.1}:8080:8080"
- "${ARR_BIND_IP:-127.0.0.1}:9117:9117"
volumes:
- "${APPDATA_ROOT}/gluetun:/gluetun"
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
restart: unless-stopped
network_mode: "service:gluetun"
depends_on:
gluetun:
condition: service_healthy
environment:
PUID: "${PUID:-1000}"
PGID: "${PGID:-1000}"
TZ: "${TZ:-Etc/UTC}"
WEBUI_PORT: "8080"
volumes:
- "${APPDATA_ROOT}/qbittorrent:/config"
- "${DATA_ROOT}:/data"
jackett:
image: lscr.io/linuxserver/jackett:latest
restart: unless-stopped
network_mode: "service:gluetun"
depends_on:
gluetun:
condition: service_healthy
environment:
PUID: "${PUID:-1000}"
PGID: "${PGID:-1000}"
TZ: "${TZ:-Etc/UTC}"
AUTO_UPDATE: "true"
RUN_OPTS: ""
volumes:
- "${APPDATA_ROOT}/jackett:/config"
flaresolverr:
image: ghcr.io/flaresolverr/flaresolverr:latest
restart: unless-stopped
network_mode: "service:gluetun"
depends_on:
gluetun:
condition: service_healthy
environment:
LOG_LEVEL: info
LOG_HTML: "false"
CAPTCHA_SOLVER: none
TZ: "${TZ:-Etc/UTC}"
sonarr:
image: lscr.io/linuxserver/sonarr:latest
restart: unless-stopped
environment:
PUID: "${PUID:-1000}"
PGID: "${PGID:-1000}"
UMASK: "002"
TZ: "${TZ:-Etc/UTC}"
ports:
- "${ARR_BIND_IP:-127.0.0.1}:8989:8989"
volumes:
- "${APPDATA_ROOT}/sonarr:/config"
- "${DATA_ROOT}:/data"
radarr:
image: lscr.io/linuxserver/radarr:latest
restart: unless-stopped
environment:
PUID: "${PUID:-1000}"
PGID: "${PGID:-1000}"
UMASK: "002"
TZ: "${TZ:-Etc/UTC}"
ports:
- "${ARR_BIND_IP:-127.0.0.1}:7878:7878"
volumes:
- "${APPDATA_ROOT}/radarr:/config"
- "${DATA_ROOT}:/data"
recyclarr:
image: ghcr.io/recyclarr/recyclarr:8
restart: unless-stopped
user: "${PUID:-1000}:${PGID:-1000}"
environment:
TZ: "${TZ:-Etc/UTC}"
CRON_SCHEDULE: "@daily"
volumes:
- "${APPDATA_ROOT}/recyclarr:/config"
read_only: true
tmpfs:
- /tmp
security_opt:
- no-new-privileges:true
cleanuparr:
image: ghcr.io/cleanuparr/cleanuparr:latest
restart: unless-stopped
environment:
PORT: "11011"
BIND_ADDRESS: "0.0.0.0"
BASE_PATH: ""
PUID: "${PUID:-1000}"
PGID: "${PGID:-1000}"
UMASK: "022"
TZ: "${TZ:-Etc/UTC}"
ports:
- "${ARR_BIND_IP:-127.0.0.1}:11011:11011"
volumes:
- "${APPDATA_ROOT}/cleanuparr:/config"
security_opt:
- no-new-privileges:true
healthcheck:
test:
- CMD
- curl
- -f
- http://127.0.0.1:11011/health
interval: 30s
timeout: 10s
start_period: 30s
retries: 3
tdarr:
image: ghcr.io/haveagitgat/tdarr:2.81.01
restart: unless-stopped
network_mode: bridge
ports:
- "${ARR_BIND_IP:-127.0.0.1}:8265:8265"
env_file:
- ./secrets/tdarr-auth.env
environment:
TZ: "${TZ:-Etc/UTC}"
PUID: "${PUID:-1000}"
PGID: "${PGID:-1000}"
UMASK_SET: "002"
serverIP: "0.0.0.0"
serverPort: "8266"
webUIPort: "8265"
internalNode: "true"
inContainer: "true"
serverURL: "http://127.0.0.1:8266"
nodeName: "arr-health"
ffmpegVersion: "7"
auth: "true"
openBrowser: "false"
maxLogSizeMB: "10"
transcodegpuWorkers: "0"
transcodecpuWorkers: "0"
healthcheckgpuWorkers: "0"
healthcheckcpuWorkers: "1"
volumes:
- "${APPDATA_ROOT}/tdarr/server:/app/server"
- "${APPDATA_ROOT}/tdarr/configs:/app/configs"
- "${APPDATA_ROOT}/tdarr/logs:/app/logs"
- "${DATA_ROOT}/media:/media:ro"
- "${DATA_ROOT}/.tdarr-temp:/temp"
security_opt:
- no-new-privileges:true
secrets:
openvpn_user:
file: ./secrets/openvpn_user
openvpn_password:
file: ./secrets/openvpn_password
qbit_username:
file: ./secrets/qbit_username
qbit_password:
file: ./secrets/qbit_password
Do not add networks: to a service using network_mode: "service:gluetun"; those are mutually exclusive Compose networking models.
The baseline also leaves Gluetun’s health server at its loopback-only default (127.0.0.1:9999). If another container genuinely needs to query that endpoint, explicitly set HEALTH_SERVER_ADDRESS=0.0.0.0:9999 and add 9999 to FIREWALL_INPUT_PORTS; otherwise do not open an unused internal port.
Several images above use moving latest tags because that matches their normal upstream release channel. For a controlled deployment, record the versions or digests you actually validate and update them intentionally rather than blindly auto-updating. The Tdarr tag shown here is the version this health-check workflow was validated against, not a claim that it is the newest release.
Tdarr UI authentication and Node authentication are separate pieces.
Generate a private key for the internal Node:
cd /srv/arr
TDARR_KEY="tapi_$(openssl rand -hex 24)"
umask 077
cat > secrets/tdarr-auth.env <<EOF
seededApiKey=$TDARR_KEY
apiKey=$TDARR_KEY
EOF
unset TDARR_KEY
Only host port 8265 is published.
Port 8266 is intentionally internal:
Tdarr Web UI host -> 8265
Tdarr Node API 127.0.0.1:8266 inside container
cd /srv/arr
sh -n appdata/gluetun/qbit-port.sh &&
echo 'PASS: qBit hook'
docker compose config -q &&
echo 'PASS: Compose'
docker compose config --services
Expected service set:
gluetun
qbittorrent
jackett
flaresolverr
sonarr
radarr
recyclarr
cleanuparr
tdarr
Make sure there is no fixed peer-port mapping:
grep -n '6881' docker-compose.yml ||
echo 'PASS: no fixed 6881 mapping'
docker compose up -d gluetun
GLUE="$(docker compose ps -q gluetun)"
Check health:
docker inspect "$GLUE" \
--format 'status={{.State.Status}} health={{if .State.Health}}{{.State.Health.Status}}{{else}}n/a{{end}}'
Check VPN IPv4:
docker exec "$GLUE" \
wget -qO- https://api.ipify.org
echo
That uses a third-party IP-echo service only for diagnostics.
If IPv6 is intentionally disabled:
docker exec "$GLUE" sh -c '
timeout 5 wget -6 -qO- https://api64.ipify.org &&
echo "FAIL: unexpected IPv6 Internet path" ||
echo "PASS: no usable IPv6 Internet path"
'
Read the provider-forwarded port:
docker exec "$GLUE" \
cat /tmp/gluetun/forwarded_port
Current Gluetun documentation still supports /tmp/gluetun/forwarded_port, but marks that status file for deprecation in the v4.0.0 release. The actual qBittorrent synchronization in this guide uses Gluetun’s up/down hooks; the file is used here only for bootstrap and verification.
Because qBittorrent has not been started yet, the first Gluetun-only boot may also log that the qBittorrent hook could not reach the WebUI. Step 9 starts qBittorrent and replays the hook manually after authentication is configured.
Do not continue until the VPN path and forwarding state are correct.
docker compose up -d qbittorrent
The Web UI is exposed by Gluetun:
http://<ARR_BIND_IP>:8080
For a fresh installation, inspect qBittorrent logs for the temporary WebUI credential if needed:
docker compose logs \
--since 5m \
--no-color \
qbittorrent
Sign in and set the username/password to match:
secrets/qbit_username
secrets/qbit_password
Keep authentication enabled and do not enable localhost bypass.
Then run the hook once manually:
PF="$(
docker exec "$GLUE" \
cat /tmp/gluetun/forwarded_port
)"
docker exec "$GLUE" \
/gluetun/qbit-port.sh up "$PF" tun0
Resolve qBittorrent:
QBIT="$(docker compose ps -q qbittorrent)"
Check live TCP/UDP listeners:
docker exec "$QBIT" sh -c '
netstat -lntup 2>/dev/null ||
ss -lntup 2>/dev/null
' |
grep ":${PF}"
Then query preferences through the authenticated API:
QBIT_BIND="$(
sed -n 's/^ARR_BIND_IP=//p' .env |
head -n 1
)"
QBIT_URL="http://${QBIT_BIND:-127.0.0.1}:8080"
QUSER="$(cat secrets/qbit_username)"
QPASS="$(cat secrets/qbit_password)"
COOKIE="$(mktemp)"
trap 'rm -f "$COOKIE"' EXIT
curl -fsS \
-c "$COOKIE" \
-H "Referer: $QBIT_URL" \
--data-urlencode "username=$QUSER" \
--data-urlencode "password=$QPASS" \
"$QBIT_URL/api/v2/auth/login" \
>/dev/null
unset QUSER QPASS
curl -fsS \
-b "$COOKIE" \
-H "Referer: $QBIT_URL" \
"$QBIT_URL/api/v2/app/preferences" |
jq '{
listen_port,
current_network_interface,
random_port,
upnp
}'
Required invariants:
listen_port == provider forwarded port
current_network_interface == tun0
random_port == false
upnp == false
The Web UI working does not prove these things.
Use:
qBittorrent default:
/data/torrents
incomplete:
/data/torrents/incomplete
Sonarr category:
/data/torrents/tv
Radarr category:
/data/torrents/movies
Sonarr root:
/data/media/tv
Radarr root:
/data/media/movies
qBittorrent, Sonarr, and Radarr all mount the same host filesystem as /data.
That is the important part.
docker compose up -d sonarr radarr
Open:
Sonarr http://<ARR_BIND_IP>:8989
Radarr http://<ARR_BIND_IP>:7878
Enable authentication before broadening access beyond loopback.
Configure qBittorrent as:
URL: http://gluetun:8080
Use the matching qBittorrent category for each application.
Do not use the host IP for container-to-container traffic when Docker DNS already supplies the intended path.
docker compose up -d jackett flaresolverr
Jackett:
http://<ARR_BIND_IP>:9117
FlareSolverr has no host-published port.
Because Jackett and FlareSolverr share Gluetun’s namespace, Jackett can use:
http://127.0.0.1:8191
for compatible FlareSolverr integration.
Sonarr/Radarr reach Jackett through:
http://gluetun:9117
Test every indexer independently.
for svc in \
gluetun \
qbittorrent \
jackett \
flaresolverr \
sonarr \
radarr \
recyclarr \
cleanuparr \
tdarr
do
cid="$(docker compose ps -q "$svc")"
printf '%-14s ' "$svc"
docker inspect "$cid" \
--format 'mode={{.HostConfig.NetworkMode}} {{range $n,$v := .NetworkSettings.Networks}}net={{$n}} ip={{$v.IPAddress}} {{end}}'
done
Expected conceptually:
gluetun project network
sonarr project network
radarr project network
recyclarr project network
cleanuparr project network
qbittorrent container:<gluetun-id>
jackett container:<gluetun-id>
flaresolverr container:<gluetun-id>
tdarr bridge
Check control-plane reachability:
for svc in sonarr radarr; do
echo "=== $svc ==="
docker exec "$(docker compose ps -q "$svc")" sh -c '
curl -sS -o /dev/null \
-w "qbit=%{http_code}\n" \
--max-time 5 \
http://gluetun:8080/
curl -sS -o /dev/null \
-w "jackett=%{http_code}\n" \
--max-time 5 \
http://gluetun:9117/
'
done
An expected redirect or authentication error can still prove the network path is alive. Do not require HTTP 200 when an application intentionally answers with 401, 403, or 3xx.
First:
stat -c 'device=%d %n' \
/srv/media-stack/torrents \
/srv/media-stack/media
Then complete one known-good download and let Sonarr or Radarr import it.
Compare the download file and library file:
stat -c \
'device=%d inode=%i links=%h size=%s path=%n' \
/srv/media-stack/torrents/<downloaded-file> \
/srv/media-stack/media/<imported-file>
A real hardlink should have:
same device
same inode
same size
link count >= 2
Do not call the storage design finished until this has been proven once.
Only do this after ordinary Sonarr/Radarr imports work.
docker compose up -d recyclarr
Create its initial configuration if needed:
docker compose run --rm \
recyclarr \
config create
Use Docker service names in the config:
sonarr:
main:
base_url: http://sonarr:8989
api_key: !secret sonarr
radarr:
main:
base_url: http://radarr:7878
api_key: !secret radarr
Use Recyclarr’s supported secret mechanism for API keys.
Preview before applying:
docker compose exec \
recyclarr \
recyclarr sync --preview --log info
Then verify both that the profiles exist and that the intended movies/series are actually assigned to them.
docker compose up -d cleanuparr
Check health:
docker inspect "$(docker compose ps -q cleanuparr)" \
--format '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{end}}'
Use these internal targets:
Sonarr:
http://sonarr:8989
Radarr:
http://radarr:7878
qBittorrent:
http://gluetun:8080
Enable automation conservatively:
configure
verify connections
observe
dry-run where available
one narrow live rule
review evidence
expand
Cleanuparr is a queue/download management layer, not an antivirus scanner.
A first-pass blocked list can include:
*.exe
*.sh
*.bat
*.cmd
*.com
*.ps1
*.vbs
*.scr
*.msi
*.lnk
This is filename policy, not malware detection.
After configuring it, query qBittorrent’s preferences and verify the setting is actually present.
More importantly, test the same ingestion path production uses. A torrent manually injected into qBittorrent may not exercise the same workflow as one originated by Sonarr or Radarr.
Do not use real malware.
Use synthetic torrent metadata that declares an intentionally blocked filename without distributing malicious payload content.
The full test path should be:
Sonarr/Radarr
|
v
candidate accepted
|
v
qBittorrent receives metadata
|
v
blocked file becomes unwanted
|
v
Arr cannot import
|
v
Cleanuparr sees queue condition
|
+--> strike/remove/block
`--> replacement if configured
A canary rejected by a quality profile or minimum-size rule is still useful evidence, but it proves only that upstream gate.
docker compose up -d tdarr
Open:
http://<ARR_BIND_IP>:8265
Create the initial UI account.
Check host publication:
docker port "$(docker compose ps -q tdarr)"
You should see 8265.
You should not see 8266.
Verify mounts:
docker inspect "$(docker compose ps -q tdarr)" \
--format '{{range .Mounts}}{{println .Destination "RW=" .RW}}{{end}}'
Expected:
/media RW= false
/temp RW= true
This deployment is health-check only:
transcodegpuWorkers=0
transcodecpuWorkers=0
healthcheckgpuWorkers=0
healthcheckcpuWorkers=1
Do not pass a GPU into Tdarr unless you intentionally expand its role.
A successful media health check is not a malware verdict and is not a quarantine gate.
For every Web UI, answer:
Who can reach it?
How do they authenticate?
Does it need host publication at all?
The Compose example defaults to loopback.
If moving to a management LAN:
ARR_BIND_IP;Check listeners:
ss -lnt |
grep -E \
':(8080|9117|8989|7878|11011|8265|8266)[[:space:]]'
There should be no host listener for Tdarr 8266.
FlareSolverr and Recyclarr should have no host-published ports.
Do not expose management UIs to the public Internet simply because torrent peer traffic is intentionally reachable through the VPN provider.
docker compose up -d
docker compose ps -a
docker compose config -q
Then check the real invariants.
Gluetun healthy
only qBit / Jackett / FlareSolverr share Gluetun
VPN IPv4 works
unexpected IPv6 path absent if disabled
forwarded port exists
qBit API reachable
listen port == forwarded port
interface == tun0
random port disabled
UPnP disabled
TCP listener present
UDP listener present
Sonarr / Radarr / Recyclarr / Cleanuparr on project network
Sonarr/Radarr reach qBit at gluetun:8080
Sonarr/Radarr reach Jackett at gluetun:9117
download and library trees same filesystem
one real hardlink proven
UIs bound only where intended
auth enabled
internal-only ports not published
auth enabled
/media read-only
/temp writable
8266 not published
no GPU
transcode workers zero
health worker enabled
A minimal local checker can validate service state, topology, the forwarded port, and the Tdarr read-only boundary.
Create /srv/arr/health-lite.sh:
cat > /srv/arr/health-lite.sh <<'EOF'
#!/usr/bin/env bash
set -u
cd "$(dirname "$0")" || exit 1
FAILURES=0
pass() {
printf 'PASS: %s\n' "$*"
}
fail() {
printf 'FAIL: %s\n' "$*" >&2
FAILURES=$((FAILURES + 1))
}
echo '=== COMPOSE ==='
docker compose config -q \
&& pass 'Compose valid' \
|| fail 'Compose invalid'
for svc in \
gluetun qbittorrent jackett flaresolverr \
sonarr radarr recyclarr cleanuparr tdarr
do
cid="$(docker compose ps -q "$svc" 2>/dev/null || true)"
[ -n "$cid" ] || {
fail "$svc missing"
continue
}
state="$(
docker inspect "$cid" \
--format '{{.State.Status}}' \
2>/dev/null || true
)"
[ "$state" = running ] \
&& pass "$svc running" \
|| fail "$svc state=$state"
done
echo
echo '=== GLUETUN ==='
GLUE="$(docker compose ps -q gluetun 2>/dev/null || true)"
if [ -n "$GLUE" ]; then
health="$(
docker inspect "$GLUE" \
--format '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}'
)"
[ "$health" = healthy ] \
&& pass 'Gluetun healthy' \
|| fail "Gluetun health=$health"
PF="$(
docker exec "$GLUE" \
cat /tmp/gluetun/forwarded_port \
2>/dev/null || true
)"
case "$PF" in
''|*[!0-9]*)
fail 'forwarded port unavailable'
;;
*)
pass 'forwarded port present'
;;
esac
fi
echo
echo '=== VPN-BOUND SERVICES ==='
for svc in qbittorrent jackett flaresolverr; do
cid="$(docker compose ps -q "$svc" 2>/dev/null || true)"
mode="$(
docker inspect "$cid" \
--format '{{.HostConfig.NetworkMode}}' \
2>/dev/null || true
)"
case "$mode" in
container:*)
pass "$svc shares container namespace"
;;
*)
fail "$svc network mode=$mode"
;;
esac
done
echo
echo '=== TDARR ==='
TDARR="$(docker compose ps -q tdarr 2>/dev/null || true)"
if [ -n "$TDARR" ]; then
MEDIA_RW="$(
docker inspect "$TDARR" \
--format '{{range .Mounts}}{{if eq .Destination "/media"}}{{.RW}}{{end}}{{end}}'
)"
[ "$MEDIA_RW" = false ] \
&& pass 'Tdarr /media read-only' \
|| fail "Tdarr /media RW=$MEDIA_RW"
if docker port "$TDARR" 8266/tcp 2>/dev/null |
grep -q .; then
fail 'Tdarr 8266 is host-published'
else
pass 'Tdarr 8266 not host-published'
fi
fi
echo
echo '=== SUMMARY ==='
printf 'Failures: %d\n' "$FAILURES"
if [ "$FAILURES" -eq 0 ]; then
echo 'ARR STACK HEALTH: PASS'
exit 0
else
echo 'ARR STACK HEALTH: FAIL'
exit 1
fi
EOF
chmod 755 /srv/arr/health-lite.sh
Run:
cd /srv/arr
./health-lite.sh
A fuller watchdog can add authenticated API checks, exact bind validation, capacity thresholds, qBittorrent preference comparison, Recyclarr targets, Cleanuparr policy, and retained failure evidence.
Useful tests:
VPN outage
management binding drift
forwarded-port mismatch detection
Tdarr read-only mount validation
application authentication
Do not deliberately expose a random torrent port to test monitoring.
Do not modify real library content merely to prove the Tdarr mount is read-only.
Test the narrowest safe condition that proves the invariant.
Polling every minute is fine.
Alerting every minute during the same outage is not.
Use:
previous current action
-------- ------- ------
UNKNOWN/PASS PASS silence
UNKNOWN/PASS FAIL DOWN
FAIL FAIL silence
FAIL PASS RECOVERED
PASS PASS silence
Start with:
detect
record
notify
—not automatic restart.
A local watchdog cannot detect the disappearance of its own host, so add an external dead-man check if host-level liveness matters.
Validate:
cd /srv/arr
docker compose config -q
Status:
docker compose ps -a
Logs:
docker compose logs \
--since 15m \
--no-color \
<service>
Recreate an ordinary service:
docker compose up -d \
--no-deps \
--force-recreate \
<service>
Do not recreate Gluetun by itself. qBittorrent, Jackett, and FlareSolverr share its network namespace. If Gluetun itself must be recreated, recreate that dependency group together:
docker compose up -d \
--force-recreate \
gluetun qbittorrent jackett flaresolverr
Current forwarded port:
GLUE="$(docker compose ps -q gluetun)"
docker exec "$GLUE" \
cat /tmp/gluetun/forwarded_port
Topology:
for svc in \
gluetun qbittorrent jackett flaresolverr \
sonarr radarr recyclarr cleanuparr tdarr
do
cid="$(docker compose ps -q "$svc")"
printf '%-14s ' "$svc"
docker inspect "$cid" \
--format 'mode={{.HostConfig.NetworkMode}} {{range $n,$v := .NetworkSettings.Networks}}net={{$n}} {{end}}'
done
Health:
./health-lite.sh
A defensible claim is:
The stack is using the expected VPN and container-network topology, the torrent listener matches the provider forwarding state, management exposure matches the configured boundary, Arr imports can hardlink on the shared filesystem, and the configured post-import structural media check has no reported finding.
That does not mean:
the download is guaranteed malware-free
the media file is safe under every parser
the VPN provider is trustworthy
the container images are bug-free
Tdarr is a quarantine gate
Each layer answers a narrower question.
storage
->
VPN boundary
->
qBittorrent transport
->
Sonarr / Radarr
->
Jackett / FlareSolverr
->
one proven hardlink import
->
Recyclarr
->
Cleanuparr
->
filename policy + inert canary
->
read-only Tdarr
->
health invariants
->
stateful alerting
That order keeps troubleshooting local: each layer is added only after the layer below it has a known-good state.
Those posts explain the design decisions and failure modes. This guide is the implementation.
Up.
For a multi-service media pipeline, the useful question is whether the relationships between the services are still correct:
I turned those assumptions into executable health invariants and designed the monitoring system around state transitions rather than repeated alerts.
Docker can tell you that a container is running. That does not prove the application is correctly wired into the rest of the system.
For example, all of the following can happen while every container remains Up:
qBittorrent listen port no longer matches VPN forwarded port
Sonarr points at an obsolete hostname
Jackett is reachable only through a stale network path
management UI is accidentally wildcard-published
Tdarr server API is exposed to the host unnecessarily
cleanup service points at an old endpoint
The health check therefore validates invariants, not only process state.
The stack-wide health script checks several categories.
Compose parses
expected services exist
services are running
restart policy matches policy
containers belong to the intended Compose project
Gluetun healthy
only intended services share Gluetun namespace
input firewall contains only required ports
VPN IPv4 works
unexpected IPv6 Internet path is absent
provider-forwarded port exists
qBittorrent API reachable
listen port == provider forwarded port
network interface == VPN tunnel
random port disabled
UPnP disabled
TCP listener present
UDP listener present
no stale default listener
Sonarr/Radarr on normal Docker network
Recyclarr/Cleanuparr on normal Docker network
Sonarr/Radarr can reach qBit via Gluetun service name
Sonarr/Radarr can reach Jackett via Gluetun service name
expected UIs bound only to trusted management path
no wildcard publication
no host publication for internal-only services
Cleanuparr healthy
local-address authentication bypass disabled
Recyclarr read-only root filesystem
Recyclarr expected schedule and targets
Tdarr authentication enabled
Tdarr server/node API keys agree
Tdarr media mount read-only
Tdarr internal server listening but not host-published
Tdarr has no GPU device
root filesystem below threshold
media/download filesystem below threshold
The script exits non-zero when a hard invariant fails.
A Compose file can accidentally regress from:
<trusted-management-address>:<port>
back to:
0.0.0.0:<port>
without affecting whether the application itself starts.
That is precisely the sort of configuration drift a health script should detect.
The same applies to ports that should not exist on the host at all. If an internal application server is only used by a process in the same container, its host publication should be treated as a failed invariant rather than an innocent extra mapping.
One management service was initially loopback-only. Before moving it to the trusted management network, the account state was checked and a real login was verified.
The sequence was:
verify account initialized
verify local-address auth bypass disabled
verify password login works
only then change host binding
verify again from a fresh browser session
A second service required a slightly more involved bootstrap because enabling Web UI authentication also meant its internal node needed an API key.
The safe sequence was:
generate private API key
keep UI loopback-only
enable authentication
configure internal node with matching key
verify node reconnects
create/login to UI account
confirm auth errors stop
only then expose UI to trusted management network
This order prevents “enable auth and hope” deployments where an internal worker silently stops functioning after the UI is secured.
Running a health script every minute is easy. Sending a notification every minute during an outage is not useful.
The local watchdog should remember the previous state:
previous current action
-------- ------- ------
UNKNOWN/PASS PASS nothing
UNKNOWN/PASS FAIL send one DOWN
FAIL FAIL suppress duplicate
FAIL PASS send one RECOVERED
PASS PASS nothing
The important property is that notification behavior depends on the transition, not simply on the current exit code.
The planned local architecture is:
systemd timer
|
v
watchdog service
|
v
stack health script
|
+--> save latest output
+--> compare state with previous run
+--> notify on transition
`--> preserve last failure for diagnosis
Persistent state can live somewhere such as:
/var/lib/<watchdog-name>/
├── state
├── last-health.txt
└── last-failure.txt
The notifier should be a small adapter so the state machine does not care whether delivery is through Home Assistant, ntfy, Gotify, Pushover, email, or another service.
Automatic remediation is attractive, but it can erase the evidence needed to understand a failure.
For the initial deployment, the watchdog should:
detect
record
notify
—not restart.
After real incidents have been observed, narrow remediations can be added for failure modes that are well understood and safe to automate.
For example, a stale application process may eventually justify a restart. A VPN/authentication/route failure may not.
There is one unavoidable blind spot:
host/LXC down
|
+--> timer cannot run
+--> health script cannot run
`--> local notifier cannot run
That requires an external dead-man monitor on a different failure domain.
The external check can be much simpler than the local one. It does not need to understand every application. It only needs to answer something like:
Is the host reachable?
Is one trusted management endpoint alive?
Is a heartbeat still fresh?
The local watchdog provides depth. The external monitor provides liveness from the outside.
A complete monitoring strategy can use three layers:
Layer 1: native application notifications
- best event context
- import/queue/cleanup-specific events
Layer 2: local stateful watchdog
- deep cross-service invariants
- DOWN / RECOVERED transitions
Layer 3: external dead-man monitor
- host/container disappearance
- independent failure domain
No single layer has to solve every problem.
A useful watchdog should retain the full health output rather than reducing everything to “red” or “green.”
A failure notification can be short:
Media stack DOWN: 3 failed invariants
while the local evidence contains the actual details:
VPN healthy
forwarded port present
qBit port mismatch
Sonarr reachable
Radarr reachable
That immediately narrows the incident from “the stack is broken” to “torrent transport state drifted.”
The point of all of this is not maximal complexity. It is to make the system answer, quickly and unambiguously:
What failed?
What is still safe?
What is still available?
Did the failure recover?
Do I need to intervene?
A good Docker media stack is not just automated. It is observable, bounded, and recoverable without guessing.
I wanted each service to have one clear job, the storage layout to support hardlinks, and the VPN failure domain to be as small as possible.
Once that was in place, the next question was less about architecture and more about trust.
Everything entering the download side of the stack comes from systems I do not control.
Torrent metadata is untrusted input.
The files described by that metadata are untrusted input.
A successful download only proves that the download client transferred what it was told to transfer.
It does not prove that I wanted the payload.
That changed the question from:
How do I make the stack download reliably?
to:
How many opportunities do I have to reject something before I treat it like normal media?
I did not want one oversized security component pretending to answer that question.
I wanted several narrow controls whose behavior I could test independently.
The resulting path looks like this:
network containment
|
v
filename policy
|
v
queue enforcement
|
v
authoritative import
|
v
read-only structural validation
|
v
media consumption
None of those layers proves that a file is malware-free.
That distinction matters.
The goal is to reduce exposure, catch specific classes of unwanted content early, and make every decision point visible enough to test.
The first control is the one established in Part 1.
qBittorrent shares Gluetun’s network namespace.
qBittorrent
|
v
Gluetun
|
v
VPN
If the VPN path disappears, the torrent client should lose its Internet path instead of quietly falling back to the host’s ordinary WAN connection.
That answers one specific question:
Where is this traffic allowed to go?
It does not answer:
What is inside this torrent?
A VPN kill switch is containment.
It is not content inspection.
Keeping those claims separate makes the rest of the stack easier to reason about.
The download client is one of the earliest places where the torrent’s file list becomes visible.
qBittorrent has an Excluded file names feature that can be used as a first-pass policy gate.
For a media-only workflow, an example list might include:
*.exe
*.sh
*.bat
*.cmd
*.com
*.ps1
*.vbs
*.scr
*.msi
*.lnk
That is an example, not a universal blacklist.
The useful rule is simpler:
If a file type has no legitimate reason to appear in this workflow, do not select it for transfer by default.
In a working exclusion path, a matching file should become unwanted rather than being selected for transfer.
Conceptually:
torrent metadata
|
v
inspect file names
|
+--> expected media ----> normal download
|
`--> blocked pattern ---> unwanted
That is valuable because the decision happens before import.
It is much better to reject an unexpected executable or script while the torrent is still download-side state than after it has already reached the media library.
But filename filtering has obvious limits.
A file can have a misleading extension.
Unwanted content can be packaged inside another file.
A valid media container can still contain malformed or hostile data.
So this layer should be described as a filename policy, not malware detection.
There is another reason I do not treat an enabled checkbox as evidence that a control is working.
qBittorrent 5.2.x has had a confirmed WebUI regression where Excluded file names could be ignored when a torrent was added through the WebUI.
That distinction is important.
The upstream report is specifically about the WebUI path. It does not prove that every API, watch-folder, or automation ingestion path behaves the same way.
So the useful invariant is not:
Excluded file names = enabled
The useful invariant is:
a torrent added through the real production path
causes a matching file to become unwanted
Version matters.
Ingestion path matters.
Observed behavior matters more than configuration state.
That lesson applies to much more than qBittorrent.
Rejecting a file is only half of the workflow.
Sonarr or Radarr may already be tracking the release that produced the torrent.
If qBittorrent refuses every useful payload file, the Arr application can be left waiting for something that will never become importable.
That is where the queue supervisor becomes useful.
In this stack, that job belongs to Cleanuparr.
The failure path becomes:
Sonarr / Radarr approve release
|
v
qBittorrent receives metadata
|
v
payload violates filename policy
|
v
files become unwanted
|
v
nothing useful can be imported
|
v
Cleanuparr sees failed queue state
|
+--> remove download
+--> fail / clean queue item
`--> replacement when configured
This is a good example of why I prefer small components with explicit ownership.
qBittorrent does not need to understand Sonarr’s queue.
Sonarr does not need to implement qBittorrent’s filename policy.
Cleanuparr does not need to inspect media containers.
Each one handles the state it already understands.
The important part is that a blocked download reaches a complete workflow outcome instead of becoming a permanent queue mystery.
I wanted to prove the blocked-download path without downloading, storing, or distributing an actual malicious executable.
There was no reason to introduce a real payload just to test plumbing.
The useful canary was torrent metadata describing a deliberately blocked synthetic filename.
Conceptually:
arr-canary/
└── blocked-test.exe
The filename is the test condition.
The file does not need to contain executable code.
That makes it possible to test:
torrent metadata parsing
|
v
filename exclusion
|
v
unwanted-file state
|
v
Arr tracked-download state
|
v
Cleanuparr classification
|
v
removal / replacement behavior
without turning a workflow test into a malware-handling exercise.
This also exposed one of the more useful lessons from rebuilding the stack.
My first instinct was to insert the test directly into qBittorrent.
That proved the qBittorrent rule.
It did not prove the stack.
The production workflow begins farther upstream.
Sonarr or Radarr creates the tracked download state that the rest of the system later observes.
A torrent inserted manually into qBittorrent therefore does not necessarily carry the same application context.
The better test begins where the real workflow begins.
If the real event originates upstream, inject the canary upstream.
That sounds obvious after the fact, but it is an easy mistake to make when testing distributed systems one component at a time.
Not every synthetic release reached qBittorrent on the first try.
One candidate did not satisfy the active quality/profile policy.
Another fell below the application’s minimum-size rules.
Initially those looked like failed tests.
They were actually useful evidence.
The application rejected something it was supposed to reject, and it did so before creating downstream state.
A safe test should have gates:
metadata parses
|
v
correct target identified
|
v
release policy accepts candidate
|
v
only then create downstream state
If the canary stops at one of those gates, that is information.
The important part is knowing which gate stopped it.
This is another reason I prefer test evidence over a final green checkbox.
A failed canary with a clear reason tells me more than a successful canary whose path I never inspected.
qBittorrent owns transfer state.
It should not own the media library.
Once a download is acceptable, Sonarr or Radarr remains responsible for deciding what becomes library content.
That keeps one authoritative location for:
The import boundary therefore stays:
qBittorrent
|
completed download
|
v
Sonarr / Radarr
|
authoritative import
|
v
media library
This was useful operationally in Part 1.
It is useful for security for the same reason: there is one well-defined transition between “downloaded content” and “library content.”
Part 1 covered the storage layout in more detail, but hardlinks are worth mentioning again here because they let the authoritative importer do its job without requiring a second physical copy.
Conceptually:
/data/torrents/example.mkv
|
| same inode
|
/data/media/example.mkv
Sonarr or Radarr creates the library entry while the download-side path can remain available for seeding.
That gives me:
Hardlinks only work when the relevant paths are on the same filesystem and the container mounts expose that relationship correctly.
If those conditions are not true, the Arr application may fall back to copying.
The important security property is not the hardlink itself.
It is that the download client still does not become the library authority.
After import, I wanted one more check that did not require handing another application unrestricted write access to the library.
That is where Tdarr fits.
I am not using it here as an automatic transcoding pipeline.
Its job in this design is narrower:
imported media
|
v
structural health check
For this role, I do not need active transcode workers.
I also do not need GPU access simply because Tdarr supports it.
The mount policy can stay narrow:
volumes:
- ${MEDIA_ROOT}:/media:ro
- ${TDARR_TEMP}:/temp
The media tree is read-only.
The scratch area is writable.
That is the boundary I care about.
Tdarr can inspect the library, maintain its own application state, and write temporary data without receiving permission to rewrite the media tree.
This is another place where terminology matters.
A successful media health check does not tell me:
this file is safe
It tells me something closer to:
the configured media health check
did not report structural corruption
There is also a timing issue.
In this design, Tdarr checks media after Sonarr or Radarr imports it.
That means Jellyfin can potentially see the imported item before the health check finishes.
So this is not a quarantine architecture.
A real quarantine system would need another boundary:
download
|
v
staging area
|
v
authoritative validation gate
|
PASS / FAIL
|
v
final media library
That is a different design with different operational costs.
I am not claiming to have built it here.
The read-only Tdarr check is another layer of visibility, not a pre-consumption security gate.
Put together, the stack now has several opportunities to say no:
Sonarr / Radarr
|
v
indexer path
|
v
qBittorrent through VPN
|
+--> blocked filename?
| |
| yes
| |
| v
| unwanted
| |
| v
| Cleanuparr
| |
| +--> remove / fail
| `--> replacement
|
`--> acceptable payload
|
v
Sonarr / Radarr
authoritative import
|
v
hardlink / copy
|
v
media library
|
+--> Tdarr read-only health check
|
`--> Jellyfin
No box in that diagram gets to declare the entire result trustworthy.
That is intentional.
I try to phrase the result narrowly.
Not:
the file passed security scanning
And definitely not:
the file is malware-free
A more defensible description is:
The download followed the expected network path, matched the configured torrent-file policy, survived queue enforcement, was imported by the authoritative Arr application, and did not produce a finding in the configured structural media check.
That sentence is less exciting.
It is also much closer to what the system actually knows.
Defense in depth works best when every layer is allowed to make only the claim it can support.
The pattern here is not specific to media automation.
The same structure works anywhere an automated pipeline consumes untrusted input:
contain the network path
|
v
reject obviously invalid input early
|
v
let the workflow owner make state transitions
|
v
validate with reduced privileges
|
v
record what actually happened
The last line is where Part 3 begins.
At this point the stack has useful boundaries, but a boundary that silently stops working is not much of a boundary.
The final part of this series will turn the assumptions in Parts 1 and 2 into explicit health invariants: VPN state, forwarded-port state, authenticated management endpoints, queue behavior, read-only mounts, and stateful DOWN/RECOVERED monitoring.
The goal is to stop asking whether all the containers are merely “up” and start asking whether the system is still behaving the way it was designed to behave.
I ended up revisiting mine after a VPN and port-forwarding problem forced me to trace the path end to end. That was useful for a different reason: it exposed which services actually needed to share a failure domain, which ones only needed to talk to each other, and where I had let convenience blur the boundaries.
This is the first of three posts. It starts with the boring part that saves the most time later: deciding what each service owns, making the storage layout support hardlinks, and keeping the VPN boundary as small as it needs to be.
The examples are intentionally generic. There are no real addresses, hostnames, credentials, account details, media titles, or deployment-specific paths here.
The basic download path is short:
request / monitored item
|
v
Sonarr or Radarr
|
v
Jackett
|
v
qBittorrent
|
v
Sonarr/Radarr import
|
v
media library
|
+----> Jellyfin
|
`----> Tdarr health check
The supporting services sit around that path rather than replacing it:
Recyclarr -> configuration policy for Sonarr/Radarr
Cleanuparr -> queue cleanup and blocked-download handling
Gluetun -> VPN egress and firewall for selected services
FlareSolverr -> browser-challenge helper for compatible indexers
That distinction matters. The easiest way I found to reason about the stack was to stop thinking in terms of “the Arr containers” and instead ask one question for each service:
What state is this application authoritative for?
Once that answer is clear, most of the architecture follows naturally.
Sonarr is the authority for television and Radarr is the authority for movies.
They decide what is monitored, which quality policy applies, whether a release is acceptable, which download client receives it, and where an imported file belongs in the final library.
qBittorrent should not independently reorganize completed media into the library. It downloads. Sonarr and Radarr import.
That gives a clean boundary:
qBittorrent:
peer connections
torrent state
transfer state
download paths
Sonarr / Radarr:
media identity
release policy
naming
import state
final library placement
Keeping that boundary intact also makes failures easier to understand. If a torrent completes but never appears in the library, the question is no longer “which container moved it?” The download client completed a transfer; the Arr application either imported it or recorded why it could not.
Jackett sits between Sonarr/Radarr and the configured indexers.
Its purpose here is compatibility. Sonarr and Radarr speak to Jackett through a normalized interface, and Jackett deals with the indexer-specific side.
That means an indexer failure is not automatically a Sonarr or Radarr problem. The failure may be in one indexer, Jackett itself, DNS, browser-challenge handling, or the network path Jackett uses.
FlareSolverr belongs next to Jackett for the same reason. It is a narrow helper for sites that require supported browser-challenge handling. It is not a media manager and it does not need a public-facing UI.
qBittorrent is the transfer engine.
It accepts work from the Arr applications, connects to peers, downloads and seeds data, reports progress, and maintains the category/download paths the rest of the stack expects.
Later in the series I use qBittorrent’s filename exclusion feature as one small security control. That control needs to be treated as a version- and workflow-specific policy gate, not as antivirus and not as proof that a download is safe.
Recyclarr is useful because quality definitions, profiles, custom formats, scores, and naming policy are configuration that can drift.
It synchronizes the desired policy into Sonarr and Radarr. It does not download anything and it should not be treated as proof that every existing movie or series is assigned to the profile you intended.
Those are separate checks:
Does the desired profile exist?
!=
Is this item actually assigned to it?
Cleanuparr watches the workflow for conditions that need cleanup or intervention.
In this design it is useful for things such as failed imports, blocked downloads, stalled or otherwise unusable queue entries, and replacement searches after a bad download is removed.
It is an automation and enforcement layer. It is not a malware scanner.
Tdarr is commonly used for transcoding, but I am deliberately using only a small part of it here: media health checking after import.
The media library is mounted read-only. Scratch space can be writable, but the checker does not need permission to rewrite the authoritative library.
media library
|
| read-only
v
Tdarr
|
`--> structural media health check
This is not a quarantine system. A successful media health check tells me something about the structure of the media file; it does not prove that the file is malware-free.
Jellyfin is at the far end of the pipeline. It reads the organized library and handles playback, clients, metadata and transcoding where required.
It has no reason to participate in torrent acquisition.
That separation is useful operationally and from a permissions standpoint: the media server should not need credentials or network access that only the acquisition side uses.
Container networking gets a lot of attention in these stacks, but the path layout causes just as many avoidable problems.
The goal is for the downloader and importers to see one consistent filesystem tree:
/data
├── torrents
│ ├── incomplete
│ ├── tv
│ └── movies
└── media
├── tv
└── movies
qBittorrent writes under /data/torrents. Sonarr and Radarr see those same paths and also see their destinations below /data/media.
That consistency matters because it lets the applications use the filesystem directly instead of translating unrelated container paths with Remote Path Mappings.
It also makes hardlinks possible when the download and media directories are on the same filesystem.
/data/torrents/tv/example.mkv
|
| hardlink
v
/data/media/tv/Series/example.mkv
Both directory entries can refer to the same underlying file data. The torrent can continue seeding from the download path while the library gets its organized filename immediately, without storing a second full copy.
If the source and destination are on different filesystems, that does not work. I would verify this before configuring the applications rather than discover it after a large import starts copying data.
Bringing up every container at once makes the first failure unnecessarily hard to isolate. A better order is to prove one boundary at a time.
Decide where incomplete downloads, completed downloads and final media live.
Verify that the container-visible paths are consistent and that the paths intended for hardlinks are on the same filesystem.
Before attaching another service, verify the VPN tunnel, firewall behavior, intended IPv4/IPv6 policy and provider-side port forwarding if it is part of the design.
Do not treat “container is running” as proof that the network path is correct.
Attach qBittorrent to the VPN namespace and prove that it fails closed.
Then verify the actual torrent settings: listening interface, listening port, random-port behavior, UPnP policy and category paths.
Add the importers only after the download path works.
Configure one known-good download and import before adding more automation. If that path is not solid, Recyclarr and cleanup rules only add more variables.
Add indexers gradually. Test them independently.
“Jackett is running” does not mean every configured indexer works.
Introduce policy synchronization after Sonarr and Radarr are stable. Use preview/dry-run behavior where available and inspect what it intends to change.
Start with observation and narrow rules. Cleanup automation should not be the thing hiding a broken normal download/import path.
Add read-only health checking after the library path is proven. Transcoding can be a separate project; it does not need to be mixed into the first validation pass.
This was the architectural change that made the stack much easier to troubleshoot.
A common Compose layout puts every application behind Gluetun because it is convenient:
network_mode: "service:gluetun"
That is exactly what I want for qBittorrent. If the VPN disappears, qBittorrent should not quietly fall back to the host’s normal route.
It is not what I want for the entire control plane.
Sonarr and Radarr do not inherently need their own Internet traffic to share qBittorrent’s network namespace. Recyclarr and Cleanuparr do not need to disappear just because the VPN is unhealthy. Tdarr has nothing to do with acquisition egress at all.
The split I settled on is:
normal Compose network
├── gluetun
├── sonarr
├── radarr
├── recyclarr
└── cleanuparr
share Gluetun network namespace
├── qbittorrent
├── jackett
└── flaresolverr
separate bridge
└── tdarr
qBittorrent, Jackett and FlareSolverr are intentionally coupled to the VPN.
The control-plane applications are not.
Because Sonarr and Radarr share a Docker network with Gluetun, Docker service discovery and Gluetun’s shared-network model still let them reach services inside the Gluetun namespace through the Gluetun service name and the appropriate application port:
sonarr/radarr
|
+----> gluetun:<qbit-port>
|
`----> gluetun:<jackett-port>
That gives the failure mode I actually want:
VPN failure
|
+--> qBittorrent loses Internet access
+--> Jackett loses Internet access
+--> FlareSolverr loses Internet access
|
+--> Sonarr remains reachable
+--> Radarr remains reachable
+--> Recyclarr remains reachable
+--> Cleanuparr remains reachable
`--> Tdarr remains reachable
The VPN can fail without taking the tools needed to diagnose the failure down with it.
This is convenient:
ports:
- "8080:8080"
but Docker interprets a short port mapping without a host address as a publication on all host interfaces.
For management interfaces I prefer an explicit trusted binding:
ports:
- "${MGMT_IP}:8080:8080"
or no host publication at all when another controlled access path already exists.
Helper services that do not need direct user access should remain internal.
The same principle applies to authentication. “It is only on my LAN” is not a useful reason to leave an administrative interface unauthenticated.
Public examples should contain placeholders, not sanitized-looking real credentials.
For Gluetun specifically, Docker secret files are supported for sensitive values such as OpenVPN credentials. That is preferable to teaching readers to paste real passwords directly into a Compose file.
At a minimum, the public version of a stack should never contain:
VPN credentials
Arr API keys
Jackett API keys
qBittorrent passwords or cookies
webhook URLs
authentication databases
resolved Compose output containing secrets
The same rule applies to screenshots and diagnostic output. A screenshot can undo all the work that went into sanitizing the article around it.
At this point each service has a clear owner, storage paths are designed for the import behavior we want, and the VPN contains only the applications that actually need to fail with it.
That is enough architecture for one post.
Part 2 will deal with the less comfortable side of a media automation stack: untrusted download metadata and payloads, filename exclusions, queue enforcement, safe canaries, and read-only post-import validation.
Part 3 will turn the assumptions from the first two posts into health invariants and stateful monitoring.
GitHub Pages is enough for that.
This walkthrough starts with the smallest possible site and verifies that GitHub can actually serve it before adding Jekyll, layouts, CSS, or anything else. That makes troubleshooting a lot easier than building the whole site first and wondering which part broke.
The commands use GitHub CLI because I wanted to do the setup from the terminal. gh is not a requirement for GitHub Pages. If you would rather create the repository and configure Pages in the GitHub web interface, that works too.
All usernames, paths, and other identifying values below are examples. Replace them with your own.
At minimum:
For the CLI-only version:
gh)Check Git:
git --version
Check GitHub CLI:
gh --version
On Gentoo, GitHub CLI is available as:
doas emerge --ask github-cli
If you are not using gh, create the repository through GitHub’s web interface and skip the CLI-specific commands below.
Start the login:
gh auth login
For GitHub.com, the browser-based login is the easiest option on a normal workstation.
Afterward:
gh auth status
You should see the account you intended to use and no authentication errors.
One security rule worth establishing immediately: do not put access tokens into blog screenshots, shell examples, or Markdown files. There is almost never a reason to run a command that prints your GitHub token while writing a tutorial.
Rather than typing the account name into every command, get it from the authenticated session:
GHUSER="$(gh api user --jq '.login')"
printf 'GitHub username: %s\n' "$GHUSER"
For a personal GitHub Pages site, the repository name is:
YOUR-GITHUB-USERNAME.github.io
Using $GHUSER also avoids accidentally creating the repository with a typo.
I keep blog repositories under ~/blog/git, but the local path does not matter to GitHub.
mkdir -p ~/blog/git
cd ~/blog/git
Create the repository:
GHUSER="$(gh api user --jq '.login')"
gh repo create "${GHUSER}.github.io" \
--public \
--add-readme \
--description "Personal blog" \
--clone
Then enter it:
cd "${GHUSER}.github.io"
The --add-readme is useful here for more than convenience. It gives the new repository actual content immediately, which is enough for the first Pages smoke test.
Check the local side:
git --no-pager status
git remote -v
git branch --show-current
A fresh repository should be on its default branch with a clean working tree.
Now check GitHub’s view of it:
gh repo view \
--json nameWithOwner,visibility,url,defaultBranchRef
Things I care about at this point:
YOUR-GITHUB-USERNAME.github.ioorigin remoteIf any of those are wrong, fix them now. There is no reason to start building a site on top of a bad repository setup.
This surprised me during setup: by the time I checked the new user-site repository, Pages was already configured and built.
You can query it directly:
GHUSER="$(gh api user --jq '.login')"
gh api \
"repos/${GHUSER}/${GHUSER}.github.io/pages" \
--jq '{
status: .status,
url: .html_url,
source: .source,
https_enforced: .https_enforced
}'
A working configuration may look roughly like:
{
"https_enforced": true,
"source": {
"branch": "main",
"path": "/"
},
"status": "built",
"url": "https://YOUR-GITHUB-USERNAME.github.io/"
}
If you get valid Pages configuration, leave it alone.
If the API instead returns HTTP 404 because Pages has not been configured, it can be enabled from the CLI:
GHUSER="$(gh api user --jq '.login')"
gh api \
--method POST \
"repos/${GHUSER}/${GHUSER}.github.io/pages" \
--input - <<'JSON'
{
"source": {
"branch": "main",
"path": "/"
}
}
JSON
If your default branch is not main, use the actual branch name rather than copying that value blindly.
Then query /pages again and make sure the configuration is what you expected.
Do this before adding Jekyll.
curl -I "https://${GHUSER}.github.io/"
Or, if all you care about is the result:
curl -fsS -o /dev/null \
-w 'Homepage: %{http_code}\n' \
"https://${GHUSER}.github.io/"
The useful result is:
Homepage: 200
At this point the important part is already proven:
local Git repository
|
v
GitHub repository
|
v
GitHub Pages
|
v
HTTPS request returns 200
That is the publishing path.
Everything after this is site structure and design.
Now add the minimum Jekyll structure.
Create a posts directory:
mkdir -p _posts
mkdir -p _layouts
Create _config.yml:
title: YOUR-BLOG-NAME
description: Notes on Unix, infrastructure, security, networking, and whatever else breaks.
url: "https://YOUR-GITHUB-USERNAME.github.io"
baseurl: ""
markdown: kramdown
permalink: /:year/:month/:day/:title/
Do not put secrets in this file. It is part of a public site repository.
Create _layouts/default.html:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>
How to Create a Free Blog on GitHub (CLI-Based) | Unix Magick
</title>
</head>
<body>
<main>
</main>
</body>
</html>
There is intentionally no theme or CSS here.
The goal is still to prove the content pipeline before working on appearance.
Create index.md:
---
layout: default
title: YOUR-BLOG-NAME
---
# YOUR-BLOG-NAME
A place for technical notes, troubleshooting, and project write-ups.
## Posts
- [Build a Hardened Arr Stack with Docker Compose: Gluetun, Hardlinks, and Health Checks](/2026/09/01/build-a-hardened-arr-stack/) — 2026-09-01
- [Operationalizing an Arr Stack: Health Invariants and Stateful Alerting](/2026/08/28/operationalizing-an-arr-stack/) — 2026-08-28
- [Hardening an Arr Stack: Defense in Depth from Torrent to Library](/2026/08/27/hardening-an-arr-stack/) — 2026-08-27
- [Building an Arr Stack: What Each Service Should Own](/2026/08/26/building-an-arr-stack/) — 2026-08-26
- [How to Create a Free Blog on GitHub (CLI-Based)](/2026/08/25/create-free-blog-github-cli/) — 2026-08-25
That loop means new posts automatically appear on the homepage.
Jekyll posts use a date-prefixed filename:
_posts/YYYY-MM-DD-post-name.md
For a simple test:
---
layout: default
title: "Site Online"
date: 2026-01-01
---
The site is online.
Use the real publication date when you create your own file.
At this stage the site is ugly, which is fine. Ugly and working is much easier to improve than attractive and broken.
This is the part I would not skip on a technical blog.
Start with:
git --no-pager status --short
Then stage only the files you meant to add:
git add \
_config.yml \
_layouts/default.html \
index.md \
_posts/
Review the staged diff:
git --no-pager diff --cached
Actually read it.
For a public technical blog, I specifically look for:
.gitignore is useful, but it is not a substitute for reviewing what you are about to publish.
If a secret was already committed, adding it to .gitignore afterward does not remove it from Git history.
Once the staged diff is clean:
git commit -m "Create initial blog"
git push
Now GitHub has the Jekyll source.
Check the latest build:
GHUSER="$(gh api user --jq '.login')"
gh api \
"repos/${GHUSER}/${GHUSER}.github.io/pages/builds/latest" \
--jq '{
status: .status,
error: .error.message,
commit: .commit,
created_at: .created_at,
updated_at: .updated_at
}'
You are looking for a successful build and no error message.
Then test the homepage again:
curl -fsS -o /dev/null \
-w 'Homepage: %{http_code}\n' \
"https://${GHUSER}.github.io/"
And test the first post using its actual permalink:
curl -fsS -o /dev/null \
-w 'Post: %{http_code}\n' \
"https://${GHUSER}.github.io/YYYY/MM/DD/POST-NAME/"
Both should return:
200
Now there are two verified paths:
Markdown -> Jekyll -> homepage -> 200
Markdown -> Jekyll -> post -> 200
That is enough infrastructure for a real blog.
At this point I would stop.
No custom domain.
No analytics.
No third-party JavaScript.
No theme dependency.
No giant pile of plugins.
No redesign directly on the production branch.
Get the basic publishing path working first. Once that is boring and repeatable, make a separate branch for layout and design work and test it locally before merging it into production.
That is exactly where the interesting part starts, but it should not be mixed into the initial bring-up.
Repository state:
git --no-pager status --short
Review staged changes:
git --no-pager diff --cached
GitHub authentication:
gh auth status
Pages state:
gh api \
"repos/${GHUSER}/${GHUSER}.github.io/pages"
Latest Pages build:
gh api \
"repos/${GHUSER}/${GHUSER}.github.io/pages/builds/latest"
Public smoke test:
curl -fsS -o /dev/null \
-w '%{http_code}\n' \
"https://${GHUSER}.github.io/"
That is most of the operational surface area for a small static blog.
The rest is writing.
]]>