Hands-on Lab

Upgrade Jellyfin from 10.11 to 12 in Docker with a Backup and Rollback

October 21, 2026 3 min

0 / 9

Cheat sheet

Found it useful? Don't miss the next lab

The video has captions and a transcript. Everything it shows is written out, step by step, below. Cheat sheet with every command

0:00 / 0:00

We create compose.yaml with the jellyfin/jellyfin:10.11.11 tag pinned and user 1000:1000 so the server does not run as root. We publish port 8096 for the web UI and the API, and mount the /srv/media library read-only. The config and the database live in the jellyfin-config volume: that is the only thing to copy before upgrading.

mkdir -p ~/jellyfin /srv/media && cd ~/jellyfin && cat > compose.yaml <<'EOF'
services:
  jellyfin:
    image: jellyfin/jellyfin:10.11.11
    container_name: jellyfin
    user: 1000:1000
    ports:
      - "8096:8096/tcp"
      - "7359:7359/udp"
    volumes:
      - jellyfin-config:/config
      - jellyfin-cache:/cache
      - type: bind
        source: /srv/media
        target: /media
        read_only: true
    restart: unless-stopped
volumes:
  jellyfin-config:
    name: jellyfin-config
  jellyfin-cache:
    name: jellyfin-cache
EOF
echo "compose.yaml written: $(wc -l < compose.yaml) lines"

I did it

We confirm Compose parses the file without errors and that the image and both volumes are the ones we expect, before starting anything.

cd ~/jellyfin && docker compose config --images && docker compose config --volumes

What this proves

jellyfin/jellyfin:10.11.11 the pinned image is 10.11.11 Goal · you start from a version the jump to 12.0 supports
jellyfin-config there is a named volume for /config Goal · you know which volume to copy before upgrading

docker compose up -d pulls the image and starts the container in the background. The loop checks the log every 2 s, up to 60 times, until it sees Startup complete, and then requires /System/Info/Public to answer without an error. We save the server Id, which lives in the config volume, to prove later that 12.0 starts on the same data.

cd ~/jellyfin && docker compose up -d --quiet-pull && for i in $(seq 1 60); do docker compose logs jellyfin | grep -q 'Startup complete' && break; sleep 2; done; curl -sf http://localhost:8096/System/Info/Public >/dev/null && echo "Startup complete, API answering (attempt $i)" && curl -s http://localhost:8096/System/Info/Public | jq -r .Id > server-id.txt

I did it

We read the real version with curl and jq from /System/Info/Public, which needs no authentication. It is the check the guide asks for before upgrading: the direct jump to 12.0 is only supported from 10.10.7 or any 10.11.x.

curl -s http://localhost:8096/System/Info/Public | jq -r '"product: \(.ProductName)", "version: \(.Version)"'

What this proves

version: 10.11.11 the running server is 10.11.11 Goal · you confirm from the API that you can jump straight to 12.0

First we stop the service so the database cannot change during the copy. Then an alpine:3 container with --rm mounts jellyfin-config read-only (:ro) and the current folder at /backup, and tar writes jellyfin-config.tar.gz. It is the guide's command for named volumes.

cd ~/jellyfin && docker compose stop jellyfin && docker run --rm -v jellyfin-config:/config:ro -v "$PWD":/backup alpine:3 tar -czf /backup/jellyfin-config.tar.gz -C / config

I did it

We confirm Jellyfin was stopped during the copy. The archive holds what matters: the config/data/jellyfin.db database, which 12.0 is about to rewrite, and the server settings in system.xml.

cd ~/jellyfin && docker compose ps -a --format '{{.Name}} {{.State}}' && ls -lh jellyfin-config.tar.gz | awk '{print $5, $9}' && tar -tzf jellyfin-config.tar.gz | grep -E 'jellyfin.db$|system.xml$'

What this proves

jellyfin exited the container was stopped when the copy was taken Goal · you know the copy is consistent and can take you back
config/data/jellyfin.db the database is inside the tar.gz Goal · you have safe exactly what the migration will change

We pin 12.0 rather than latest, so a future 13.0 cannot arrive without a backup first. docker compose pull downloads the image before anything else stops, so download time does not count as downtime.

cd ~/jellyfin && sed -i 's#jellyfin/jellyfin:10.11.11#jellyfin/jellyfin:12.0#' compose.yaml && docker compose pull --quiet jellyfin && echo pulled

I did it

We confirm the change in the file and that both images are downloaded. Keeping 10.11.11 locally is part of the rollback plan.

cd ~/jellyfin && grep 'image:' compose.yaml && docker image ls jellyfin/jellyfin --format '{{.Repository}}:{{.Tag}}'

What this proves

