Jellyfin installeren op een VPS met Docker

Wat u gaat bouwen

Een Jellyfin-mediaserver op een VPS: één container, drie volumes en een block-storage-schijf voor uw films en series, bereikbaar vanuit elke browser of Jellyfin-app. De installatie bestaat uit een compose-bestand van vijftien regels. Alles wat daarna misgaat, komt voort uit twee oorzaken: bestandsrechten die de container niet kan lezen, en het verzoek aan een VPS zonder GPU om video te transcoderen waarvoor deze niet geschikt is. Deze handleiding besteedt het grootste deel van de tekst aan deze twee punten, omdat daar de meeste supportvragen vandaan komen.

Jellyfin is gratis en volledig open source, zonder account, betaalde functies of telemetrie; dit is de reden waarom het op bijna elke lijst staat van zaken die de moeite waard zijn om in 2026 zelf te hosten. Het speelt media af die u zelf bezit. Het bevat geen content en deze handleiding gaat niet over het verkrijgen daarvan.

De realiteit van transcoding, voordat u iets huurt

Lees dit eerst, want het verandert wat u aanschaft. Een mediaserver doet een van de twee volgende dingen wanneer u op afspelen drukt. Direct play streamt het bestand zoals het is: de VPS leest bytes van de schijf en verstuurt deze over de verbinding, wat vrijwel geen CPU kost. Transcoding codeert de video on-the-fly opnieuw, met een nieuwe resolutie, een nieuwe codec of ingebrande ondertiteling, en dat is puur CPU-werk.

Een standaard VPS heeft geen GPU. Elke videotranscode draait dus op de CPU met libx264/libx265, en software-encoding is kostbaar. Een enkele 1080p H.264-transcode kan meerdere gedeelde vCPU's volledig belasten; een 4K- of HEVC-transcode kan de real-time snelheid meestal niet bijhouden, waardoor het afspelen stopt en oneindig buffert. Hardware-transcoding, de techniek die dit goedkoop maakt op een thuis-pc met een Intel iGPU of een Nvidia-kaart, is simpelweg niet beschikbaar tenzij uw provider GPU-instances verhuurt.

De gehele strategie op een VPS is daarom: vermijd transcoding. Houd uw bibliotheek in codecs die uw clients native afspelen, H.264-video, AAC- of AC3-audio, in een MP4- of MKV-container, en kies client-apps die direct-play ondersteunen: de native Jellyfin-apps voor Android TV, iOS en Roku, plus Infuse, Kodi en de desktop Jellyfin Media Player. Doe dat en de VPS hoeft tijdens het afspelen nooit een ffmpeg-transcode uit te voeren, waardoor een bescheiden box met 2 vCPU's naar meerdere mensen tegelijk kan streamen. Als u van plan bent te transcoderen, heeft u een veel grotere, duurdere box nodig, en zelfs dan is 4K een riskante keuze.

Maak ook de berekening voor de bandbreedte, want dat is de andere verrassing. Direct play verstuurt het bestand met de eigen bitrate. Een gecomprimeerd 1080p-bestand verbruikt 8-12 Mbps; een 1080p Blu-ray remux 20-30 Mbps; 4K HDR 40-80 Mbps. Drie mensen die 10 Mbps-bestanden direct afspelen, zorgen voor 30 Mbps aan constante upload vanaf uw VPS. Controleer twee getallen in uw abonnement: de poortsnelheid (kan deze 30 Mbps upstream aan?) en de maandelijkse datalimiet. Eén film van twee uur met 10 Mbps is ongeveer 9 GB aan dataverkeer, dus een limiet van 1 TB/maand is goed voor iets meer dan honderd van dergelijke films per maand, drie of vier per dag. Een huishouden dat 4K kijkt, met vier tot acht keer de bitrate, verbruikt dit veel sneller. Reken al het andere verkeer dat vanaf dezelfde box naar buiten gaat mee in datzelfde budget, inclusief een zelfgehoste RustDesk relay, die een volledige externe desktopsessie verzorgt wanneer twee peers geen directe verbinding kunnen maken.

Vereisten

