Jellyfin Setup Guide: Your Complete Open-Source Media Server Walkthrough

Jellyfin Setup Guide: Your Complete Open-Source Media Server Walkthrough

by

Understanding Jellyfin: The Open-Source Alternative

Jellyfin stands as a fully open-source media server solution, born from a community fork of Emby after its proprietary shift. Unlike Plex or Emby, Jellyfin requires no licensing fees, no account creation, and no telemetry. It runs entirely on your hardware, giving you complete control over your media library. This guide provides a step-by-step installation and configuration walkthrough, covering Docker and native setups, hardware transcoding, reverse proxy configuration, and advanced optimization for a production-ready environment.

Prerequisites and Preparation

Before beginning, assess your hardware. Jellyfin is lightweight; a Raspberry Pi 4 can serve direct streams to a few users, but transcoding (converting video on-the-fly) demands CPU or GPU power. For 4K HDR transcoding, an Intel CPU with Quick Sync (7th gen or newer) or an NVIDIA GPU (GTX 1050 Ti or higher) is recommended. Minimum system requirements include: 2GB RAM (4GB+ for transcoding), 2GB free disk space for the base application, plus storage for your media. A 64-bit operating system (Ubuntu 22.04 LTS or Debian 12 are ideal) and a stable network connection are essential. You will also need SSH access (for headless servers) and basic familiarity with the command line.

Installation Methods: Docker vs. Native

Docker is the most portable and maintainable method, isolating Jellyfin and its dependencies. Native installation offers slightly lower overhead but requires manual dependency management. For most users, Docker is superior due to easy updates and rollbacks.

Docker Installation (Recommended)

Ensure Docker and Docker Compose are installed. Create a project directory:

mkdir ~/jellyfin && cd ~/jellyfin

Create a docker-compose.yml file:

version: "3.8"
services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - JELLYFIN_PublishedServerUrl=http://your-domain.com # Optional
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /path/to/media:/media:ro
    ports:
      - 8096:8096
      - 8920:8920 # Optional: HTTPS
    devices:
      - /dev/dri:/dev/dri # For Intel Quick Sync
    restart: unless-stopped

Replace /path/to/media with your media directory. For NVIDIA GPU support, add runtime: nvidia and deploy.resources.reservations.devices (detailed in advanced section). Run:

docker compose up -d

Jellyfin is now accessible at http://your-server-ip:8096.

Native Installation (Ubuntu/Debian)

Add the official repository:

sudo apt update && sudo apt install curl gnupg
curl -fsSL https://repo.jellyfin.org/ubuntu/jellyfin_team.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/jellyfin.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/jellyfin.gpg] https://repo.jellyfin.org/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/jellyfin.list
sudo apt update
sudo apt install jellyfin

Enable and start the service:

sudo systemctl enable jellyfin
sudo systemctl start jellyfin

Open http://your-server-ip:8096 to begin the web setup.

Initial Configuration Wizard

Upon first access, you will be prompted to create an administrator account. Enter a strong username and password. Then, configure your media library. Click “Add Media Library” and select content type (Movies, TV Shows, Music, etc.). For Movies, set the folder path to your media directory (e.g., /media/movies). Jellyfin supports multiple libraries—create separate ones for 4K content, anime, or home videos.

Enable “Real-time monitoring” to automatically detect new files. For “Metadata readers,” keep the defaults (NFO files, TheMovieDb). Under “Image fetchers,” select TMDB and Fanart.tv. For TV Shows, enable TheTVDB. Ensure your media follows a standard naming convention: MovieName (Year).ext and TVShow/Season 01/EpisodeName.ext. This prevents metadata mismatches.

Advanced Configuration: Transcoding and Hardware Acceleration

Transcoding is resource-intensive. Hardware acceleration offloads this to your GPU. In Jellyfin’s dashboard (Settings > Playback > Transcoding), enable hardware encoding. For Intel Quick Sync, select “Video Acceleration: Intel QSV.” For NVIDIA, choose “NVAENC/NVDEC.” You must install the appropriate drivers and libraries on the host.

For Intel (native Ubuntu):

sudo apt install intel-media-va-driver-non-free vainfo

For Docker, ensure /dev/dri is passed to the container (already done in the compose file above). For NVIDIA, install the NVIDIA Container Toolkit and add to compose:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

Test transcoding by playing a 4K file in a browser (which forces a transcode). Check Jellyfin logs for errors.

