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

@ -186,3 +186,22 @@ as the sidecar isn't switched on. With `JELLYFIN_URL` unset, the instance sugges
its client mode brings up `wg0.conf` with the host's kernel module, and its `wg`
makes the home end's keys, so nothing is installed on the machine. Jellyfin's image
is the sidecar's, and so is its user ID, 61096.
## Open (31 Oct 2026, found setting the home end up; for the developer to decide)
- **A failed tunnel takes Jellyfin's internet with it.** The image's client mode deletes
the namespace's default route whenever `wg0.conf` fails to come up (`ip route del
default` in its `svc-wireguard/run`, ls126: a placeholder or wrong key, an endpoint
that doesn't resolve), so Jellyfin, in that namespace, reaches neither TMDb nor
anything else, and a library scanned then gets frames of its videos for posters. A
tunnel that comes up keeps the route, before its first handshake too. Noted in
`deploy/sidecars/README.md`, step 4. Ways out:
- keep it, documented (as now): a broken tunnel then also stops new metadata, which
is loud rather than silent;
- a custom service (the image's `/custom-services.d`; `/custom-cont-init.d` runs
before `svc-wireguard`, too early) that puts the route back once the tunnel has
failed, so Jellyfin keeps the internet whatever the tunnel does;
- Jellyfin on `outside` itself rather than in WireGuard's namespace, which changes
how Caddy's requests reach it (D8) and so reopens this record.
A test in `test/deploy/jellyfin_home_test.dart` for whichever is chosen.