Anime-Sanctuary

Jellyfin

Your family videos sleep in folders, on a disk or in a computer. Let's install Jellyfin, a personal media server, so you can watch them from a browser, a phone or a TV.

Course
Tutorial 23 of 35
Time
40 min to read
Tested with
Commands: tested on Debian 13 (Jellyfin 12.4)
What you will be able to do
  • Write a Compose file for Jellyfin with its three folders.
  • Create the admin account and add a video library.
  • Know how to make it reachable without exposing its port as it is.
  • Back up its settings and update Jellyfin.

Before you start: Docker and Docker Compose.

Contents
  1. What a media server does
  2. Prepare the folders
  3. Write the Compose file
  4. First start
  5. Create the admin account
  6. Add a library
  7. Watch on a browser, phone and TV
  8. Open it without exposing its port
  9. Back up and update
  10. If it fails
  11. What's next
  12. Sources

How do you install Jellyfin with Docker Compose on Debian? You need a Compose file of about ten lines, three well-organized folders and one account to create. Allow forty minutes. You get a personal media server that shows your own videos like a small streaming platform.

What a media server does

A personal media server is a librarian living on your server. It knows your videos, gives each one a poster and a title, and lends them to all your screens. Jellyfin is one, free and open source. You tell it where your files are, and it turns them into a shop window. It fetches posters and film summaries from the Internet, but your video files stay at home.

Not every device plays every format. When a TV can't play a file as it is, Jellyfin converts it on the fly. That's called transcoding. It makes the processor, the machine's brain, work hard, so a small server feels it. To set all this up, you first need well-organized folders.

1Prepare the folders

Jellyfin needs three folders: one for its settings (accounts, options, watch history), one for its cache (throwaway files like thumbnails) and one for your videos. We create them ourselves, before Docker does. Otherwise Docker creates them in the name of root, the administrator account, and Jellyfin wouldn't be allowed to write in them.

On the server
mkdir -p ~/jellyfin/config ~/jellyfin/cache ~/jellyfin/media/Films
cd ~/jellyfin

Inside media/Films, make one folder per film, named after the film, with the year in parentheses. Jellyfin reads that name to find the title and the year. For a holiday film, the folder is called Vacances a la mer (2019) and the file inside has the same name, followed by .mp4.

To drop your videos from your computer, use rsync, covered in Your first backup with rsync. The Videos folder in the command is yours, the one that holds your films.

On your computer
rsync -av Videos/ alice@203.0.113.10:jellyfin/media/Films/

The folders exist and the videos are on their way. Now write the file that describes the container.

2Write the Compose file

One service is enough: Jellyfin carries its own database. The file builds on what you know from Docker and Docker Compose. It links each folder on the server to a folder inside the container, and it keeps the port for the server itself.

One line deserves a check before you copy: user. It names the Linux account Jellyfin runs under. It will be yours rather than root, which limits the damage if there's a flaw. This account is written as two numbers: id -u gives your user number, and id -g gives your group's. If alice is the first account created, it's 1000 twice.

On the server
id -u
id -g

If you see anything other than 1000, replace "1000:1000" with your two numbers, separated by a colon. In the next command, cat copies the text between <<'EOF' and the EOF line into docker-compose.yml.

On the server
cat > docker-compose.yml <<'EOF'
services:
  jellyfin:
    image: jellyfin/jellyfin:12.4
    restart: unless-stopped
    user: "1000:1000"
    ports:
      - "127.0.0.1:8096:8096"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - ./media:/media:ro
EOF

Every line has its reason:

  • jellyfin/jellyfin:12.4: the official image, with a fixed version. Nothing changes unless you decide it.
  • 127.0.0.1:8096:8096: port 8096 is open to the server only. Nobody else can reach it for now, on purpose.
  • ./config and ./cache: these two folders on the server are linked to /config and /cache in the container. Jellyfin writes there.
  • user: "1000:1000": the account Jellyfin uses to read and write its folders, the one you just checked.
  • ./media:/media:ro: your videos, read-only (ro). Jellyfin can read them, but never erase or change them.

The file is ready. Let's switch Jellyfin on.

3First start

The first command downloads the image, which is fairly large, then starts the container. The -d option of up -d lets it run in the background, without blocking the terminal. Jellyfin needs about thirty seconds to be ready.

On the server
sudo docker compose up -d

Wait half a minute, then ask it a simple question: are you well? Jellyfin answers on an address made for that.

On the server
curl -s http://127.0.0.1:8096/health
Expected output
Healthy

"Healthy" means it's in good shape. If you get a connection error, wait ten seconds and try again. Jellyfin runs, but it has no account yet. Let's see how to reach it from home.

4Create the admin account

At first launch, Jellyfin opens a setup wizard that creates the admin account. This wizard has no password: whoever arrives first becomes the owner. That's why the port is kept for the server, and why you go through a tunnel.

An SSH tunnel links your computer's port 8096 to the server's, through the SSH connection. You saw it with Nextcloud, and the command is the same, on a different port. Keep this window open for the whole setup.

On your computer
ssh -L 8096:127.0.0.1:8096 alice@203.0.113.10

