Skip to content

FAQ — Frequently Asked Questions

Jump to bottom
lwbt edited this page Dec 1, 2024 · 11 revisions

FAQ — Frequently Asked Questions

Data

What is a recommended folder structure for my media?

It is recommended to use the folder ${HOME}/Jellyfin Server Media/ and create folders inside of it.

Example to create media folders:
mkdir -pv "${HOME}/Jellyfin Server Media/"{Movies,Music,Shows,Books,Photos}

Where is the application data?

Data is stored for each user in the user’s home directory according to Flatpak conventions.

The path for Jellyfin Server is:

"${HOME}/.var/app/org.jellyfin.JellyfinServer"
To open a file browser in the directory on a desktop system where Jellyfin runs, use:
xdg-open "${HOME}/.var/app/org.jellyfin.JellyfinServer"

You can also see individual paths and their purpose in the dashboard.

Additionally there might be a Flatpak overrides file:
"${HOME}/.local/share/flatpak/overrides/org.jellyfin.JellyfinServer"
ℹ️

Jellyfin Server runs as an application in user context, not a system service. You can setup and use Jellyfin easily with multiple users, but data will be stored in ${HOME}/.var, not /var. Accessing and sharing media from different user accounts can be configured by modifying POSIX access-control lists, but it is not recommended and beyond the scope of this article.

How to backup application data

Make a backup of your configuration data before you install a new version of Jellyfin. A simple copy command could already save you a lot of trouble:

cp -a \
  "${HOME}/.var/app/org.jellyfin.JellyfinServer/" \
  "${HOME}/.var/app/org.jellyfin.JellyfinServer_bak_$(date -I)"
💡

A helper script has been integrated to have this command always at hand. It will not execute the code by itself, because of sandboxing, you need to cut and paste it.

flatpak run org.jellyfin.JellyfinServer backup

So it’s just the way the you run it from the command line with the extra parameter backup.

  • The overrides file is not relevant for release upgrades but may be for restoring data or moving to a different computer. (See section above for the overrides file.)

  • You need to also backup your media for a full backup. This is the most important part for you as a user, but not relevant for release upgrades when you stick with read-only permissions of folders for Jellyfin.

Restore and Migration

💡
 This needs to be extended.

  • At first you want to restore your media data. As stated in the backup section above, this is the most important thing for you as a user.

  • Then you want to install the Jellyfin Flatpak, and eventually restore any modifications made to the default configuration, the overrides file.

  • Then you want to restore the "${HOME}/.var/app/org.jellyfin.JellyfinServer/" folder. This holds your actual application configuration data, but ideally, to be not dependent on one specific platform, you should have a document that describes how you configured your media libraries and application settings, and also why.

Some people have written unofficial scripts in the past which seem to be no longer maintained. You can find more information in the official documentation. Most of the application configuration should be identical, just the locations are different.

Platform Support

Raspberry Pi 4 GPU

flatpak override --user --device=all org.jellyfin.JellyfinServer

Intel GPU

To enable HDR Tone mapping install the Intel extension:
flatpak install flathub org.jellyfin.JellyfinServer.Plugin.IntelComputeRuntime

App management

How to launch the application?

There are several ways to launch the application:

  • From the desktop shortcut which uses the default launcher.

    This will launch the server in the background and wait for the application health check before opening the web interface in your web browser. It will open the home screen at first launch. If Jellyfin has been started before and is already running it will open the settings dashbord.

  • Default launcher from the command line:

    flatpak run org.jellyfin.JellyfinServer

    This is the CLI equivalent to launching from the desktop shortcut.

  • Launcher script from the command line:

    flatpak run --command=jellyfin.sh org.jellyfin.JellyfinServer

    This is also the CLI equivalent to launching from the desktop shortcut.

  • Jellyfin itself from the command line:

    flatpak run --command=jellyfin org.jellyfin.JellyfinServer

    Using this launch option will bypass the behavior of the launcher script.

How do I keep the app updated?

  • Gnome-Software → Preferences → Software Updates → Automatic. That’s it.

  • On headless systems and servers: Configure a Systemd service and timer to update all or specific Flatpaks. Using Systemd instead of Cron gives you easy access to logs (Systemd-Journal).
    Example instructions have been included in a stub script which can be viewed with: flatpak run org.jellyfin.JellyfinServer updater.
    Source: github.com/flathub/org.jellyfin.JellyfinServer/blob/master/data/jf-updater.sh

❗
 The app has to be restarted to complete an upgrade.

How often does the app get updated?

There are over 30 components involved. Flathub bot runs every hour, so multiple updates per day can happen.

ℹ️
 35 modules according to Flatpak External Data Checker.

How can I run the app automatically?

ℹ️
 journalctl --unit jellyfin.service, or journalctl --user-unit jellyfin.service respectively, will only show basic service log messages. Use Dashboard → Logs in the web interface to view the application logs.

About Flatpak packaging

Why Flatpak?

  • Universal packaging format for all traditional and image-based Linux distributions.

  • Robust sand-boxing and security features with minimal overhead and resource usage.

  • Easier to manage than Docker and Kubernetes deployments.

Where should I file which types of issues?

  • Issues which can be identified as issues related to Flatpak packaging should be filed here.

    • Please do use the issue tracker to request version updates.

  • Issues related to jellyfin, jellyfin-web, jellyfin-ffmpeg and other components should be filed at the respective issue tracker.

How is the Flatpak updated on GitHub?

  • Flathub bot runs every hour to check for new versions of source modules.

  • The GitHub Actions Workflow Regenerate NuGet and Node Sources needs to be run manually when a new Jellyfin release gets published to update the lock files for NuGet and Node.

    ℹ️

    These lock files may also be known as requirements file (Python) or cache. Cache however, can be easily confused in the context of a pipeline like a GitHub Actions Workflow with the cache of downloaded data from a previous run, so lets avoid the word cache.

  • Flathub Build service starts building a new production release if both of the above pass test builds and get merged. Builds take about 30 to 45 minutes to build. Builds are published after about 4 to 6 hours.

  • A workflow with action-updater runs regularly to keep GitHub Actions Workflows up to date. (TODO)

Clone this wiki locally