docs(deploy): a failed tunnel takes Jellyfin's internet with it (ADR 0032)
All checks were successful
CI / check (push) Successful in 41m43s
CI / deploy (push) Has been skipped

linuxserver/wireguard's client mode deletes the default route when wg0.conf
fails to come up, so Jellyfin, in its namespace, loses TMDb and scans get
frames for posters. The README's step 4 says so and how to recover; ADR
0032 holds the ways out, open for the developer to decide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
This commit is contained in:
Tizian 「ティツィアーン」 2026-10-31 14:24:22 +01:00
commit f015792927
Signed by: raisondetredev
GPG key ID: 07F6FCF405488B64

View file

@ -190,6 +190,17 @@ home machine.
`sudo wg show wg-jellyfin` on the instance's server now shows a handshake.
Whenever `wg0.conf` fails to come up (a placeholder or a wrong key, an endpoint that
doesn't resolve), the image's client mode deletes the namespace's default route
(`ip route del default` in its `svc-wireguard/run`, ls126), and Jellyfin with it loses
the internet: TMDb's metadata and images fail with *Network is unreachable*, and a
library scanned then gets frames of its videos for posters. A tunnel that comes up
keeps the route, even before its first handshake. Fixing `wg0.conf` alone isn't enough:
`docker compose up -d --force-recreate`, both containers, since Jellyfin lives in
WireGuard's namespace and a restart of WireGuard alone leaves it in the old one. The
folder `wireguard/` is the container's user's (61096) from its first start on, so
`wg0.conf` is edited with sudo.
5. 🏠 **Set Jellyfin up** at http://localhost:8096 on the home machine, before the site is
switched on: the sidecar's step 6, but for its networking, which is the tunnel's:
- Dashboard › Networking › **LAN networks**: `172.29.96.1/32` alone, the gateway