image: jellyfin/jellyfin:12.0 the service now uses the 12.0 tag Goal · the next start will run the new version
jellyfin/jellyfin:10.11.11 the previous image is still local Goal · you can go back to 10.11.11 without downloading anything

docker compose run --rm starts a one-off container with the 12.0 image on the same volume and passes it --mode MigrateSystem. grep keeps the lines that matter: how many migrations each stage has and whether they were applied. The step is optional, since the server migrates on startup anyway, but this way the result does not get lost in the rest of the log.

cd ~/jellyfin && docker compose run --rm jellyfin --mode MigrateSystem 2>&1 | grep -E 'migrations for stage|Migrations have been|FTL' | sed 's/Jellyfin.Server.Migrations.//'

I did it

Because MigrateSystem exits 0 even when it fails, we read the log Jellyfin left in /config/log, mounted read-only from another alpine container. The phrase Migrations have been applied and zero FTL lines are the signal that the database is now in the 12.0 format.

docker run --rm -v jellyfin-config:/config:ro alpine:3 sh -c 'grep -ho "Migrations have been applied" /config/log/*.log | tail -1; echo "FTL lines: $(cat /config/log/*.log | grep -c "\[FTL\]")"'

What this proves

Migrations have been applied the migrations finished Goal · you know the database is now in the new format
FTL lines: 0 the log has no fatal errors Goal · you rule out a failed migration before starting the server

Compose recreates the container with the 12.0 image on the already migrated volume. The ready signal is not the container showing Up, but the Startup complete log line followed by a successful answer from /System/Info/Public, which curl -f checks.

cd ~/jellyfin && docker compose up -d && for i in $(seq 1 60); do docker compose logs jellyfin | grep -q 'Startup complete' && break; sleep 2; done; curl -sf http://localhost:8096/System/Info/Public >/dev/null && echo "Startup complete, API answering (attempt $i)"

I did it

We read the version from the same endpoint as before and compare the server Id with the one we saved on 10.11.11. A match proves 12.0 started on the migrated config and not on a fresh server. /health completes the check.

cd ~/jellyfin && curl -s http://localhost:8096/System/Info/Public | jq -r --arg id "$(cat server-id.txt)" '"version: \(.Version)", "same server Id: \(.Id == $id)"' && echo "health: $(curl -s http://localhost:8096/health)"

What this proves

version: 12.0.0 the server identifies itself as 12.0.0 Goal · you prove the upgrade through the API, without opening a browser
same server Id: true the Id matches the one from 10.11.11 Goal · you know 12.0 runs on your existing data
health: Healthy the health endpoint answers Healthy Goal · the server is ready for the full library scan

We change the tag back to 10.11.11 and recreate the container on the volume 12.0 already migrated. We wait for the Startup complete line in the log, with the same 60-attempt limit, to see what the old server does with new data.

cd ~/jellyfin && sed -i 's#jellyfin/jellyfin:12.0#jellyfin/jellyfin:10.11.11#' compose.yaml && docker compose up -d && for i in $(seq 1 60); do docker compose logs jellyfin | grep -q 'Startup complete' && break; sleep 2; done; echo "Startup complete on attempt $i"

I did it

A monitor that only looks at /health or the container state would say everything is fine. The log tells a different story: [FTL] An error occurred starting the application, because 10.11.11 cannot find the schema it expects in the database. This is why you take the backup with the server stopped.

cd ~/jellyfin && curl -s http://localhost:8096/System/Info/Public | jq -r '"version: \(.Version)"' && echo "health: $(curl -s http://localhost:8096/health)" && docker compose logs --no-log-prefix jellyfin | grep -m1 '\[FTL\]' | cut -d' ' -f2,4-

What this proves

health: Healthy the health endpoint still answers Healthy Goal · you see why a health monitor misses this failure
An error occurred starting the application the log holds a fatal startup error Goal · you know that changing the tag alone is not a rollback

docker compose down removes the container but keeps the named volumes. The alpine container mounts jellyfin-config with write access, deletes the migrated data and extracts the backup in its place. The tag is already 10.11.11, so the next up starts the previous version on the previous data.

cd ~/jellyfin && docker compose down && docker run --rm -v jellyfin-config:/config -v "$PWD":/backup alpine:3 sh -c 'rm -rf /config/* && tar -xzf /backup/jellyfin-config.tar.gz -C /' && docker compose up -d && for i in $(seq 1 60); do docker compose logs jellyfin | grep -q 'Startup complete' && break; sleep 2; done; echo "Startup complete on attempt $i"

I did it

We check the version, that the Id is still the original one, and that the new container's log has no FTL line. With the backup restored, 10.11.11 starts clean: that is the rollback that works.

cd ~/jellyfin && curl -s http://localhost:8096/System/Info/Public | jq -r --arg id "$(cat server-id.txt)" '"version: \(.Version)", "same server Id: \(.Id == $id)"' && echo "FTL lines: $(docker compose logs jellyfin | grep -c '\[FTL\]')"

