halkyon/docs/adr/0032-jellyfin-at-home.md

ADR 0032: Jellyfin at home, published by the instance through WireGuard

• Status: decided 30 Oct 2026, by the developer (D1, D9 and D10 their own choices, D2–D8 agreed as recommended). Built the same day (As built, below); not brought up yet, which takes the developer's steps as root on the instance's server.
• Builds on: the Jellyfin sidecar (deploy/compose.jellyfin.yaml, deploy/sidecars/README.md, decided 14 Oct 2026) and Halkyon Learn's suggested server (JellyfinSuggestion, decided 13 Oct). Train's Jellyfin (ADR 0030, D47, D52, D54) reaches it the same way.

Context

The Jellyfin sidecar runs Jellyfin on the instance's server, with its media copied there (deploy/jellyfin/media/). The developer's media is at home, on a machine in the home network (192.168.178.0/24, behind a FRITZ!Box), and should be reachable as jellyfin.halkyon.eu, where learn.halkyon.eu's people would find it, under three conditions the developer set on 30 Oct:

• the home network's address is never exposed: neither DNS nor anything Jellyfin answers names it;
• nobody signs up: accounts are the admin's to make (Jellyfin has no self-registration, but a fresh server's setup wizard is open to whoever reaches it first, and a user's password can be set from outside, which deploy/sidecars/jellyfin.caddy refuses);
• Halkyon's apps reach Jellyfin over HTTPS alone (Learn's JellyfinRepository.find, Train's D54), so the name needs a certificate every device trusts.

Found on 30 Oct: halkyon.eu's DNS is at Infomaniak; jellyfin.halkyon.eu already points at learn.halkyon.eu's server (A 89.58.53.154 and an AAAA), but nothing answers there, as the sidecar isn't switched on. With JELLYFIN_URL unset, the instance suggests https://jellyfin.halkyon.eu to its people as soon as a Jellyfin server answers there.

Decisions

• D1 A WireGuard tunnel from home to the instance's server, which publishes Jellyfin (the developer's choice, 30 Oct, as recommended). Alternatives weighed:

  • Cloudflare Tunnel: hides the address too, but needs all of halkyon.eu's DNS moved to Cloudflare (a tunnel needs a zone on Cloudflare's nameservers on the free plan), lets Cloudflare read every password, token and video (it ends TLS), conflicts with Cloudflare's terms for serving mostly video outside its paid video products, and leaves jellyfin.caddy's rules to be rebuilt as Cloudflare's.
  • An SSH reverse tunnel (ssh -R as deploy, kept up by autossh): no new software on the server, but TCP over TCP stalls a stream on a lossy line, and binding where a container reaches it needs sshd's GatewayPorts changed.
  • The sidecar as built, the media copied to the server: no tunnel at all, but the server's disk holds the library.

  The public sees only the instance's server, TLS ends on a machine the operator holds, jellyfin.caddy and the sidecar README's settings hold unchanged, and the DNS record is already right. Streams are bounded by the home line's upload speed and count towards the server's traffic.

