Build a Jellyfin Media Server with Verified Configuration Backups

Expected Outcome

A working Jellyfin server with a validated media library, recorded service paths, and a repeatable backup procedure for Jellyfin configuration and application data.

Assumptions

• A currently supported 64-bit Debian, Ubuntu, or compatible derivative listed by the Jellyfin project.

• A user with sudo access.

• Media storage mounted at a stable path and readable by the Jellyfin service account.

• Enough storage for Jellyfin metadata/configuration backups in addition to whatever protection exists for the media files themselves.

Bill of Materials

• The official Jellyfin Debian/Ubuntu installation script and checksum from repo.jellyfin.org.

• One small known-good media file for playback validation.

• A backup destination outside `/var/lib/jellyfin` and `/etc/jellyfin`.

Build Steps

1. Capture the host and media-storage baseline

   Confirm the distribution, architecture, free space, and media mount before installing Jellyfin. Do not make Jellyfin responsible for fixing an unstable or intermittently mounted media path.

   Read-only command: verify target and scope

   cat /etc/os-release
   dpkg --print-architecture

   Manual or UI step

   • df -h / /path/to/media

   • findmnt /path/to/media

2. Download, verify, and review the official repository installer

   Jellyfin publishes an installation script and SHA-256 checksum for Debian/Ubuntu derivatives. Download both files, verify the checksum, and inspect the script before privileged execution instead of using the deprecated apt-key workflow.

   Changes system state: review before running

   mkdir -p ~/jellyfin-install && cd ~/jellyfin-install
   curl -s https://repo.jellyfin.org/install-debuntu.sh -O
   curl -s https://repo.jellyfin.org/install-debuntu.sh.sha256sum -O

   Manual or UI step

   • sha256sum -c install-debuntu.sh.sha256sum

   • less install-debuntu.sh

   Changes system state: review before running

   sudo bash install-debuntu.sh

3. Validate the service before configuring libraries

   Confirm that the package installation created a healthy Jellyfin service and that the expected local web endpoint is listening before adding media paths.

   Read-only command: verify target and scope

   systemctl status jellyfin --no-pager

   Manual or UI step

   • ss -ltnp | grep ':8096' || true

   Read-only command: verify target and scope

   curl -I http://127.0.0.1:8096/

4. Complete initial setup and add one controlled library

   Open the Jellyfin web interface, create the administrator account, and add a library that points to the intended media mount. Start with one small test library so permissions, metadata, and playback can be validated before indexing a large collection.

5. Validate service-account access to the media path

   Check the path as the Jellyfin service account rather than assuming root or your login user's access proves Jellyfin can read the media.

   Read-only command: verify target and scope

   sudo -u jellyfin test -r /path/to/media && echo 'Jellyfin can read media root'
   sudo -u jellyfin find /path/to/media -maxdepth 2 -type f -print -quit

6. Exercise metadata and playback

   Allow the library scan to complete, verify metadata for the known-good item, and play the item from a client. Playback is the validation boundary; a populated library alone does not prove transcoding/direct-play paths are healthy.

7. Record the package-install backup paths

   For Debian/Ubuntu package installations, Jellyfin documents /var/lib/jellyfin as the data directory and /etc/jellyfin as the configuration directory. Record the paths actually configured on your host before building a backup job.

   Read-only command: verify target and scope

   grep -E '^(JELLYFIN_DATA_DIR|JELLYFIN_CONFIG_DIR)' /etc/default/jellyfin || true
   sudo du -sh /var/lib/jellyfin /etc/jellyfin

8. Create a consistent configuration/data backup

   Stop Jellyfin for the short Lab backup window so the SQLite/application state is not changing while copied. Archive configuration and application data to a destination outside the live directories, then restart the service immediately. This protects Jellyfin state; it does not back up the media library itself.

   Changes system state: review before running

   BACKUP_ROOT=/path/to/backup/jellyfin-$(date +%Y%m%d-%H%M%S)
   sudo systemctl stop jellyfin
   sudo mkdir -p "$BACKUP_ROOT"
   sudo tar -C / -cpf "$BACKUP_ROOT/jellyfin-config-data.tar" etc/jellyfin var/lib/jellyfin
   sudo systemctl start jellyfin
   sudo sha256sum "$BACKUP_ROOT/jellyfin-config-data.tar" | sudo tee "$BACKUP_ROOT/SHA256SUMS"

9. Validate the backup artifact

   List the archive and verify its checksum. For stronger assurance, restore the archive to a disposable path or isolated test host and confirm the expected configuration/database files are present before you rely on it as recovery evidence.

   Read-only command: verify target and scope

   sudo sha256sum -c "$BACKUP_ROOT/SHA256SUMS"
   sudo tar -tf "$BACKUP_ROOT/jellyfin-config-data.tar" | head -50
   systemctl is-active jellyfin

Validation

• The Jellyfin service is active and the local HTTP endpoint responds after installation and again after the backup window.

• The Jellyfin service account can read the intended media path.

• A known-good media item is indexed with metadata and can be played from a client.

• The backup archive contains `/etc/jellyfin` and `/var/lib/jellyfin`, and its SHA-256 verification succeeds.

• The operator can state separately how the actual media files are protected; Jellyfin metadata backup is not represented as media backup.

Troubleshooting

• If Jellyfin does not start, inspect service status and recent journal entries before reinstalling or changing permissions broadly.

  Read-only command: verify target and scope

  systemctl status jellyfin --no-pager
  journalctl -u jellyfin --since '-20 minutes' --no-pager

• If media is visible to your login user but not Jellyfin, inspect ownership, group membership, ACLs, and mount options on the exact media path. Do not solve a narrow access problem with world-writable permissions.

  Manual or UI step

  • namei -l /path/to/media

  • getfacl -p /path/to/media | head -80

• If playback fails while browsing works, capture the Jellyfin server log and determine whether the client attempted direct play, remux, or transcoding before changing codecs or hardware-acceleration settings.

Cleanup or Rollback

• Remove only the temporary installer files after the installed repository and service are validated.

• Keep at least one verified configuration/data backup outside the live Jellyfin directories before testing upgrades or major configuration changes.

• If this was a disposable Lab and you uninstall Jellyfin, preserve the backup and media separately before purging packages or deleting `/var/lib/jellyfin` and `/etc/jellyfin`.

Next Improvements

• Schedule configuration/data backups with a maintenance-aware process and periodically test restoration on an isolated host.

• Protect the media library with storage-level backup/snapshot/replication appropriate to its size and value.

• Evaluate hardware acceleration only after normal playback works and the server/client capabilities are documented.

References

• Jellyfin — Linux installation
• Jellyfin — Manual repository installation
• Jellyfin — Backup and restore