What this proves

version: 10.11.11 the server is back on 10.11.11 Goal · you have a tested rollback, not an assumed one
FTL lines: 0 the startup has no fatal errors Goal · you tell a good restore apart from the false healthy of the previous step

With -v, docker compose down also removes the named volumes declared in the compose file. You would not do this on a real server: here the lab is disposable and we do not want to leave data behind.

cd ~/jellyfin && docker compose down -v

I did it

We count the containers and volumes whose name contains jellyfin. Both counters at zero confirm the lab leaves nothing behind.

echo "jellyfin containers: $(docker ps -aq --filter name=jellyfin | wc -l)"; echo "jellyfin volumes: $(docker volume ls -q --filter name=jellyfin | wc -l)"

What this proves

jellyfin containers: 0 no container is left Goal · you leave the machine as it was
jellyfin volumes: 0 no volume is left Goal · no lab data is left using disk space

Was this lab useful? Rate it:

Click to rate this post!

[Total: 0 Average: 0]

Video transcript

0:00 Jellyfin 10.11 to 12.0 in Docker, with a way back.
0:06 We write the guide's compose file, with Jellyfin 10.11.11 pinned and two named
0:12 volumes, for the config and the cache.
0:14 Jellyfin from 10.11.11 to 12.0 in Docker, with a backup and a
0:21 tested rollback.
0:22 12.0 rewrites the database on first start, and 10.11 can no longer read it.
0:29 Version, backup, tag, migration, test and restore.
0:34 Compose validates the file:
0:36 image 10.11.11, volumes jellyfin-config and jellyfin-cache.
0:43 We start 10.11.11, wait for Startup complete and the API, and save
0:49 the server ID to compare it later.
0:52 The public API answers without logging in:
0:56 version 10.11.11, a supported starting point.
1:01 The backup that lets you go back is a file copy, taken with the server stopped.
1:05 We stop Jellyfin, and a throwaway alpine container packs the config volume into a
1:10 tar.gz.
1:13 The container is stopped and the tar.gz holds the jellyfin.db database and the
1:19 system.xml file.
1:23 We change the image tag from 10.11.11 to 12.0 with sed and
1:29 pull the new image.
1:30 The compose file points at 12.0, and we keep 10.11.11 locally to go
1:36 back.
1:40 MigrateSystem applies the migrations and exits, without starting the server.
1:45 We run only the migration:
1:47 18 CoreInitialisation migrations, 13 AppInitialisation ones, and the log says
1:53 they have been applied.
1:54 The log in the volume confirms the migration, with zero FTL lines.
2:03 We start 12.0 and wait, with the same loop, for Startup complete and the API.
2:10 The same query now returns 12.0.0, with the same server ID, and health says
2:16 Healthy.
2:20 Changing only the tag is not enough:
2:23 10.11.11 cannot read the migrated database.
2:27 We try the mistake the guide describes:
2:29 going back to the 10.11.11 tag without restoring the backup.
2:35 The danger:
2:36 the API says 10.11.11 and health says Healthy, but the log holds a fatal
2:42 startup error.
2:44 The proper rollback:
2:45 we take the service down, restore the tar.gz into the volume with alpine and
2:50 start 10.11.11.
2:54 10.11.11 is back with the same server ID and zero FTL lines.
3:02 docker compose down with -v removes the container and the volumes.
3:09 No Jellyfin container or volume is left.

This lab reproduces, on a disposable machine, the guide how to upgrade Jellyfin 12 with Docker and keep a way back: you start from 10.11.11 installed as in the guide to installing Jellyfin with Docker, copy the config volume, jump to 12.0 and test the rollback. Everything you see in the terminal really ran, with the official jellyfin/jellyfin:10.11.11 and jellyfin/jellyfin:12.0 images.

Why you copy /config before you upgrade Jellyfin 12

12.0 rewrites the database on its first start, and the Jellyfin backup and restore documentation is clear about it: there is no downgrade mechanism. In the official image, data and config live together under /config, so that folder is the only thing you need to keep. The 12.0 release notes only support the direct jump from 10.10.7 or any 10.11.x.

How to back up a named volume

With Jellyfin stopped, a throwaway alpine:3 container mounts the jellyfin-config volume read-only and packs it with tar. It is the same pattern as the Docker volume backup and restore lab, and the article on Docker volumes and bind mounts explains the difference between volumes and bind-mounted folders. The Docker documentation on volumes describes the same technique.

What the lab’s rollback proves

Going back to the 10.11.11 tag without restoring the backup leaves a server that answers Healthy on /health and reports its version through the API, but whose log holds a fatal startup error. Restoring the tar.gz and starting 10.11.11 gives a log with no FTL lines and the same server ID. If you run Jellyfin on the latest tag, also read the article on Watchtower for automatic Docker updates: the official image on Docker Hub moves latest to 12.0, and an automatic update migrates with no backup first.

