Setup private media server with Jellyfin on OpenWrt using Docker | Detailed tutorial

Want to have your own private media server that fetches movie and TV show information, ratings, synopsis, etc. automatically? That’s easy with Jellyfin. And, thanks to Docker, you can setup Jellyfin Media server on OpenWrt. In this step-by-step tutorial for beginners, we will cover everything from setting up Docker on OpenWrt to running Jellyfin on OpenWrt along with common issues and their solution.

Let us first understand what Jellyfin is.

What is Jellyfin?

Here’s how the official page puts it:-

Jellyfin is the volunteer-built media solution that puts you in control of your media. Stream to any device from your own server, with no strings attached. Your media, your server, your way.

For those unaware, the project is opensource on GitHub. Both the server and the client are available on almost every OS, on top of Docker images. So, it’s highly interoperable and supported by the community.

That brings me to the next thing that we will be setting up on our OpenWrt device – Docker.

What is Docker?

Docker’s home page has to say this:-

Docker helps developers build, share, run, and verify applications anywhere — without tedious environment configuration or management.

In simpler terms, Docker or rather Docker containers are mini-Linux installations holding your favourite applications (Docker images). This way managing these apps, segregating them and even testing them becomes much easier. Docker is also not very power hungry. This works in our favour, as the devices we plan to run these are not very powerful as well.

So, now, let’s jump into the tutorial.

Video Tutorial: Setup Jellyfin Media Server on OpenWrt with Docker

For the textual tutorial, keep reading.

How to setup Jellyfin Media Server using Docker on OpenWrt?

Disclaimer

Neither me, nor PS4Linux.com or anybody mentioned in this article (We) is responsible for any damages you face due to following the instructions or using OpenWrt, Docker, Jellyfin or related packages on your router. Carefully look into local or regional laws before installing/using OpenWrt, Docker, Jellyfin or related packages on your router, as many regions do have restrictions, sometimes legal, in place. OpenWrt, Docker, Jellyfin and other related packages open up your router to many possibilities, some of which may be considered illegal in some areas. We are not responsible for anything that happens due to usage of OpenWrt, Docker, Jellyfin or related packages by You and do not provide any guarantee or warranty in regards to anything in this article or its pages. We also, in no way condone media piracy. You are completely responsible for any action taken pursuing this article. This article is strictly for educational purposes. You proceed at your own risk!

Requirements

• Device running OpenWrt with USB/Memory card port
  • On Amplifi HD, flash the updated image with inbuilt Luci & USB dependencies. Then, setup Extroot to increase disk space (also applicable for devices with low internal storage).
  • N.B. It is recommended to be using a powerful router or another device like Android box running OpenWrt for this, as some processes in serving media files is CPU and RAM-intensive. In this tutorial, I will be using my Amlogic S905 Android Box running ophub’s OpenWrt Image. It is also recommended to have Samba server on OpenWrt for easier management of media files and a download manager like Aria2 for OpenWrt. Infact, this tutorial assumes you have Samba share already setup.
• SSH/Terminal access to OpenWrt device
• USB Drive/Memory Cards (if supported) – Size depends on size
• Device with internet browser connected to router
• GParted Live (Download here) – Recommended if re-partitioning

Now, let’s jump into the tutorial.

Step 1. Install Docker on OpenWrt

1. Go to terminal/SSH (via Putty) and login to your router as root.
2. Type opkg update and press Enter.
3. To install the packages necessary for Docker, type opkg install dockerd docker luci-app-dockerman luci-lib-docker and press Enter. Some of these packages might already be installed on your device.

Step 2. Setup USB Drive for Jellyfin on OpenWrt

Jellyfin on OpenWrt running on a Docker container will require 2 partitions (Ext4 is fine for both):-

1. Docker Root partition: This will hold all our Docker images, containers and related data. Set aside atleast 2GB for this partition, as Jellyfin Docker image alone would take up around 1GB after installation.
2. Media partition: If you have already setup Network share using Samba on OpenWrt, you can use that partition.

