Upgrade to Jellyfin 12.2: install medialab Server with Docker Compose or apt

Why switch now

If you run Jellyfin on your own hardware, you have probably been watching the 12.2 release. medialab Server is our variant of Jellyfin 12.2: the same libraries, users and apps, with our verified plugins built in and MediaLab TV included. It is free software under the GPL-2.0, with no license key and public source code.

This is not a migration. The Jellyfin apps for Android, iOS, TV and the web connect exactly as they do to official Jellyfin. What changes is the home your plugins live in: our catalog is added automatically, our plugins show Verified – medialab and come first among Live TV tuners, guide sources and subtitle providers, and you can reorder that list whenever you like.

Below are two ways in — a jellyfin docker compose stack and the apt packages on Debian 12 — plus the one thing you must do first: a backup.

Before you start: the one-way door

At the first start, the Jellyfin database is upgraded to the 12.2 format. An older Jellyfin cannot open that database again. There is no downgrade path for the data itself, so treat this as a one-way upgrade.

So, before anything else:

• Make a backup of the settings and data. For a container setup that means the whole /config folder; for apt that means /etc/jellyfin and /var/lib/jellyfin.
• Keep the backup somewhere the server cannot touch, and note which Jellyfin version you were running.
• If you have users whose names differ only by case, check them before the upgrade. The documentation calls this out as a point to verify before switching.

Do that, and the rest is routine.

Prerequisites

• A 64-bit x86 or ARM machine. Ubuntu is fine for the container.
• For the container route: Docker (or Podman, Unraid, Portainer, Kubernetes), a folder for /config, one for /cache, your media folder, and the numeric PUID/PGID of the account that should own the settings (id -u, id -g).
• For the apt route: Debian 12 (bookworm), amd64 or arm64. The packages need Debian 12 libraries, so they do not install on Ubuntu — use the container there.
• Your existing Jellyfin data, backed up.

Step 1: Install with Docker Compose

The image is ghcr.io/cristiancasapu/medialab-server, built for linux/amd64 and linux/arm64 from the same signed Debian packages as the apt repository.

Create a compose.yaml:

services:
  medialab-server:
    image: ghcr.io/cristiancasapu/medialab-server:12.2-ml.10
    container_name: medialab-server
    restart: unless-stopped
    ports:
      - "8096:8096"
      - "7359:7359/udp"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /srv/media:/media:ro
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Europe/Bucharest
      MLW_SERVER_NAME: Home media
      MLW_ADMIN_USER: admin
      MLW_ADMIN_PASSWORD_FILE: /run/secrets/admin_password
    secrets:
      - admin_password

secrets:
  admin_password:
    file: ./secrets/admin_password

Then:

mkdir -p secrets && printf '%s' 'a-long-password' > secrets/admin_password
docker compose up -d
docker compose logs -f

A few notes on the tags: 12.2-ml.10 pins one release (recommended if you want to choose when to update), 12.2 follows the newest 12.2 release and latest the newest release overall. The 12.2-ml10-deb12 tag names the exact apt version inside the image.

The admin variables only work on a new server; on one that is already set up they are ignored. The password never appears in the container logs, which is why it goes in a file rather than on the command line. A complete example with an .env file lives in the repository (examples/compose.yaml, examples/.env.example).

On Unraid, add a container and set the template URL to the medialab-server.xml file in the repository's examples/unraid/ folder (or copy it to /boot/config/plugins/dockerMan/templates-user/), check that /config points at /mnt/user/appdata/medialab-server and /media at your media share, use PUID 99 and PGID 100, and add --device=/dev/dri to Extra Parameters if you have an Intel or AMD GPU. Portainer and Kubernetes work with the same image and volumes.

Step 2: Install with apt on Debian 12

The packages come from https://apt.medialab.works/debian. First add the repository, which ships as a signed package:

curl -fsSLO https://apt.medialab.works/medialab-repo.deb
sudo apt install ./medialab-repo.deb