Network Configuration: Reverse Proxy with Nginx

Direct HTTP access is insecure. Use a reverse proxy (Nginx) with SSL. Install Nginx and Certbot (for Let’s Encrypt certificates):

sudo apt install nginx certbot python3-certbot-nginx

Create an Nginx configuration file /etc/nginx/sites-available/jellyfin:

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;

    location / {
        proxy_pass http://localhost:8096;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /socket {
        proxy_pass http://localhost:8096/socket;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Enable the site and obtain a certificate:

sudo ln -s /etc/nginx/sites-available/jellyfin /etc/nginx/sites-enabled/
sudo certbot --nginx -d your-domain.com
sudo nginx -t && sudo systemctl reload nginx

Now access Jellyfin securely at https://your-domain.com.

Plugin Ecosystem: Extending Functionality

Jellyfin’s plugin system unlocks features like metadata agents, subtitles, and integrations. Install from Settings > Plugins > Catalog. Essential plugins include:

  • Open Subtitles: Fetch subtitles automatically.
  • Fanart: Enhanced backdrop art.
  • TMDb Box Sets: Automatic movie collections.
  • Intro Skipper: Skip TV show intros (requires FFmpeg with certain patches).
  • Playback Reporting: Monitor user activity.
    Install by clicking the plugin and selecting “Install.” Restart Jellyfin for changes to take effect.

User Management and Access Control

Create separate user accounts for family or friends. Go to Dashboard > Users > Add User. Set a password and assign libraries under “Library Access.” Use “Access Schedule” to restrict viewing hours for children. Enable “Allow remote connections” only for trusted users. For passwordless guest access, create a user with no password and restrict to a specific library.

Media Organization: Folder Structure and Naming

Jellyfin relies on folder structure and file names for accurate metadata. Follow this hierarchy:

/media
├── movies
│   ├── The Matrix (1999)
│   │   ├── The Matrix (1999).mkv
│   │   └── poster.jpg
│   └── Inception (2010)
│       └── Inception (2010).mp4
└── tvshows
    ├── Breaking Bad
    │   ├── Season 01
    │   │   ├── Breaking Bad S01E01.mkv
    │   │   └── Breaking Bad S01E02.mkv
    │   └── Season 02
    └── Game of Thrones

Use Sonarr and Radarr for automated renaming. Avoid special characters except hyphens and underscores. For 4K and standard versions, create separate libraries (e.g., “Movies 4K” and “Movies HD”) and assign different user permissions.

Monitoring and Maintenance

Monitor Jellyfin health using built-in logs (Dashboard > Logs) or external tools like Grafana with Prometheus (via jellyfin-exporter). Schedule regular metadata refreshes: Dashboard > Scheduled Tasks > “Refresh metadata” every 24 hours. Update Jellyfin regularly. With Docker, pull the latest image:

docker compose pull && docker compose up -d

Backup the config directory (or /etc/jellyfin for native) weekly to avoid library loss.

Performance Tuning and Troubleshooting

If streaming stutters, reduce transcoding bitrate limits (Playback > Streaming > Maximum allowed bitrate). For audio sync issues, disable “Audio boost when downmixing.” For subtitle rendering problems, switch from “ASS” to “SRT” or enable “Burn subtitles only when necessary.” Monitor CPU and GPU usage with htop and nvidia-smi. If using a Raspberry Pi, ensure GPU memory is at least 256MB in config.txt. For large libraries (10,000+ items), increase database cache: in /etc/jellyfin/system.xml (native) or mount /cache on a fast SSD.

Security Hardening

Disable remote access to the admin dashboard. In Nginx, add:

location /web/ {
    allow 192.168.1.0/24;
    deny all;
}

Use fail2ban to block brute force attempts. Create a jail for Jellyfin:

[jellyfin]
enabled = true
port = http,https
filter = jellyfin
logpath = /var/log/jellyfin/jellyfin.log
maxretry = 5

Create the filter file /etc/fail2ban/filter.d/jellyfin.conf with regex matching failed login attempts. Enforce HTTPS via HSTS headers in Nginx:

add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";

Final Operational Checks

Verify hardware transcoding works by playing a high-bitrate file and checking the dashboard for “Transcoding” indicators. Test remote access from an external network. Ensure cron jobs for backups are active. For large deployments, consider clustering Jellyfin with a shared database (PostgreSQL) and NFS storage. Document your setup for future reference. The system is now ready for daily use.

Leave a Comment