TAPPaaS

Jellyfin

Open-source media server for personal movie, TV, music, and photo libraries.

Status: Testing — installed and live-tested on the reference site with its media on an NFS share (ADR-029). See INSTALL.md for installation and for the media share a site's server declares — before or after Jellyfin is installed.

Overview

Field Value
VM name jellyfin
Zone the environment's zone (zone0 from config/environments/<env>.json)
Port 8096
VM ID 360
App version 12.2
VM disk 32G on tanka1 — OS and Jellyfin's own data (/var/lib/jellyfin, metadata, cache)
Media /media — subdir jellyfin of the NFS share media (storage:nfs); a local directory while the share is pending

Storage

The media library is not in the VM. /media is the subdirectory jellyfin of the NFS share named media, served by a cluster node from its tankb pool through storage:nfs (ADR-029 v0.9):

No share yet? Jellyfin installs and works anyway, but the media then lives in /media on the VM's own 32G disk (on tanka1) — a stopgap, not a home for a library. Declare the media share for real use. When it arrives, the next update moves what /media holds into it — copied while Jellyfin runs, jellyfin.service stopped for the final pass, the old directory kept as /media.pre-nfs until the next healthy update — and mounts it. The module ships with rebootOk: true, so that happens without anyone present; Jellyfin is down for the final copy only.

Why: media is large and can be re-ripped or re-downloaded. It does not belong on the replicated tanka tier or in the VM's backup, and it should outlive the VM — deleting or rebuilding Jellyfin leaves the library where it is. For the same reason Jellyfin is deliberately not HA (no cluster:ha).

Every request is squashed to the share's owner (ADR-029 D7), so the jellyfin user reads and writes the share although the files on the server belong to one reserved uid.

Media Folders

update.sh creates the library folders — on the share, or on the VM's disk while the share is pending:

/media/
  Movies/           Jellyfin library: Movies
  TV/               Jellyfin library: Shows
  Music/            Jellyfin library: Music
  Photos/           Jellyfin library: Photos
  Audiobooks/       Jellyfin library: Books/Audiobooks

Another module that needs the library — a download client writing new media, say — gets its own grant on the share media and mounts it itself. It never goes through Jellyfin. subdir is organisation, not isolation: every consumer granted media can reach all of it (ADR-029 D15).

Module dependencies & traffic flow

graph LR
    jellyfin["jellyfin (zone: env zone, VM :8096)"]
    cluster["cluster:vm"]
    templates["templates:nixos"]
    backup["backup:vm"]
    nfs["storage:nfs"]
    netproxy["network:proxy / network:rules"]
    idoidc["identity:identity (OIDC, SSO-Auth plugin)"]
    node["share media — nfs-media.mgmt.internal (tankb pool on a node)"]
    caddy["Caddy reverse proxy (on the OPNsense firewall, :443)"]
    authentik["Authentik (identity) — Sign in with Authentik"]
    homeclients["home-zone clients (LAN)"]
    vpnpeers["netbird VPN peers (remote devices)"]
    internet["internet (public)"]

    jellyfin -->|dependsOn| cluster
    jellyfin -->|dependsOn| templates
    jellyfin -->|dependsOn| backup
    jellyfin -->|dependsOn| nfs
    jellyfin -->|dependsOn| netproxy
    jellyfin -->|dependsOn| idoidc

    jellyfin -.->|"NFSv4 tcp/2049 — /media = media/jellyfin"| node
    homeclients -.->|"https://jellyfin.&lt;domain&gt;"| caddy
    vpnpeers -.->|"same vhost, via WireGuard overlay"| caddy
    internet -.->|"proxyAllowedZones includes internet"| caddy
    caddy -.->|"upstream :8096"| jellyfin
    jellyfin -.->|"OIDC: Sign in with Authentik"| authentik

Solid arrows are declared dependsOn edges (install-order dependencies). Dashed arrows are traffic: network:proxy creates the jellyfin.<domain> vhost on the Caddy reverse proxy, and proxyAllowedZones (home, netbird, internet) controls which source zones that vhost accepts. There is no Authentik gate in front: Jellyfin's apps log in to its own API, and they must work for friends and family away from the site. Who gets in is decided at Jellyfin's login (below). The NFS path to the share is the one rule network:rules derives from the mount (none while it is pending).

Access: Jellyfin's own login, for the web and the apps

https://jellyfin.<domain> answers Jellyfin itself, from home, from netbird and from the internet alike (home clients resolve the same name to Caddy, ADR-021). Jellyfin's apps on TVs, phones and computers can therefore reach it from anywhere — the point: friends and family use them from their own homes.

What protects it on the internet

Quick Start

# installs with or without a media share — see INSTALL.md → Media share
cd "${TAPPAAS_REPO:-/home/tappaas/TAPPaaS}"/src/home/jellyfin
install-module.sh jellyfin

See INSTALL.md for full instructions.