Skip to content
SHC Docs

Jellyfin

Jellyfin is a free-software media system. The SHC package runs the official jellyfin/jellyfin image with:

  • jellyfin-config: the instance’s whole identity, meaning the library database, users, playlists, plugins, server keys. Backed up.
  • jellyfin-cache: transcode / image / subtitle cache. Regenerable, not backed up.
  • the media library at /media, read-only: a data volume named for mediaHostPath (host-srv-jellyfin-media by default), created empty. SHC never opens a host path into a container. Kept out of SHC backups (it is typically TB-scale), so back it up out of band; a move carries it and a delete warns, because a volume a host path names is critical.
Terminal window
shc install jellyfin -t <tenant> --stack media --var mediaHostPath=/srv/media \
--expose media.example.com

<tenant> is your tenant (Tenants). --expose gives Jellyfin its web address, where you open the setup wizard; without it the server runs with no address.

Common variables:

  • mediaHostPath: the path that names the library’s data volume, mounted read-only at /media. /srv/media names host-srv-media.
  • hwAcceleration: none (default) | vaapi (maps /dev/dri) | nvenc (needs the NVIDIA Container Toolkit on the host).
  • publicUrl: what Jellyfin advertises to LAN auto-discovery. Empty lets it use the request URL, which is right behind most reverse proxies.
  • adminUser / adminPassword: Jellyfin has no programmatic admin-create path, so these are not seeded. They exist so the password is generated into the vault; you paste it into the first-boot setup wizard yourself.

The admin password is retrievable with shc vault get against the deployment scope, the same as any other autogenerated secret.

The library volume starts empty. Mount it writable on the node that runs the deployment, copy your media in, then release the mount:

Terminal window
shc volume mount host-srv-media -s media --read-write
rsync -a /path/to/your/films/ <the path it printed>/
shc volume umount <the handle it printed>

Jellyfin reads /media read-only and picks the files up on its next library scan.


Read this before updating a deployment that is on 10.10. Everything below was rehearsed live on 2026-08-03 against a seeded library; the observed behaviour is quoted, not predicted.

10.11 rewrites the library out of the legacy raw-SQLite library.db into the EF-Core-managed jellyfin.db, then renames the old file to library.db.old.

  • It is one way. There is no downgrade. library.db.old exists so a failed migration can be retried; it is not a supported way back to 10.10.
  • It runs unattended on first boot, for minutes to hours. Upstream’s own number: 300,000 well-formed entries can migrate in minutes, while 30 series with severe inconsistencies can take multiple hours.
  • Do not restart the container mid-migration and do not roll the image back mid-migration. That is the one action that turns a slow upgrade into a broken library.
  • The source version must be 10.10.7. Other 10.10.x releases are documented by upstream as “will fail”; reach 10.10.7 first.
  • 10.11 also drops ARM32 (armhf) entirely and deprecates the internal TLS listener (slated for removal in the next major). Terminate TLS at the proxy.

Four things in apps/standalone/jellyfin/: two start jobs that run with the old server stopped, and two settings in compose.yaml.

1. jellyfin-wal-checkpoint: recovers the write-ahead log the migration would otherwise drop.

10.10.7 keeps library.db in WAL mode and does not checkpoint it at shutdown. A graceful stop checkpoints jellyfin.db and leaves library.db-wal whole. Measured on a seeded library after docker stop:

filesize
data/jellyfin.db180224 (its -wal gone)
data/library.db4096
data/library.db-shm32768
data/library.db-wal1396712

That 4 KB library.db contains zero tables. Opened without its sidecar, select name from sqlite_master returns nothing: schema, rows and watched state all live in the log.

A 10.11 rung whose MigrateLibraryDb reads only the main file therefore migrates an empty database and reports success. Reproduced end-to-end on 10.11.6 through this package: the gate archived /config and exited 0, the migration logged Migration 20241020103111_LibraryDbMigration was successfully applied, library.db.old came out at 4096 bytes with the 1.4 MB WAL left orphaned beside it, and the server served "startupWizardCompleted": false: a fresh install where a library, a user and its watched state had been.