• Een nieuwe Ubuntu 24.04 KVM VPS met root- of sudo-toegang, inclusief Docker en de Compose-plugin geïnstalleerd.
• Een block-storage volume voor de media, met een grootte die past bij uw bibliotheek (zie de dimensionering hieronder). De kleine root-schijf die bij een VPS wordt geleverd, is niet de plek waar uw films moeten staan.
• Een domeinnaam als u publieke HTTPS-toegang wilt, of een WireGuard VPN op dezelfde VPS als u het geheel liever privé houdt.
• Media die u legaal mag streamen, uw eigen rips, uw eigen opnames, bestanden waarvan u de eigenaar bent.

Koppel eerst de block storage

Koppel het volume in het configuratiescherm van uw provider, zoek het vervolgens op en monteer het. Achterhaal de apparaatnaam via lsblk; dit zal iets zijn als /dev/sdb of /dev/vdb, maar nooit de root-schijf.

lsblk
sudo mkfs.ext4 /dev/sdb          # ONLY on a new, empty volume: this ERASES it
sudo mkdir -p /mnt/media
sudo blkid /dev/sdb              # copy the UUID shown for this device

Monteer het volume op basis van de UUID, niet via /dev/sdb, omdat apparaatletters bij een herstart kunnen wijzigen. Hierdoor loopt u het risico de verkeerde schijf te formatteren of te koppelen. Voeg één regel toe aan /etc/fstab:

UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  /mnt/media  ext4  defaults,nofail  0  2

sudo mount -a
df -h /mnt/media

nofail is van belang: zonder deze optie zal de server bij een ontkoppeld block volume weigeren op te starten en terugvallen naar een emergency shell. De meest gemaakte fout is het uitvoeren van mkfs.ext4 op een volume dat al data bevat; dit wist alle gegevens. Formatteer alleen nieuwe volumes; als de schijf al uw bestanden bevat, ga dan direct door naar de regel voor fstab.

De media indelen volgens de verwachtingen van Jellyfin

Jellyfin koppelt metadata op basis van map- en bestandsnamen. Bij een onjuiste indeling verschijnen films als bestanden zonder titel en poster, of wordt een aflevering aan de verkeerde serie gekoppeld. Vier conventies volstaan voor het meeste werk: elke film staat in een eigen map met een bijbehorende bestandsnaam, genaamd Name (Year) (Jellyfin beschouwt het jaartal als optioneel, maar het maakt de koppeling aanzienlijk betrouwbaarder); seizoensmappen worden benoemd als Season 01, niet S01; afleveringsbestanden gebruiken S01E01; en specials worden geplaatst in Season 00.

/mnt/media
├── Movies
│   ├── Blade Runner (1982)
│   │   └── Blade Runner (1982).mkv
│   └── Arrival (2016)
│       └── Arrival (2016).mkv
└── Shows
    └── Severance (2022)
        ├── Season 01
        │   ├── Severance - S01E01.mkv
        │   └── Severance - S01E02.mkv
        └── Season 00
            └── Severance - The Lexington Letter.mkv

De (Year) bij films is geen versiering; het onderscheidt remakes zodat de matcher de juiste titel selecteert. Houd Movies en Shows als afzonderlijke mappen op het hoogste niveau, omdat elk daarvan een Jellyfin-bibliotheek van een specifiek inhoudstype wordt; het mengen hiervan verstoort de metadata-provider. Jellyfin indexeert met plezier ook een derde map met foto's, maar de ervaring is beperkt in vergelijking met een gespecialiseerde fotoserver. Als uw albums belangrijk zijn, kunt u deze beter onderbrengen op een eigen systeem met PhotoPrism of Immich en deze server reserveren voor films en tv-series.

Rechten: de voornaamste reden voor lege bibliotheken

Dit is het misverstand dat mensen vaak een hele avond kost. De officiële jellyfin/jellyfin-image respecteert de PUID/PGID-omgevingsvariabelen niet; deze horen bij de LinuxServer.io-image (lscr.io/linuxserver/jellyfin). Bij de officiële image beheert u de gebruiker met de user:-sleutel in compose, en als u deze weglaat, draait de container als root. Welke u ook gebruikt, de regel blijft gelijk: de uid/gid waaronder de container draait, moet elk mediapad kunnen lezen en doorlopen.

