Overview
Runs Jellyfin, a media server for movies, shows, music and photos, with apps for browsers, phones and TVs. The block is a singleton that runs where its volume's primary is, behind a VIP. The volume holds what Jellyfin cannot rebuild: its SQLite database (users, watch history, sessions), its settings and library definitions, and downloaded metadata and artwork. The media itself is not on the volume; every node reads it from the same path. The image cache and transcodes go to the unit's private /tmp, so they are never replicated and are rebuilt after a failover.
pkgs.jellyfin brings Jellyfin's web client and its own ffmpeg.
Open http://<VIP>/ right after deploying: until Jellyfin's startup wizard is finished, anyone who reaches it can create the administrator.
- Shape
- Singleton on a replicated volume
- Reached at
- VIP on HTTP
- Node package
pkgs.jellyfin
Fetched on demand: the first time a block of this type is placed on a node, its agent fetches pkgs.jellyfin, built from the node's own nixpkgs so the NixOS binary cache serves it. That first placement needs network access (or a binary cache on the LAN) and waits for the download; later placements on that node start at once.
Example
apiVersion: expanse.io/v1 kind: Block metadata: name: media namespace: default spec: type: media/jellyfin replicas: 1 strategy: kind: SINGLETON resources: requests: cpu: "2" memory: 1Gi storage: - name: jellyfin-data size: 10Gi replication: 3 mountPath: /var/lib/jellyfin config: publishedServerUrl: https://media.example.com network: ports: - name: http port: 80 target_port: 8096 protocol: tcp expose: EXPOSE_VIP health_check: readiness: type: PROBE_TCP port: 8096 period_seconds: 2
Jellyfin refuses to start with less than 2 GiB free for its data, so size the volume above that; artwork grows with the library. Each node's /tmp needs 2 GiB free for the cache.
$ expanse ctl block apply -f jellyfin.yaml --dry-run # validate only $ expanse ctl block apply -f jellyfin.yaml
Configuration
Jellyfin always listens on 8096, so that is the target_port. Everything else (libraries, users, transcoding, plugins) is set in Jellyfin's dashboard and kept on the volume. The block owns config/database.xml and rewrites it on every start.
Keys go under spec.config and are checked against the type's JSON Schema when the block is applied. A default is what the block uses when the key is unset.
| Key | Default | Meaning |
|---|---|---|
publishedServerUrl | none | URL Jellyfin gives clients that find it by LAN discovery, such as https://media.example.com. |
Using it
Mount the media at the same path on every node that may run the block, for example an NFS export in each node's NixOS configuration, and add that path as a library in the dashboard. The block runs as an unprivileged user, so the files must be world-readable, and it cannot see /home. Jellyfin only reads the media.
For HTTPS, put a web/caddy block in front and point it at this block's VIP (expanse ctl block get media).
The unit's sandbox does not let Jellyfin list the node's network interfaces, so it logs "Error obtaining interfaces" at start. Jellyfin then counts the private ranges (10/8, 172.16/12, 192.168/16) as the LAN; if yours differs, list its subnets under Networking in the dashboard.
When a node fails
When the serving node dies, the block, its volume's primary and its VIP move together to a survivor, and Jellyfin starts there on the same volume. Streams in progress stop; the address stays the same, and apps stay signed in, because their tokens are in the database on the volume.
Nothing Jellyfin acknowledged is lost: the block configures SQLite to sync every commit, and the volume replicates each write before it completes. Settings, library definitions and artwork are flushed every 2 seconds. Jellyfin is slow to start, since it probes ffmpeg before it serves requests: in Expanse's three-node VM test, a survivor took over 58 seconds after the crash and Jellyfin answered at 135 seconds, with all 20 users created before the crash, the library and the movie.
Limits
- One Jellyfin at a time: it keeps its state in SQLite on one volume.
- No hardware transcoding: the unit cannot open the GPU, so Jellyfin transcodes on the CPU. Give it CPU, or use clients that play the media directly.
- No HTTPS inside the block; use
web/caddyin front. - The block does not serve the media; mount it on the nodes.
- Backups are separate: back up the volume with
util/restic-backup.
Source
- docs/JELLYFIN.md: the Expanse guide this page follows.
- nix/blocks/media/jellyfin: the type's identity and JSON Schema.