Upstream fixed this in 10.11.7 (the shipped jellyfin.dll carries a wal_checkpoint string from .7 onward and none in .0 through .6) and the pin is past it, so this start job is not what saves the pinned rung. It is what stops the packaging depending on which rung is pinned: images.jellyfin is an ordinary var, and --var images.jellyfin=…10.11.6… is one flag away.

It runs before the gate, decides on the same two discriminators (no legacy library.db, or a non-migrating target → one line and exit 0), runs PRAGMA wal_checkpoint(TRUNCATE), and then checks the file rather than trusting the return value: the PRAGMA does not raise when it cannot get the lock, it returns busy=1 and leaves the log whole. A non-empty library.db-wal afterwards is a non-zero exit and the new version never starts.

It is the only container in the package that can write /config, and it is deliberately not given the archive volume: the container that can write the library cannot touch the rollback artifact, and vice versa.

2. jellyfin-upgrade-gate: a start job that runs before jellyfin starts.

A start job is the mechanism in an app package that can refuse an operation: both jobs name before: [jellyfin:stopped], so on an update the old server stops, the jobs run, and the new version starts only once both ended 0. A non-zero exit fails the update and starts the old server again as it was. (App hooks: cannot do this: the runner discards a pre-hook’s error, and its halt marker only ends the hook sequence, not the deploy.)

On every deploy it decides in this order:

  • no /config/data/library.db → nothing to migrate (a fresh install, or a deployment already on the EF-Core schema) → prints one line, exits 0;
  • target tag is 10.10 or older → no migration → exits 0;
  • otherwise the target migrates: it prints the warning above, then archives /config to the jellyfin-preupgrade volume as config-pre-ef-core-<UTC timestamp>.tar.gz and exits 0. If it cannot write that archive it exits non-zero and the new version never starts.

An archive already present is kept, never overwritten (the older one was taken against a library nothing had half-migrated yet), and its name tells you when it was taken.

--var preUpgradeBackup=skip keeps the warning but takes no archive, for operators who hold their own /config backup. It asserts something SHC cannot verify, so it is not the default.

The archive is a real artifact, not a receipt: in the rehearsal the extracted data/library.db opened cleanly and held all six seeded titles.

It is taken after the checkpoint, deliberately. wal_checkpoint(TRUNCATE) is crash-safe (an interrupted one leaves the log whole and SQLite replays it on the next open), so running it first opens no unrecoverable window, and what it buys is an archive whose library.db is self-contained rather than a 4 KB shell plus a 1.4 MB sidecar. Verified: the archive taken this way was extracted into a fresh /config, started under 10.10.7, and served the movie, the user and its watched/favourite state from a single 188 KB library.db with no sidecar present.

3. A readiness probe that is not fooled by the loading placeholder.

10.11 serves a placeholder while it initialises, and that placeholder answers /System/Info/Public (the obvious readiness endpoint, and the one this package used to healthcheck) with 200 less than a second after the container starts (first a camelCase body, then the plain text Jellyfin Server is loading. Please wait.). Measured on 10.11.11 from an empty /config:

t/System/Info/Public/Users/Public/web/index.html/health
+0.6s200 (placeholder)503503200
+2.4s200 (…is loading)503200503
+8.2s200 (real document)200200200

Left alone, that means the deploy reports success while the one-way migration is still running, and an operator looking at a still-loading UI restarts the container. The healthcheck therefore probes /Users/Public, which is 503 for the whole loading window and 200 exactly when the server is serving, on both 10.10.7 and 10.11.11.

4. A healthcheck window sized against the deploy, not against a boot.