We draaien als uid/gid 1000, de eerste niet-rootgebruiker op een standaard Ubuntu-systeem. Bevestig uw eigen waarden en stel het eigenaarschap in:

id                                  # confirm your user is uid=1000 gid=1000
sudo chown -R 1000:1000 /mnt/media
sudo find /mnt/media -type d -exec chmod 755 {} \;
sudo find /mnt/media -type f -exec chmod 644 {} \;
mkdir -p ~/jellyfin/config ~/jellyfin/cache
sudo chown -R 1000:1000 ~/jellyfin

Mappen hebben de execute-bit nodig (de x in 755), niet alleen leesrechten. Zonder deze bit kan de container de map niet betreden, ook al kan de naam wel worden weergegeven. De valkuil die een hele bibliotheek leegmaakt, is de bovenliggende map: als de uid van de container de mount zelf niet kan doorlopen, bereikt deze nooit /media/Movies of /media/Shows, en verschijnt elke bibliotheek direct als leeg met Access to the path ... is denied in het logbestand. Elke individuele mediamap die niet gelezen kan worden, wordt gelogd en overgeslagen. Hierdoor verdwijnt een reeks bestanden die als root zijn gekopieerd geruisloos uit de bibliotheek. Daarom voeren we een recursieve chown uit en stellen we de execute-bit in op elke map, in plaats van slechts één map te herstellen.

Het docker-compose bestand

services:
  jellyfin:
    image: jellyfin/jellyfin:12
    container_name: jellyfin
    user: "1000:1000"
    restart: unless-stopped
    ports:
      - "127.0.0.1:8096:8096"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /mnt/media:/media:ro
    environment:
      - JELLYFIN_PublishedServerUrl=https://jellyfin.example.com

Regel voor regel: jellyfin/jellyfin:12 volgt de huidige 12.x release-lijn (12.2 per 2026-10-10). user: "1000:1000" stelt de uid/gid in waaronder het Jellyfin-proces wordt uitgevoerd. Dit wijzigt de eigenaar of rechten van bestanden niet, omdat Docker de uid/gid van de host op gemounte mappen behoudt. Daarom moet de chown hierboven hiermee overeenkomen. /config bevat de volledige server, accounts, bibliotheken, metadata en de kijkstatus; deze map moet schrijfbaar zijn en is het onderdeel waarvan u back-ups maakt. /cache is tijdelijke werkruimte. De media-mount is bewust :ro (alleen-lezen): Jellyfin slaat standaard artwork en metadata op onder /config, waardoor het nooit naar uw bibliotheek hoeft te schrijven. De alleen-lezen instelling beschermt uw bestanden tegen onbedoeld verwijderen of een defecte plugin. De poort is bewust gebonden aan 127.0.0.1; de web-login van Jellyfin is standaard HTTP, dus we stellen 8096 nooit bloot aan het openbare internet. JELLYFIN_PublishedServerUrl is het adres dat de server adverteert voor lokale automatische detectie, een LAN UDP-broadcast. Clients via internet zien dit nooit en gebruiken simpelweg de URL die u in de app invoert. Stel dit in op het adres dat aan clients moet worden doorgegeven en houd er rekening mee dat u die URL handmatig moet invoeren op apparaten op afstand.

Start de service vanuit de compose-directory:

docker compose up -d
docker logs -f jellyfin

Eerste uitvoering: de installatiewizard en uw bibliotheken

Omdat de poort is gebonden aan localhost, bereikt u de wizard via een SSH-tunnel vanaf uw laptop in plaats van een gat in de firewall te openen:

ssh -L 8096:127.0.0.1:8096 you@your-vps-ip

Navigeer nu naar http://localhost:8096. De wizard leidt u door de taalkeuze en vervolgens het aanmaken van een beheerdersaccount met een sterk wachtwoord. Dit account is uw server, dus gebruik geen tijdelijk of hergebruikt wachtwoord. Voeg uw eerste bibliotheek toe: kies het inhoudstype Movies, verwijs naar /media/Movies (het pad binnen de container, niet het hostpad), en herhaal dit voor Shows op /media/Shows. Voltooi de stappen en Jellyfin start de scan. Een correct resultaat is dat posters en titels binnen een minuut of twee verschijnen voor een kleine bibliotheek. Voeg bibliotheken later toe of bewerk ze via Dashboard → Libraries en forceer een nieuwe scan met Scan All Libraries. Die posters maken ook een alternatieve frontend de moeite waard zodra de basis werkt, aangezien Halcyon dezelfde bibliotheek herbouwt als een beloopbare videotheek uit de jaren 90 op basis van het artwork dat Jellyfin al heeft opgehaald.