That creates /etc/apt/sources.list.d/medialab.sources and installs the signing key. If you prefer to do it by hand, download the key to /usr/share/keyrings/medialab-archive-keyring.gpg and check the fingerprint: it must be 6B7D 46D8 2C3C 4D4C 0A14 2F92 4189 96EB 3CE1 59C7, for "medialab Server packages packages@medialab.works". Then write the same medialab.sources file. apt checks the signature on every apt update.

Install:

sudo apt update
sudo apt install medialab-server medialab-server-web jellyfin-ffmpeg8

medialab-server replaces jellyfin-server and medialab-server-web replaces jellyfin-web. If Jellyfin is already installed from Jellyfin's repository, apt removes those two packages and keeps your data, because medialab Server uses the same folders. If Jellyfin's repository is still configured, apt keeps the medialab packages installed; you can remove the old repository when you no longer need it.

The server runs as the usual jellyfin service under the jellyfin user:

sudo systemctl status jellyfin
sudo systemctl restart jellyfin
sudo journalctl -u jellyfin -f

The paths are the familiar ones: /etc/jellyfin for settings, /var/lib/jellyfin for database, plugins and metadata, /var/log/jellyfin, /var/cache/jellyfin, /etc/default/jellyfin for start-up options, /usr/share/jellyfin/web for the web interface and /usr/lib/jellyfin-ffmpeg/ffmpeg. To change the service user or other systemd options, use sudo systemctl edit jellyfin. For hardware transcoding on an Intel or AMD GPU, the package adds the jellyfin user to the render and video groups.

Step 3: First start and checks

Open http://<server>:8096. On a fresh server the setup wizard asks for the first administrator, the language and your libraries from /media. On an existing one, your data is already there — so walk through it:

• Libraries: paths still resolve and scans complete.
• Users: everyone can log in, and no two names differ only by case.
• Plugins: our catalog is added by itself and our plugins show Verified – medialab; the server checks their signatures and flags a plugin changed after publishing.
• Hardware acceleration: confirm transcoding works, and that the render/video groups (apt) or /dev/dri (container) are in place.

MediaLab TV, included

Since 12.2-ml.8 the TV app is part of the server, free — no plugin and no separate subscription. On a TV without a Jellyfin app, open https://<server>:8096/web/tv/, or use the MediaLab TV entry in the users' menu, and you get the Netflix-style interface: Continue Watching, Next Up, libraries, My List, live TV, title pages, search with an on-screen keyboard and profiles, with its own player for audio tracks, subtitles, resume and Skip intro / recap / credits.

Settings live in the users' menu under MediaLab TV – admin: name, logo (PNG/SVG), colors, language, access path and Turnstile. If you had the jf-tvapp plugin installed, the server takes over its settings, logo and Turnstile key and no longer loads the plugin; the same addresses keep working. On official Jellyfin, MediaLab TV remains the jf-tvapp plugin.

Updating and going back

• Container: pull the new 12.2-ml.N tag and recreate the container; the settings in /config stay.
• apt: sudo apt update && sudo apt upgrade, or use the Self-Update plugin from the web interface.

Every release is listed in the changelog. To return to official Jellyfin, reinstall its packages or image against the same data — but remember the database is already in 12.2 format, so you need an official Jellyfin that can open it. That is exactly why the backup comes first.

Tips and troubleshooting

• Keep the backup until you are happy. The database upgrade is one-way; a copy of /config (or /etc/jellyfin plus /var/lib/jellyfin) is your only way back.
• Ubuntu and apt don't mix here. The packages need Debian 12 libraries; on Ubuntu, use the container image.
• Logs first. docker compose logs -f for containers, sudo journalctl -u jellyfin -f for apt.
• Permissions. Wrong PUID/PGID shows up as unreadable media or an unwritable /config.
• Plugin order is yours. Our plugins come first among tuners, guide sources and subtitle providers, but you can change the order at any time.

Conclusion

medialab Server is the least dramatic upgrade you can make: same apps, same data, same folders — with Jellyfin 12.2 underneath, our verified plugins in front and MediaLab TV built in. Back up, pick Docker Compose or apt, and start it. The product page and the user guide cover the details, and the knowledge base has the full container and apt articles. Questions? The FAQ and contact page are open.