• D2 The home end runs in Compose, Jellyfin inside the tunnel's network namespace (recommended; over WireGuard on the home host with Jellyfin's port bound to the tunnel's address, which Docker can't bind before the interface is up, and over firewall rules on the home host). A wireguard container (cap_add: NET_ADMIN, the host's kernel module) holds the tunnel; Jellyfin joins it with network_mode: service:wireguard, so it listens on the tunnel and on that namespace's loopback alone, and is not on the home network at all (no DLNA, no discovery on UDP 7359). The admin port is published on the home host's loopback only (127.0.0.1:8096), where Learn on the same machine may reach it over plain HTTP (isLoopback). The home end dials out with PersistentKeepalive = 25, so the FRITZ!Box needs no open port, and the server's config holds no endpoint for it. The files live beside the deploy as deploy/home-jellyfin/ (compose file, WireGuard config without its key; the steps in the sidecar README); the key stays out of the repository.

• D3 The tunnel's addresses are 10.61.96.1 (the server) and 10.61.96.2 (home), a /30, IPv4 alone (recommended): outside Docker's address pools (172.17.0.0/16 to 172.31.0.0/16 and 192.168.0.0/16 in /20s, which a new network could take), the edge network (172.30.80.0/24), the home network and Multipass' bridges on the laptop (10.97.x.0/24). Caddy reaches Jellyfin over IPv4; visitors keep coming over either.

• D4 WireGuard on the server's host, as wg-quick@wg-jellyfin, on UDP 51820 (recommended, over a WireGuard container on edge, which would need NET_ADMIN beside the instance and routes into it from Caddy). The port is opened in the host's firewall; WireGuard answers nothing that isn't signed by a known key, so it shows no service to a scan. The home peer's AllowedIPs on the server is 10.61.96.2/32, so nothing it sends under another source address gets in. The server's key is kept in /etc/wireguard/ (root, 0600) and in the operator's password manager, as a new server needs it again.

• D5 The tunnel reaches Jellyfin from Caddy alone, and reaches nothing on the server (recommended), by rules that wg-quick's PostUp sets and PreDown removes, so they live exactly as long as the interface:

  • in DOCKER-USER: 172.30.80.2 (Caddy) to 10.61.96.2 on TCP 8096 accepted; every other new connection into or out of wg-jellyfin dropped, replies (ESTABLISHED,RELATED) passing;
  • in INPUT: nothing new from wg-jellyfin accepted, so home can't reach sshd, published ports or anything else listening on the host.

  The rules match Caddy's own address, as DOCKER-USER sees packets before Docker masquerades them; home then sees them from 10.61.96.1 (Docker's MASQUERADE for edge, which takes every packet leaving the network; found while building, the proposal had them arrive as 172.30.80.2), so home's AllowedIPs is 10.61.96.1/32 alone. A compromised home machine thus gets replies to Caddy's requests and nothing else of the production server.

• D6 The CI runner can't reach the tunnel either (recommended): 10.61.96.0/30 is added to IPAddressDeny in deploy/runner/forgejo-runner.service, beside Docker's ranges. Without it, a job could talk to the home Jellyfin through the host's route.

• D7 One site, with its upstream a setting (recommended, over a second site file repeating the rules): jellyfin.caddy proxies to {$JELLYFIN_UPSTREAM:jellyfin:8096}. A new deploy/compose.jellyfin-home.yaml mounts the same site into Caddy, sets JELLYFIN_DOMAIN and JELLYFIN_UPSTREAM=10.61.96.2:8096, leaves the server's JELLYFIN_URL unset (D9) and runs no Jellyfin container; COMPOSE_FILE takes either it or compose.jellyfin.yaml, never both. redeploy.sh needs no change: WireGuard is the host's, set up once by root, as the sidecars' users are.

• D8 Jellyfin's own settings for a server seen through a proxy (recommended; the sidecar README's step 6, with two additions): JELLYFIN_PublishedServerUrl = https://jellyfin.halkyon.eu, so Jellyfin never hands out a home address; LAN networks set to 172.29.96.1/32 alone (the gateway of the home end's Compose network, its subnet fixed for it, through which Docker hands on what reaches the machine's loopback; the proposal said 127.0.0.1/32, which no request comes from), as Jellyfin counts every private range as local when it's left empty, which would count the tunnel too and let an admin without remote access sign in through it; Known proxies 10.61.96.1, as which Caddy's requests arrive (D5). The admin works from the home machine's http://localhost:8096, not through an SSH tunnel; the wizard is finished there before the tunnel is first brought up.

• D9 learn.halkyon.eu suggests it to all its people (the developer's, 30 Oct, over JELLYFIN_URL=none), while it answers: the compose file leaves JELLYFIN_URL unset, so the instance looks at https://jellyfin. on its own domain (JellyfinSuggestion) and suggests it only once it answers as a Jellyfin server. Set, the instance would suggest it whether it answers or not, which D10 makes the wrong default. Its login screen shows only the accounts meant for everyone; the admin and every personal account are hidden from it (D8, the sidecar README's step 6).

• D10 The home end is the developer's own machine, this laptop (the developer's, 30 Oct, over an always-on machine at home): Jellyfin is reachable while it runs and away otherwise, which is accepted. It dials out, so it serves from wherever the laptop is online, not only at home, as long as outgoing UDP passes. Asleep, the tunnel stops; on waking, the next keepalive brings it back within 25 s.