In any case, make sure you use a Linux machine or OpenWrt itself to set these partitions on top of Extroot, if you already have it. You can also try using a USB hub to add another drive just for Docker Root partition, but that’s not recommended. Just use GParted or a similar application to shrink existing partitions and create new ones for Docker Root. Check the tutorial video, if it seems confusing.

Step 3. Mount USB drive and configure Docker on OpenWrt

1. Plug the USB drive into your OpenWrt device.
2. Login to OpenWrt Web Admin GUI (Luci) and go to System → Mount Points. Check if the Docker Root partition got mounted automatically. If yes, click on Unmount.
3. Under Mount Points, click on Add.
4. In the dropdown next to UUID, select your Docker Root partition.
5. Click on the dropdown next to Mount point, click on custom and type /opt/docker. Then, click Save.
6. To verify if it got properly mounted, on terminal, type df -h /opt/docker and press Enter. Under Filesystem, it should output the device identifier for your Docker Root partition.
7. Next, we need to check if Docker Daemon (dockerd) has a configuration file read to go. To do that, type cat /etc/config/dockerd and press Enter. If it is empty, or throws an error, type cp /etc/config/dockerd-opkg /etc/config/dockerd and press Enter. Else, continue to next step.
8. Now, to edit this file, it is recommended to install Nano text editor, which can be done by running opkg update && opkg install nano on the terminal.
9. Next, open the config file in Nano by typing nano /etc/config/dockerd and press Enter. Find the line that says option data_root. Check if the value within the single inverted commas is /opt/docker. Else, edit it such that the line says option data_root '/opt/docker/'. When done, press on Ctrl + S and Ctrl +X to save and exit.

To check if it is configured properly, reboot your router. Then, check Docker under Main Menu. It should have options such as Configuration, Overview, Images, Containers, etc. If it doesn’t, check the troubleshooting steps below. If Menu is shown properly, go to Docker → Overview and check if Docker Root Dir points to /opt/docker and that the size corresponds to the partition.

Step 4. Add user and folders for Jellyfin and set directory permissions

As always, running root is an option. But, it is not recommended. So, we will set up a new user and add Jellyfin-related folders (config and cache) for this new user. Follow the steps below:-

1. To install applications required to add a user, type opkg update && opkg install shadow-useradd and press Enter.
2. Add the new user by typing useradd noob404 and press Enter. Replace noob404 with your preferred username.
3. To make the directories, type these commands one by one and press Enter. N.B. Each new line is a command. Also, replace noob404 with your preferred username.

   mkdir -p /home/noob404/jellyfin/cache
   mkdir -p /home/noob404/jellyfin/config

4. To set directory permissions, we need to make our new user the owner of the newly created Jellyfin directories. To do that, type chown -R noob404:noob404 /home/noob404 and press Enter.
5. Type cat /etc/passwd and check the output. Find the uid:guid pair next to your newly created username, for example, 32768:32768. Make a note of this, as we will need it in Step 6.

Step 5. Pull Jellyfin Docker image

1. On terminal, type docker pull jellyfin/jellyfin and press Enter. Wait for the process to complete.
2. Verify proper installation by checking Docker → Images on OpenWrt Web Admin GUI (Luci).

Step 6. Setup and start Jellyfin Docker Container on OpenWrt

1. On OpenWrt Web Admin GUI (Luci), go to Docker → Containers.
2. Click on Add and set the following values:-
   • Container Name: Set a preferred name for the container. It can be anything.
   • Docker Image: In the dropdown, select jellyfin/jellyfin:latest.
   • Always pull image first: Check it.
   • Restart Policy: Change to Always, if you want to start the Jellyfin server automatically on every boot.
   • Networks: From the dropdown, select host | host.
   • User(-u): Enter the uid:guid pair we made a note of, in Step 4, for example, 32768:32768.
   • Environment Variable(-e): Set timezone. For example, for India, it should be TZ=Asia/Kolkata.
   • Bind Mount(-v): Enter these values one by one clicking on the + button each time. Also, replace /mnt/sda1 with your media partition (in my case the Samba network share partition).

     /home/noob404/jellyfin/config:/config
     /home/noob404/jellyfin/cache:/cache
     /mnt/sda1:/media

   • Leave the other values to default.