start_period is 900s with 10×30s retries. During start_period docker reports health: starting, and SHC maps (running, starting) to the deployment status starting, not degraded. The unhealthy verdict therefore lands at 1200s, past the 900s timeouts.compose_converge budget that bounds docker compose up --wait, so a still-migrating deploy expires as a timeout rather than being marked FAILED. That distinction matters: SHC does not roll back an update, so a timeout leaves the migration running, while an unhealthy verdict is the thing that makes an operator reach for a rollback.

If your library needs longer than the converge budget, that budget is global config (timeouts.compose_converge), not an app knob; raise it before the hop, or accept the timeout and wait the migration out.

Terminal window
# 1. Be on 10.10.7, and take a backup you can name later.
shc -s media backup create
shc -s media backup ls # write the ID down: you will need it
# 2. Update. The gate prints the warning and takes its own /config archive.
shc update media

While it runs: shc logs media -f. A deploy that times out is not a failure: check the log, confirm the migration is still progressing, and wait.

Verified live. The order is not interchangeable:

Terminal window
# 1. Put the pin back on the 10.10 rung FIRST.
shc update media --var images.jellyfin=jellyfin/jellyfin:10.10.7@sha256:7ae36aab93ef9b6aaff02b37f8bb23df84bb2d7a3f6054ec8fc466072a648ce2
# 2. Replay the PRE-HOP backup, BY ID.
shc backup restore --id <the id from step 1 above> --stack media --yes

Three things that will otherwise bite you:

  • Step 1 will report the deploy failed, and that is expected. 10.10.7 cannot read a migrated /config: it dies with SQLite Error 1: 'no such column: u.MaxParentalAgeRating' and crash-loops until step 2 replaces the data. Keep going.
  • Do not restore first. A restore restarts the deployment, and a 10.11 image that finds a restored legacy library.db simply migrates it again.
  • Name the backup ID. --before 0m means “the newest backup”, and every restore takes its own pre-restore safety backup first, so a second attempt with --before 0m restores the broken state you were trying to escape. (Observed exactly that in rehearsal.)

A restore replays mount data. It does not rewind the image pin, which is why step 1 exists.

The update fails on the start job jellyfin-upgrade-gate exiting 1, and the gate’s own log names the cause and the remedy. Nothing was migrated: /config still holds the legacy library.db, and the old server starts again as it was. Free the space (or fix the mount), re-run shc update, and the gate archives and lets jellyfin through. --var preUpgradeBackup=skip is the deliberate override.

The gate’s own config-pre-ef-core-*.tar.gz is the fallback for when the platform backup is gone: it lives under the deployment’s mounts/jellyfin-preupgrade/, and unpacking it over mounts/jellyfin-config/ with the stack stopped puts the legacy /config back by hand.

jellyfin-config rides the regular per-mount snapshot. Consistency comes from the capture, not from a WAL checkpoint: the whole /config tree is archived, so library.db-wal and library.db-shm are in the archive beside library.db, and the container is quiesced (paused) for the capture. A frozen writer plus all three files is a crash-consistent set that SQLite replays on open.

No WAL checkpoint is performed for backups. (The upgrade path is a different window and does checkpoint; see jellyfin-wal-checkpoint above. That start job runs in its own image with the server stopped and only when a legacy library.db is about to be migrated; it protects a one-way schema rewrite, not a snapshot.) The jellyfin-flush-sqlite job is wired at pre_backup and pre_update, but the pinned image ships libsqlite3.so.0 for .NET and no sqlite3 CLI (command -v sqlite3 exits 127 on the pinned digest), so there is nothing for it to run. It reports that absence on stderr every run and names the databases it left alone; it used to print jellyfin sqlite WAL checkpoint done unconditionally while doing nothing. It stays wired so it starts working by itself if a future pin ships the CLI (the app’s test suite fails on that pin change on purpose, so the choice gets re-made rather than drifting). Nothing in the backup guarantee depends on it.

jellyfin-preupgrade is excluded from backups: it is a copy of a mount the backup already carries.

The media library is never in a backup. That is deliberate; see Overview.