Als u afhankelijk bent van transcoding, open dan Dashboard → Playback → Transcoding en stel het tijdelijke pad voor transcoding in op /cache/transcodes, zodat de tijdelijke bestanden op het cache-volume terechtkomen in plaats van /config te vullen. Laat hardwareversnelling op None staan; er is geen GPU beschikbaar voor versnelling.

Toegang op afstand: TLS-reverse proxy, of houd het op de VPN

Er zijn twee veilige manieren om Jellyfin van buitenaf te bereiken, en één onveilige methode die u moet vermijden. De onveilige methode is het direct openstellen van poort 8096 voor het internet: de inloggegevens worden in leesbare tekst verzonden en de poort wordt binnen enkele uren onderworpen aan brute-force-aanvallen.

Optie A, TLS-reverse proxy. Plaats Jellyfin op een subdomein achter Traefik met automatische TLS voor uw Docker-apps, of achter nginx met een Let's Encrypt-certificaat uitgegeven door Certbot. Jellyfin gebruikt WebSockets voor real-time updates, dus de proxy moet de upgrade-headers doorsturen. Traefik doet dit automatisch; nginx vereist dat deze expliciet worden gedefinieerd en heeft HTTP/1.1 nodig naar de upstream, anders vindt de upgrade nooit plaats:

location / {
    proxy_pass http://127.0.0.1:8096;
    proxy_http_version 1.1;
    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_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Stel JELLYFIN_PublishedServerUrl in op het https://-adres zodat lokale autodiscovery de juiste URL adverteert, externe apps het adres gebruiken dat u opgeeft, en voeg fail2ban toe om brute-force-pogingen op de inlogpagina te vertragen. Zodra de server publiek toegankelijk is, wijst u Uptime Kuma naar de URL zodat u op de hoogte bent van downtime voordat uw kijkers dat zijn. Stuur de notificaties naar een zelfgehoste ntfy-server zodat een mislukte controle als pushbericht op uw telefoon aankomt in plaats van als een e-mail die u pas de volgende ochtend leest. Het plaatsen van een inlogpagina op het openbare internet is ook een goed moment om de rest van de server te auditen in plaats van erop te vertrouwen dat alleen poort 443 reageert: sudo ss -tlnp toont elke luisterende poort en het bijbehorende proces. Als u ook eigen code op de server implementeert, scant open-kritt repositories en hun dependencies op kwetsbaarheden; dit controleert de broncode, niet de luisterende poorten.

Optie B, houd het privé via een VPN. Stel poort 8096 helemaal niet open voor het openbare internet; bereik Jellyfin alleen via een WireGuard-tunnel die op dezelfde server eindigt. Voor een huishouden is dit de eenvoudigste veilige keuze: geen certificaat, geen publieke blootstelling, geen aanvalsoppervlak voor brute-force. De localhost-binding uit het compose-bestand is hier op zichzelf niet voldoende, omdat een poort die op 127.0.0.1 is gepubliceerd alleen bereikbaar is vanaf de VPS zelf, niet vanaf VPN-peers. Publiceer deze in plaats daarvan op het tunneladres van de server (bijvoorbeeld "10.8.0.1:8096:8096", gebruikmakend van uw eigen WireGuard-server-IP), of behoud localhost en plaats een proxy die op het tunneladres luistert ervoor, en maak vervolgens verbinding via de VPN. Zie de WireGuard VPN-configuratie voor een privé-VPS voor de tunnel zelf.

Opslagcapaciteit en back-ups

Baseer uw budget op kwaliteit, niet op het aantal bestanden. Gecomprimeerde 1080p-films nemen elk 4-15 GB in beslag; een 1080p-remux 20-40 GB; een seizoen van een 1080p-serie 15-40 GB; alles in 4K is 40-100 GB per film. Een bibliotheek van enkele honderden films plus wat series vereist een volume van 2-4 TB. Het is goedkoper om het block-volume eenmalig ruim te dimensioneren dan om later te moeten migreren.

/config bevat de volledige serverstatus; dit is dus het enige onderdeel waarvan u een back-up moet maken. Maak een snapshot of stop de container en maak een tar-archief, en bewaar deze kopie buiten de server:

docker compose down
sudo tar czf jellyfin-config-$(date +%F).tgz -C ~/jellyfin config
docker compose up -d

/cache en de transcode-map zijn vervangbaar. De media op /mnt/media back-upt u afzonderlijk of accepteert u als herbruikbaar; de meeste gebruikers kiezen voor het laatste vanwege de omvang. Upgrades verlopen via docker compose pull && docker compose up -d; de bovenstaande :12-tag blijft binnen de 12.x-lijn. Overstappen naar de volgende hoofdversie is een bewuste wijziging van de tag. Lees de Jellyfin-release notes door voordat u dit doet, aangezien er bij hoofdversies migraties van het bibliotheekschema plaatsvinden. Jellyfin liet de voorloop "10." in zijn versienummers vallen met 12.0 (september 2026): 12.0 is wat voorheen 10.12 zou zijn geweest. Er is geen 11.x en 10.11.x was de laatste lijn volgens het oude schema. Als een ouder compose-bestand van u nog jellyfin/jellyfin:10 bevat, blijft dit bevroren op 10.11 (die tag werd voor het laatst gewijzigd op 2026-06-06, naar 10.11.11) en zal het nooit 12.x ophalen. Overstappen naar :12 is meer dan alleen een tag-wijziging: 12.0 wijzigt het databaseschema en herschrijft gegevens bij de eerste keer opstarten. Stop daarom de server en maak eerst de bovenstaande back-up, aangezien die back-up de enige weg terug is. 12.0 upgradet rechtstreeks vanaf 10.10.7 of elke 10.11.x-release. Daarna is een volledige bibliotheekscan vereist, wat merkbaar langer duurt dan gebruikelijk. Een vastgezette tag plus één back-up van de statusmap is het volledige recept voor elke altijd actieve container. Dit is hetzelfde patroon als achter het behouden van het geheugen en de planningen van een self-hosted agent na een herstart.

Foutmodi en de bijbehorende meldingen

Bibliotheek is leeg na een scan. Het logboek onder Dashboard → Logs (of ~/jellyfin/config/log/log_*.log) toont:

System.UnauthorizedAccessException: Access to the path '/media/Movies' is denied.

De uid van de container kan het pad niet lezen. Oorzaak: media is eigendom van root of een andere uid dan uw user:-waarde, een map mist het uitvoeringsrecht (execute bit), of de mount zelf is niet toegankelijk voor die uid. Oplossing: chown -R 1000:1000 /mnt/media, mappen 755, bestanden 644, en voer daarna een nieuwe scan uit.

Afspelen belast de CPU volledig en buffert. docker stats jellyfin toont een CPU-gebruik nabij 100% maal het aantal cores, en Dashboard → Playback vermeldt de sessie als Transcode met een snelheid lager dan 1.0x. De client speelt niet direct af, waardoor de VPS trager dan real-time transcodeert en achterblijft. Oorzaak: een niet-ondersteunde codec of container, het inbranden van ondertitels of HDR-tonemapping. Oplossing: schakel over naar een client die direct afspeelt, bewaar bronbestanden in H.264/AAC, gebruik tekst-ondertitels (SRT) in plaats van afbeeldings-ondertitels (PGS/VOBSUB) — die de meeste Jellyfin-clients niet zelf kunnen renderen en dus een inbrand-proces forceren — en vermijd 4K HDR volledig op een server zonder hardware-transcoding.

"No compatible streams are available." De volledige melding is meestal "This client isn't compatible with the media and the server isn't sending a compatible media format." De client wees de bron af en de fallback-transcode kon eveneens niet starten. Oorzaak: een defect ffmpeg-commando, een onleesbaar bestand of het gebruikersprofiel blokkeert videoconversie. Oplossing: lees de ffmpeg-regel in Dashboard → Logs, controleer of het bestand überhaupt afspeelbaar is, controleer de afspeelrechten van de gebruiker als u afhankelijk bent van transcoding, en probeer een tweede client om browser-specifieke codec-problemen uit te sluiten.

Films hebben geen poster of de verkeerde poster. De metadata kwam niet overeen. Oorzaak: een map- of bestandsnaam die niet overeenkomt met de titel zoals vermeld door uw metadata-provider, een remake of veelvoorkomende titel zonder jaartal om versies te onderscheiden, een seizoensmap genaamd S01 in plaats van Season 01, of afleveringen die niet in S01E01-formaat staan. Oplossing: hernoem naar de bovenstaande structuur en kies daarna Refresh metadata → Replace all, of gebruik Identify op een enkel item om de juiste TMDB/TVDB-vermelding te koppelen.

FAQ

Kan een VPS video transcoderen zonder GPU?

Ja, maar dit gebeurt uitsluitend via de CPU en is rekenintensief. Eén 1080p software-transcode kan meerdere vCPU's volledig belasten. Bij 4K of HEVC is real-time verwerking vaak niet haalbaar, wat leidt tot bufferen tijdens het afspelen. De beste aanpak is om transcodering te vermijden: bewaar uw bibliotheek in H.264/AAC en gebruik client-applicaties die direct-play ondersteunen, zodat de VPS enkel bytes streamt. Huur alleen een GPU-instantie als u daadwerkelijk on-the-fly transcodering nodig heeft.

Waarom is mijn Jellyfin-bibliotheek leeg na een scan?

Dit wordt bijna altijd veroorzaakt door toegangsrechten. De officiële jellyfin/jellyfin-image draait als de user: die u instelt (of root). Als de bestanden niet leesbaar zijn voor die uid, logt de scan Access to the path ... is denied en slaat deze bestanden over. Herstel het eigenaarschap met chown -R 1000:1000 /mnt/media, geef mappen het execute-bit (755) en voer de scan opnieuw uit. Controleer ook de bovenliggende mappen; als de uid van de container /mnt/media zelf niet kan doorlopen, bereikt deze nooit de bibliotheekmappen en blijft alles leeg. De op één na meest voorkomende oorzaak is een mappenstructuur die niet overeenkomt met wat Jellyfin verwacht.

Hoe krijg ik veilig op afstand toegang tot Jellyfin?

Er zijn twee goede opties. Plaats de service achter een TLS-reverse proxy op een subdomein zodat de inloggegevens en de stream versleuteld zijn, en voeg fail2ban toe. Stel nooit poort 8096 direct bloot aan het internet, aangezien wachtwoorden dan in leesbare tekst worden verzonden. Of houd de service volledig privé en benader deze enkel via een VPN; dit is de eenvoudigste veilige keuze voor thuisgebruik. Voer het publieke adres direct in de apps in, aangezien autodiscovery een lokaal netwerk-broadcast is die clients via het internet niet bereikt.

Hoeveel schijfruimte en bandbreedte heeft een Jellyfin-VPS nodig?

De benodigde schijfruimte hangt af van de kwaliteit: reken op 4-15 GB per gecomprimeerde 1080p-film, 20-40 GB per remux en 40-100 GB voor 4K. De meeste bibliotheken vereisen daarom een block volume van 2-4 TB. De bandbreedte wordt bepaald door de direct-play bitrate: 8-12 Mbps per 1080p-stream en aanzienlijk meer voor 4K. Controleer of uw poortsnelheid het aantal gelijktijdige kijkers aankan en houd rekening met de maandelijkse datalimiet. Zorg voor extra CPU-capaciteit als u van plan bent te transcoderen; geef prioriteit aan bandbreedte boven CPU-cores als u direct-play gebruikt.

Is het legaal om Jellyfin op een VPS te draaien?

Jellyfin zelf is vrije, open-source software en het gebruik ervan is volledig legaal. Waar het om gaat is de inhoud: stream alleen media die u bezit of waarvoor u een licentie heeft, zoals uw eigen disc-rips, opnames of bestanden waarvoor u de rechten heeft. Jellyfin levert geen media mee en biedt geen middelen om deze te verkrijgen; het is een speler voor een bibliotheek die u reeds in uw bezit heeft.