Upgrading and rollback

Upgrade

1. Read the release notes in the changelog for every version between yours and the new one. Each says whether the state file or any setting changes.
2. Back up the state file:

   docker compose stop jellypass
   cp -p data/grants.json data/grants.json.backup
   docker compose start jellypass

3. Set JELLYPASS_IMAGE in .env to the new version, then:

   docker compose pull
   docker compose up -d
   curl http://127.0.0.1:8787/health

Each release is published as X.Y.Z, plus X.Y and X tags that move to the newest release in that line. latest follows the main branch and may contain unreleased changes. Restarting JellyPass signs administrators out of the admin site.

Roll back

JELLYPASS_IMAGE=ghcr.io/nicklongmore86/jellypass:PREVIOUS_VERSION docker compose up -d

An upgrade can move the state file to a schema older versions can't read; then restore the backup you took before upgrading. If you use the household app, check the admin-only GET /v1/app/outstanding first and roll back only once it answers "clear": true; the changelog explains how to drain it.

Backup and restore

The state file is the only data JellyPass needs to keep. Back up Jellyfin separately: JellyPass is not a backup of Jellyfin's users or policies. To restore, stop JellyPass, put the backup in place (owned by UID 1000), start it, then preview and apply a reconciliation in Grants.

Jellyfin versions

JellyPass supports the current Jellyfin release and the one before it: Jellyfin 12.x and 10.11.x. It reads Jellyfin's version at startup and every five minutes. From 3.10.0, any other version (an older 10.x, a future 13.0, or any build whose version has a suffix, such as 12.5.0-rc1) is unconfirmed until an administrator confirms it. On an unconfirmed version:

• in JellyPass 3.x, household addresses keep serving as before;
• JellyPass logs a warning once for each version, the admin site shows a notice that this is not a tested Jellyfin version, and GET /v1/jellyfin/version reports "confirmation": "unconfirmed" and "enforcement": "warn";
• an administrator confirms that exact version with Allow Jellyfin X in the admin site, or with JELLYFIN_UNTESTED_VERSION_OK, which clears the warning. Confirm a version only once you are satisfied JellyPass's household privacy checks hold on it, since they were written for the supported versions. A later upgrade to another untested version warns again.

While JellyPass can't read the version (Jellyfin unreachable at startup, or its last read failed), there is nothing to confirm: in 3.x household addresses keep serving, JellyPass logs a warning for each failed read and tries again every 30 seconds, the admin site shows that the version can't be read, and GET /v1/jellyfin/version reports "version": null and "confirmation": null (with "enforcement": "warn" and the last error).

JellyPass 4.0.0 will refuse household requests on an unconfirmed version: household addresses will answer 503 and pass nothing to Jellyfin until that exact version is confirmed, and also while the version can't be read. The admin site, webhooks and grants keep working either way.

Check JellyPass's release notes before upgrading Jellyfin to a new major version.

Coming in 4.0

JellyPass 4.0 is in development and will be a breaking release, including moving the admin site to a listener of its own. It will come with upgrade notes; these pages describe 3.x.

Edit this page on GitHub