The lab does not cover the full library scan or third-party plugins, because the machine has no library and no users. Those steps, with their measured times, are in the written guide.

FAQ

Can I go back to Jellyfin 10.11 just by changing the image tag?

No. In this lab, 10.11.11 started on already migrated data answered Healthy on /health and reported its version through the API, but its log held a fatal error while starting the application. You have to restore the /config backup taken before migrating.

How do I check the Jellyfin version without logging in?

Query /System/Info/Public, which needs no authentication: curl -s http://localhost:8096/System/Info/Public | jq -r .Version. In the lab it returned 10.11.11 before the upgrade and 12.0.0 after it.

How do I back up if I use named volumes?

Stop Jellyfin and mount the volume in a helper container: docker run –rm -v jellyfin-config:/config:ro -v "$PWD":/backup alpine:3 tar -czf /backup/jellyfin-config.tar.gz -C / config. The restore is the same idea in reverse, with the volume mounted writable.

Do I need to run –mode MigrateSystem before starting 12.0?

No, the server migrates on startup anyway. Running it separately lets you read the result: in the lab it announced 18 CoreInitialisation migrations and 13 AppInitialisation ones. Since it exits 0 even when it fails, check that the log says Migrations have been applied and has no FTL lines.

Cheat sheet

mkdir -p ~/jellyfin /srv/media && cd ~/jellyfin && cat > compose.yaml <<'EOF'
services:
  jellyfin:
    image: jellyfin/jellyfin:10.11.11
    container_name: jellyfin
    user: 1000:1000
    ports:
      - "8096:8096/tcp"
      - "7359:7359/udp"
    volumes:
      - jellyfin-config:/config
      - jellyfin-cache:/cache
      - type: bind
        source: /srv/media
        target: /media
        read_only: true
    restart: unless-stopped
volumes:
  jellyfin-config:
    name: jellyfin-config
  jellyfin-cache:
    name: jellyfin-cache
EOF
echo "compose.yaml written: $(wc -l < compose.yaml) lines"

cd ~/jellyfin && docker compose up -d --quiet-pull && for i in $(seq 1 60); do docker compose logs jellyfin | grep -q 'Startup complete' && break; sleep 2; done; curl -sf http://localhost:8096/System/Info/Public >/dev/null && echo "Startup complete, API answering (attempt $i)" && curl -s http://localhost:8096/System/Info/Public | jq -r .Id > server-id.txt

cd ~/jellyfin && docker compose stop jellyfin && docker run --rm -v jellyfin-config:/config:ro -v "$PWD":/backup alpine:3 tar -czf /backup/jellyfin-config.tar.gz -C / config

cd ~/jellyfin && sed -i 's#jellyfin/jellyfin:10.11.11#jellyfin/jellyfin:12.0#' compose.yaml && docker compose pull --quiet jellyfin && echo pulled

cd ~/jellyfin && docker compose run --rm jellyfin --mode MigrateSystem 2>&1 | grep -E 'migrations for stage|Migrations have been|FTL' | sed 's/Jellyfin.Server.Migrations.//'

cd ~/jellyfin && docker compose up -d && for i in $(seq 1 60); do docker compose logs jellyfin | grep -q 'Startup complete' && break; sleep 2; done; curl -sf http://localhost:8096/System/Info/Public >/dev/null && echo "Startup complete, API answering (attempt $i)"

cd ~/jellyfin && sed -i 's#jellyfin/jellyfin:12.0#jellyfin/jellyfin:10.11.11#' compose.yaml && docker compose up -d && for i in $(seq 1 60); do docker compose logs jellyfin | grep -q 'Startup complete' && break; sleep 2; done; echo "Startup complete on attempt $i"

cd ~/jellyfin && docker compose down && docker run --rm -v jellyfin-config:/config -v "$PWD":/backup alpine:3 sh -c 'rm -rf /config/* && tar -xzf /backup/jellyfin-config.tar.gz -C /' && docker compose up -d && for i in $(seq 1 60); do docker compose logs jellyfin | grep -q 'Startup complete' && break; sleep 2; done; echo "Startup complete on attempt $i"

```
cd ~/jellyfin && docker compose down -v
```

Found it useful? Don't miss the next lab

Subscribe to the newsletter

Why you copy /config before you upgrade Jellyfin 12

How to back up a named volume

What the lab’s rollback proves

FAQ

Can I go back to Jellyfin 10.11 just by changing the image tag?

How do I check the Jellyfin version without logging in?

How do I back up if I use named volumes?

Do I need to run –mode MigrateSystem before starting 12.0?

Cheat sheet