• D11 The home end dials the server by its address (the developer's, 31 Oct, found setting the home end up): Endpoint = 89.58.53.154:51820 in wg0.conf, not learn.halkyon.eu. Whenever wg0.conf fails to come up, linuxserver/wireguard's client mode deletes the namespace's default route (ip route del default in its svc-wireguard/run, ls126: a kill switch, for the VPN clients it is made for), so Jellyfin, in that namespace, reaches neither TMDb nor anything else, and a library scanned then gets frames of its videos for posters, until both containers are recreated. Bringing an interface up needs no network, but resolving a name does (wg retries it for some seconds, then fails), so on the home end (D10), starting or waking before its network and DNS, the name made that failure recur. By address it comes up whatever the network does, the handshake following once it is back; what is left is a placeholder or a wrong key, met once while setting it up, which the sidecar README's step 4 says how to recover from. IPv4, which every home network has. A new address of the server's has to be written in by hand. Over a custom service in the image's /custom-services.d putting the route back (working against the image's kill switch and resting on its scripts as ls126 has them, which an update may change unnoticed), and over turning the namespace round, Jellyfin owning it and a WireGuard container without a kill switch joining it (a new D2 for a failure the address all but removes).

Consequences

• People reaching jellyfin.halkyon.eu see the instance's server alone. The instance's server knows the home address (the tunnel's endpoint, in wg show), as its operator does anyway; nothing it serves names it.
• Every byte streamed crosses the home line's upload and the server twice (in through the tunnel, out to the visitor). Learn streams as stored (static=true), so a video's bitrate must fit the upload; Train's smaller copies (D52) are transcoded at home.
• The production server gains a listening UDP port, a kernel interface and firewall rules outside Compose; they belong in the sidecar README's steps, with how to switch them off (systemctl disable --now wg-quick@wg-jellyfin, the port closed).
• With the laptop off, asleep or offline, Caddy answers 502 at jellyfin.halkyon.eu; Learn and Train show the server as unreachable, as for any Jellyfin that is away. The instance stops suggesting it at its first look after that: a look counts for an hour, and the first instance.info() after the hour starts the next one in the background, that answer still giving the old suggestion. Apps that took the suggestion already keep it (the app asks once), and devices signed in to it keep their token.
• The instance's own look reaches jellyfin.halkyon.eu at its public address from inside its container, through the host back to Caddy. With the sidecar this was never used in production, as its compose file sets JELLYFIN_URL; the check after setup confirms that instance.info() names it.

As built (30 Oct 2026, the agent's calls, each with its reason)

• Files: deploy/compose.jellyfin-home.yaml and jellyfin.caddy's upstream ({$JELLYFIN_UPSTREAM:jellyfin:8096}, D7); deploy/home-jellyfin/ with the home end's compose.yaml and wg0.conf.example, and under server/ the instance's wg-jellyfin.conf, its rules (wg-jellyfin-rules.sh, POSIX sh as the host's scripts are: the host has no Dart) and a systemd drop-in; the steps in deploy/sidecars/README.md, Jellyfin at home. test/deploy/jellyfin_home_test.dart holds each rule above to the files, refusals first: no JELLYFIN_URL, the home peer's one address, the drops, the runner's deny, Jellyfin inside the tunnel's namespace, its port on the loopback alone.
• The rules in chains of their own (halkyon-jellyfin-forward, -input), jumped to from DOCKER-USER and INPUT for the tunnel's interface alone, so their order against Docker's rules is fixed and down removes all of them, a half-made set too. RETURN rather than ACCEPT for what passes, so Docker's own rules still apply.
• The tunnel starts after Docker and restarts with it (After, Requires, PartOf=docker.service): its rules go into Docker's chain, which exists only once Docker runs.
• The server's private key is a file beside the config (PostUp = wg set %i private-key …), so wg-jellyfin.conf is copied from the repository as it is, but for the home end's public key.
• The server looks at Jellyfin through Caddy on edge (extra_hosts, the domain at 172.30.80.2), not at the public address from inside its container, which needs Docker's hairpin NAT and, by the AAAA record, IPv6 to work for it. The certificate is the domain's, so the look is as anyone's.
• CI's Sandbox step also fails if a job reaches 10.61.96.2:8096, as it does for Docker's networks: the deny in the runner's unit is only on the server once installed again (step 3).
• The home end's image is linuxserver/wireguard 1.0.20260223-r0-ls126, of 15 Oct 2026, pinned by its digest: two weeks old, rather than the build of the day before; 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.