Then open http://localhost:8096 in your browser. The wizard guides you through a few screens:

  1. Pick the interface language.
  2. Enter a username, for example alice, and a long password from your password manager.
  3. Skip the libraries screen. We will add them in the next step.
  4. Pick your language for film titles and summaries.
  5. Leave remote access allowed, then finish.

You land on the login page, then on a home screen that's still empty. Your server has an administrator, and it's you. It just needs videos to show.

5Add a library

A library is a folder you hand over to Jellyfin, with a type: films, music, series. Jellyfin scans it and shows what it finds. In the dashboard (the menu at the top left), open "Libraries", then add one:

  • Content type: "Movies" for videos, "Music" for songs. Pick the one that matches your folder.
  • Name: whatever you like, for example "Family films".
  • Folder: /media/Films. That's the path inside the container, the one in the right-hand column of the Compose file, not ~/jellyfin/media/Films.

Confirm, and Jellyfin scans the folder. For a short film, allow a few seconds. You can check from the server that the container really sees your files.

On the server
sudo docker compose exec jellyfin ls /media/Films
Expected output
Vacances a la mer (2019)

In the interface, the film shows up on the home page, with its title and year. So Jellyfin can read your files. Let's play one.

6Watch on a browser, phone and TV

In the browser, click the film, then the play button. It starts right away, through the tunnel. It's the simplest test, and it's enough to check that everything works.

For now, Jellyfin can only be reached from your computer, through the tunnel. If that's all you need, go on to the backup in step 8. What follows opens Jellyfin to your other devices. It needs a domain name and HTTPS, and it makes the server visible on the Internet.

Phone and TV: the apps

You need an address that works outside the tunnel, so a domain name, covered in Domain name and DNS, and HTTPS. Jellyfin offers free apps for Android phones and iPhones, for Android TV and Fire TV, and more. In them you enter your server's address, then your name and password. The full list is on Jellyfin's clients page, listed in the sources.

7Open it without exposing its port

Opening port 8096 as it is would send your passwords and your videos in clear text over the Internet. To reach Jellyfin from your other devices, you need a solid front door. That's the job of a Reverse proxy. It receives visitors over HTTPS, with the certificate from HTTPS with Let's Encrypt, then passes their request to 127.0.0.1:8096.

The setup is the one from the dedicated article, with three changes. The target address is 127.0.0.1:8096. Your domain is, for example, jellyfin.exemple.fr. Finally, the ProxyPass line ends with upgrade=websocket, which gives ProxyPass / http://127.0.0.1:8096/ upgrade=websocket. This option lets through the always-open connections Jellyfin uses for its remote control.

In the apps, the address to enter then becomes https://jellyfin.exemple.fr. The whole Internet can now reach the login page. Keep a long password and only create accounts for people you trust. One thing is left: protecting what you just built.

8Back up and update

What matters is the config folder: your accounts, your libraries, everyone's watch progress. The cache rebuilds itself, and your videos are backed up separately, as in Your first backup with rsync. For a consistent copy, stop Jellyfin for a few seconds, archive config with tar, which packs the folder into one compressed file, then restart.

On the server
cd ~/jellyfin
sudo docker compose stop
tar czf jellyfin-config.tar.gz config
chmod 600 jellyfin-config.tar.gz
sudo docker compose start

The archive holds your accounts, so chmod 600 keeps it for you alone. It weighs a few hundred KB for a small library, more with lots of films. A backup that stays on the server won't protect you from a server failure, so copy it elsewhere.

Restore the settings

Stop Jellyfin, set the current settings aside, extract the archive into ~/jellyfin, which recreates config, then restart.

On the server
cd ~/jellyfin
sudo docker compose stop
mv config config.ancien
tar xzf jellyfin-config.tar.gz
sudo docker compose up -d

An update replaces the container with a newer one that keeps your folders. Do the backup first, then download and recreate.

On the server
sudo docker compose pull
sudo docker compose up -d

The number 12.4 gets the fixes of this series. To move to the next one, change the number in the file, then run the two commands again.

If it fails

Four situations come up again and again:

  • Jellyfin refuses to add the folder. You entered a path from the server instead of a path from the container. The log says so: sudo docker compose logs jellyfin | grep "does not exist" prints, for example, The specified path does not exist: /home/alice/videos. Enter /media/Films.
  • The library is added, but no film shows up. The container isn't allowed to read your files. Test with sudo docker compose exec jellyfin ls /media/Films. A Permission denied answer confirms the problem. Give the folders to Jellyfin's account, the one in the user line: sudo chown -R 1000:1000 ~/jellyfin/media, with your two numbers if they aren't 1000. Don't make the films readable by every account on the server.
  • The film shows up under a raw file name, with no poster. The folder name doesn't follow the "Title (year)" pattern. Rename it, then rescan the library from the dashboard.
  • port is already allocated. Something else uses port 8096. Change the first 8096 in the file, as in the Docker article.

What's next

Your videos now have their shop window, with an account, a backup and a clean way in. Your scanned comics and your e-books deserve one too. The next article, Kavita, applies the same method to a reader made for them.