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
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.
mkdir -p ~/jellyfin/config ~/jellyfin/cache ~/jellyfin/media/Films
cd ~/jellyfinInside 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.
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.
id -u
id -gIf 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.
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
EOFEvery 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../configand./cache: these two folders on the server are linked to/configand/cachein 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.
sudo docker compose up -dWait half a minute, then ask it a simple question: are you well? Jellyfin answers on an address made for that.
curl -s http://127.0.0.1:8096/healthHealthy"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.
ssh -L 8096:127.0.0.1:8096 alice@203.0.113.10Then open http://localhost:8096 in your browser. The wizard guides you through a few screens:
- Pick the interface language.
- Enter a username, for example
alice, and a long password from your password manager. - Skip the libraries screen. We will add them in the next step.
- Pick your language for film titles and summaries.
- 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.
sudo docker compose exec jellyfin ls /media/FilmsVacances 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.
cd ~/jellyfin
sudo docker compose stop
tar czf jellyfin-config.tar.gz config
chmod 600 jellyfin-config.tar.gz
sudo docker compose startThe 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.
cd ~/jellyfin
sudo docker compose stop
mv config config.ancien
tar xzf jellyfin-config.tar.gz
sudo docker compose up -dAn update replaces the container with a newer one that keeps your folders. Do the backup first, then download and recreate.
sudo docker compose pull
sudo docker compose up -dThe 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. APermission deniedanswer confirms the problem. Give the folders to Jellyfin's account, the one in theuserline: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.