3. Click on Submit.
4. Return to Containers page.
5. Check the box next to your Jellyfin container and click on Start.

Wait for a few minutes for the container to start. Then, on your internet browser, go to your router’s IP followed by :8096, for example, http://192.168.1.1:8096. This will drop you into Jellyfin’s web page.

Step 7. Setup Jellyfin server, add libraries and more

The first time you visit the web page, you will have to set some basic things, like the username and password. Set a suitable username and password, which doesn’t necessarily have to be the one we set up in Step 4. Set language and region options. Leave other settings to default (if any).

To add libraries, you can go to Jellyfin’s web page and go to Dashboard. As for folder selection, go to root (/) and select media to get access to your media partition within Jellyfin on OpenWrt. Here are a few tutorials to get you started:-

• Adding libraries to Jellyfin
• Jellyfin naming convention for shows
• Jellyfin naming convention for movies
• Jellyfin plugins

Now, let us look into some common issues and their solution.

Troubleshooting: Jellyfin on Docker running on OpenWrt

Docker Menu only has Configuration, other options missing

This is a known issue with luci-app-dockerman (Luci Docker Manager for OpenWrt) where even after setting the configuration file properly, Docker Menu on Luci only shows Configuration. This was initially thought to be due to an issue with Docker Daemon (dockerd) failing to start, as mentioned here. But, in my case, nothing worked. So, here is what I did to fix it.

1. Turn your device off (DO NOT reboot).
2. Turn it back on.
3. Wait for 5 minutes before you login back to Luci to check if Docker now shows other sub-menu items (Images, Containers, etc.). If that doesn’t fix it, try rebooting a few times, each time, increasing the time before which you decide to enter Luci webpage.

In my case, after I setup the container, this issue vanished completely. I am guessing it still has something to do with the Docker container starting late.

100% CPU usage by jellyfin-mpeg

If you have successfully setup the libraries and ware consuming the media on your Jellyfin server, you will soon see that the OpenWrt device constantly runs at 100% CPU, thus causing overheating. This is a special cause of concern if you are using a cheap Android box. The fix is pretty easy. But, let me quickly explain why this happens. Most cheap systems like an Android box do not support hardware transcoding, which is what causes high CPU usage. But, what actually triggers the transcoding is the client you are using to watch/consume the media, which in most cases is an internet browser.

The fix is extremely simple to implement – use Jellyfin’s official client! That’s it! Jellyfin has official clients for almost every OS and device out there, including Fire TV, Roku, WebOS (LG), Android, Windows, Mac, etc. Download it here. Use it to watch media hosted on your Jellyfin server. In most cases, this will help you revert to direct play instead of transcoding, which translates to much lesser CPU usage and cooler heads (CPUs)!

Media library scanning stuck on 48% or no media added after library scan

If you still face this issue given user permissions were set properly and you followed proper naming conventions, it’s most likely a plugin issue. Jellyfin depends on 3rd party API (The Movie Database, The Open Movie Database, etc.) to collect information regarding movies including their artwork, synopsis, etc. But, many of these APIs are inaccessible on some ISPs in some countries. For example, I, from India, am unable to access both these APIs. Thus, Jellyfin is unable to add media properly. This is why you see this issue.

To fix it, follow these steps:-

1. Go to Dashboard → Catalog on Jellyfin.
2. Install another database, for example, TheTVDB.
3. Click on Dashboard and click Restart.
4. Go to your Library and click on Manage library.
5. Untick the non-working databases and use the arrow keys to bring the new database, in my case, the TheTVDB, to the top. When done, click on OK.
6. Click on Dashboard and click Scan All Libraries.

This should fix the issue.

Conclusion

I hope you enjoyed this article. If you do face any issues, just leave a comment below and I will try to help you out.