Jellyfin 12 con Docker Compose: media server self-hosted

Vuoi guardare film e serie TV, ascoltare musica e consultare i tuoi contenuti da smartphone, TV o browser senza affidare la libreria a una piattaforma proprietaria? Jellyfin 12 è un media server open source e self-hosted che puoi installare sul tuo server Linux con Docker Compose.

In questa guida vediamo come installare Jellyfin 12 con Docker Compose, aggiungere una libreria multimediale, configurare l’accesso da altri dispositivi e proteggere i dati con un backup. Troverai anche una sezione dedicata a chi deve aggiornare un’installazione precedente: il passaggio alla versione 12 richiede alcune precauzioni importanti.

Cos’è Jellyfin 12

Jellyfin è un software per organizzare e riprodurre contenuti multimediali conservati sul proprio server. Puoi creare librerie per film, serie TV, musica, foto e libri, gestire utenti separati e accedere ai contenuti tramite browser e applicazioni compatibili.

La versione 12, rilasciata a settembre 2026, migliora le prestazioni di diverse operazioni sulle librerie e sulle playlist. Introduce inoltre funzionalità più complete per libri e fumetti, tra cui una migliore gestione dei metadati e della lettura nell’interfaccia web.

A differenza di un servizio di streaming commerciale, Jellyfin non fornisce un catalogo di film o musica: organizza e distribuisce i file che possiedi e che hai il diritto di utilizzare.

Prerequisiti

Per seguire la guida servono:

• un server Linux (consigliamo Debian 13 o Ubuntu Server 26.04), un VPS, un NAS compatibile oppure un mini PC;
• Docker Engine e il plugin Docker Compose;
• spazio disco sufficiente per i contenuti e per i dati dell’applicazione;
• file multimediali da aggiungere alle librerie;
• la porta 8096/TCP disponibile sulla rete in cui userai Jellyfin.

La procedura usa l’immagine ufficiale jellyfin/jellyfin. Su host Windows e macOS, il progetto consiglia invece l’installazione nativa: l’esecuzione in container su queste piattaforme non è ufficialmente supportata e può presentare limitazioni.

1. Crea cartelle e librerie

Collegati al server tramite terminale e crea una cartella dedicata a Jellyfin:

mkdir -p ~/jellyfin/{config,cache}
mkdir -p ~/jellyfin/media/{Film,Serie,Musica,Libri}
cd ~/jellyfin

Le directory hanno scopi diversi:

• config contiene configurazione, database, utenti e metadati di Jellyfin;
• cache contiene dati temporanei che Jellyfin può rigenerare;
• media contiene i tuoi film, le serie, la musica e i libri.

Se i tuoi contenuti si trovano già su un altro disco, non devi copiarli in ~/jellyfin/media: potrai sostituire il percorso del volume nel file Compose con quello reale, per esempio /mnt/archivio/media.

2. Verifica UID e GID

Jellyfin deve poter leggere i file multimediali e scrivere nelle cartelle config e cache. Per eseguire il container con il tuo utente Linux, controlla i relativi identificativi:

id -u
id -g

Annota i due numeri mostrati. Nei passaggi seguenti li inseriremo nel file .env.

Se utilizzi un disco montato o un NAS, verifica anche i permessi di lettura delle cartelle che conterranno i media. Evita di cambiare proprietario ricorsivamente a un archivio già esistente senza sapere quali altri servizi lo utilizzano.

3. Crea il file .env

Dalla cartella ~/jellyfin, crea il file delle variabili:

nano .env

Inserisci UID e GID ottenuti in precedenza. Nell’esempio entrambi valgono 1000, ma sul tuo sistema potrebbero essere diversi:

JELLYFIN_UID=1000
JELLYFIN_GID=1000

Salva il file prima di proseguire.

4. Crea il file docker-compose.yml

Crea il file Compose:

nano docker-compose.yml

Incolla questa configurazione:

services:
  jellyfin:
    image: jellyfin/jellyfin:12.0
    container_name: jellyfin
    user: "${JELLYFIN_UID}:${JELLYFIN_GID}"
    restart: unless-stopped
    ports:
      - "8096:8096/tcp"
      - "7359:7359/udp"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - ./media:/media:ro

Il tag 12.0 segue gli aggiornamenti della serie 12.0 senza passare automaticamente a una futura versione principale. Prima di ogni aggiornamento è comunque opportuno leggere le note di rilascio e creare un backup.

La porta 8096/TCP serve per l’accesso HTTP. La porta 7359/UDP è usata per il rilevamento del server da parte dei client nella rete locale: è facoltativa e non deve essere inoltrata verso Internet.

Il volume ./media:/media:ro monta i file multimediali in sola lettura. Jellyfin potrà riprodurli e catalogarli senza modificare gli originali. Se desideri che Jellyfin scriva file direttamente nelle cartelle dei media, dovrai valutare separatamente se rimuovere :ro.

5. Avvia Jellyfin 12

Controlla prima la configurazione Compose:

docker compose config

Se non vengono segnalati errori, avvia il servizio:

docker compose up -d

Controlla lo stato del container:

docker compose ps

Se Jellyfin non parte o la pagina non si apre, leggi i log:

docker compose logs -f jellyfin

6. Completa la configurazione iniziale

Apri un browser su un dispositivo della stessa rete e visita:

http://IP-DEL-SERVER:8096

Segui la procedura guidata di Jellyfin: scegli la lingua dell’interfaccia, crea un account amministratore con una password robusta e imposta le librerie multimediali.

Quando Jellyfin chiede il percorso di una libreria, usa i percorsi interni al container, non quelli del server host:

• Film: /media/Film;
• Serie TV: /media/Serie;
• Musica: /media/Musica;
• Libri: /media/Libri.

Per ogni cartella seleziona il tipo di contenuto corretto. Puoi creare le librerie anche in un secondo momento dal pannello di amministrazione.

7. Organizza i file multimediali

Una struttura ordinata aiuta Jellyfin a riconoscere titoli, stagioni ed episodi e a recuperare i metadati corretti. Per esempio:

media/
├── Film/
│   └── Esempio Film (2024)/
│       └── Esempio Film (2024).mkv
├── Serie/
│   └── Serie di esempio (2023)/
│       └── Season 01/
│           └── Serie di esempio (2023) S01E01.mkv
├── Musica/
│   └── Artista/
│       └── Album/
│           └── 01 - Brano.flac
└── Libri/
    └── Autore/
        └── Libro.epub

Per i film è consigliabile usare una cartella per ogni titolo e includere l’anno quando noto. Dopo aver aggiunto i file, aggiorna la libreria dall’interfaccia di Jellyfin per avviare la scansione.

Se la libreria appare vuota, controlla innanzitutto che i file siano effettivamente presenti nel percorso montato e che l’UID/GID configurato possa leggerli.

8. Accedi da TV e smartphone

Una volta avviato il server, puoi collegare client compatibili presenti nella stessa rete. Se il dispositivo non rileva Jellyfin automaticamente, inserisci manualmente l’indirizzo:

http://IP-DEL-SERVER:8096

La scoperta automatica usa la rete locale: in alcune configurazioni Docker, VLAN o firewall potrebbe non funzionare anche se il server è raggiungibile normalmente dal browser. In quel caso, l’inserimento manuale dell’indirizzo è la soluzione più semplice.

9. Attiva la transcodifica hardware

Se un client non supporta direttamente il formato di un video, Jellyfin può convertirlo durante la riproduzione. Questa operazione si chiama transcodifica e può richiedere molte risorse CPU.

Su un server Linux con GPU Intel o AMD compatibile, puoi valutare l’accelerazione hardware. Verifica prima che il dispositivo sia disponibile sull’host:

ls -l /dev/dri

Se il dispositivo esiste, aggiungi al servizio jellyfin nel file Compose:

    devices:
      - /dev/dri:/dev/dri

Se esegui il container con un utente non root, può essere necessario aggiungere anche il GID del gruppo che ha accesso al dispositivo di rendering. Controllalo sull’host con:

getent group render

In quel caso, aggiungi al servizio un valore group_add corrispondente al GID reale, per esempio:

    group_add:
      - "122"

Il numero 122 è solo un esempio: non copiarlo senza verificarlo sul tuo server. Dopo la modifica, esegui docker compose up -d e seleziona il metodo di accelerazione appropriato dal pannello di Jellyfin, nella sezione dedicata alla riproduzione e alla transcodifica.

Per GPU NVIDIA serve invece una configurazione diversa, che comprende driver e NVIDIA Container Toolkit sull’host. Non aggiungere opzioni GPU al file Compose se non hai prima verificato hardware, driver e permessi.

10. Usare Jellyfin fuori casa

Per l’accesso remoto hai due possibilità comuni: una VPN oppure l’esposizione tramite reverse proxy e HTTPS. Evita di inoltrare direttamente la porta 8096 dal router a Internet.

Se usi Nginx Proxy Manager, puoi creare un Proxy Host con:

• Domain Names: jellyfin.example.com;
• Scheme: http;
• Forward Hostname / IP: IP locale del server Jellyfin;
• Forward Port: 8096;
• Websockets Support: attivo.

Richiedi poi un certificato SSL per il dominio e abilita il reindirizzamento a HTTPS. Se Nginx Proxy Manager e Jellyfin condividono una rete Docker, puoi usare il nome del servizio jellyfin come host e la porta interna 8096.

Nel pannello di Jellyfin, configura anche l’indirizzo del reverse proxy tra i Known Proxies nelle impostazioni di rete. In questo modo Jellyfin può interpretare correttamente gli header inoltrati dal proxy e distinguere gli IP dei client.

Se vuoi approfondire l’argomento, leggi anche la nostra guida su Nginx Proxy Manager con Docker Compose e SSL.

11. Backup di Jellyfin

Un media server self-hosted richiede backup regolari. Per ripristinare Jellyfin non basta conservare il file docker-compose.yml: devi salvare almeno la cartella config e i tuoi file multimediali.

La cartella cache contiene dati rigenerabili e in genere non è essenziale per il ripristino. Se fai backup manuali dei file di configurazione e del database, arresta prima Jellyfin per ottenere una copia coerente:

cd ~/jellyfin
docker compose down

tar -czf "$HOME/jellyfin-config-$(date +%F).tar.gz" \
  docker-compose.yml .env config

docker compose up -d

Il comando precedente non salva i file in media. Prevedi quindi un backup separato della libreria, preferibilmente su un altro disco o in un’altra posizione. Non conservare l’unica copia di sicurezza sullo stesso server.

12. Aggiornare a Jellyfin 12

Attenzione: questa sezione riguarda solo chi possiede già un’installazione Jellyfin precedente. Se hai seguito la guida dall’inizio e hai creato una nuova istanza con l’immagine jellyfin/jellyfin:12.0, non devi eseguire una migrazione.

Jellyfin 12 modifica lo schema del database e riscrive dati al primo avvio. Il progetto avverte che, dopo la migrazione, tornare alla versione precedente richiede il ripristino di un backup completo precedente all’aggiornamento.

Prima di aggiornare:

1. Verifica la versione attuale: devi partire da Jellyfin 10.10.7 oppure da una versione 10.11.x. Da versioni più vecchie devi passare prima a 10.10.7.
2. Arresta Jellyfin ed esegui un backup manuale completo dei dati e della configurazione. Salva anche il file Compose usato dall’installazione corrente.
3. Rimuovi i plugin di terze parti non ancora compatibili con Jellyfin 12.
4. Verifica che non esistano utenti i cui nomi differiscano soltanto per maiuscole e minuscole.
5. Solo dopo questi controlli, aggiorna il tag dell’immagine nel file Compose, scarica l’immagine e riavvia il container.

Per applicare l’aggiornamento, dalla cartella della tua installazione esistente:

docker compose pull
docker compose up -d
docker compose logs -f jellyfin

Le migrazioni iniziali possono impiegare tempo: non interrompere il server mentre sono in corso. Una volta terminato l’avvio, esegui una scansione completa delle librerie, richiesta dalla versione 12 per ricostruire correttamente alcune informazioni sui contenuti. Se l’interfaccia mostra anomalie, prova anche a svuotare la cache del browser o a ricaricare la pagina forzatamente.

Se la tua vecchia installazione usa un’immagine diversa da quella ufficiale o percorsi dei volumi differenti, non sostituire il vecchio Compose con quello di questa guida: conserva le mappature originali e pianifica la migrazione in base alla configurazione effettiva.

Problemi comuni

Jellyfin non vede film o serie

Controlla che i file si trovino davvero nella directory montata come /media, che la libreria punti al percorso interno corretto e che l’utente del container abbia permesso di lettura.

La porta 8096 è già occupata

Modifica soltanto la porta esposta sull’host, per esempio 8097:8096/tcp. In questo caso accederai a Jellyfin tramite http://IP-DEL-SERVER:8097.

Il container parte ma il client non trova il server

Prova a inserire manualmente l’indirizzo del server. Il rilevamento automatico può essere limitato dalla configurazione della rete Docker, dal firewall o dalla separazione tra VLAN.

La riproduzione video consuma troppa CPU

Controlla se Jellyfin sta effettuando una transcodifica invece della riproduzione diretta. Se disponi di una GPU supportata, valuta l’accelerazione hardware e verifica i permessi del dispositivo nel container.

Conclusioni

Con Jellyfin 12 e Docker Compose puoi creare un media server self-hosted per organizzare e riprodurre i tuoi contenuti da browser, smartphone e TV. L’installazione di base richiede un solo container, ma vale la pena curare fin dall’inizio permessi, struttura delle cartelle, accesso remoto e backup.

Se stai aggiornando un server già in uso, tratta il passaggio alla versione 12 come una vera migrazione: leggi le note di rilascio, conserva una copia completa dei dati e pianifica il tempo necessario alla prima scansione delle librerie.

FAQ su Jellyfin 12

Jellyfin 12 è gratuito?

Sì. Jellyfin è un software open source che puoi installare sul tuo server. Hardware, spazio di archiviazione e connettività restano a tuo carico.

Posso installare Jellyfin 12 con Docker Compose?

Sì. Il progetto distribuisce un’immagine Docker ufficiale e documenta l’installazione con Docker Compose su host Linux.

Quale porta usa Jellyfin?

Per impostazione predefinita l’interfaccia HTTP usa la porta 8096/TCP. La porta 7359/UDP è utilizzata per il rilevamento del server nella rete locale.

Jellyfin 12 richiede un database esterno?

No. Per la configurazione di questa guida non sono necessari container PostgreSQL o MariaDB: Jellyfin salva i propri dati nella directory persistente montata come /config.

Come accedo a Jellyfin fuori casa?

Puoi usare una VPN oppure un dominio con reverse proxy e HTTPS. Evita di esporre direttamente la porta 8096 su Internet e non esporre la porta UDP di rilevamento all’esterno.

Posso aggiornare direttamente da Jellyfin 10 a Jellyfin 12?

Dipende dalla versione esatta. Il progetto supporta il passaggio da 10.10.7 e da qualsiasi 10.11.x; se usi una versione precedente devi aggiornare prima a 10.10.7. Esegui sempre un backup completo prima della migrazione.

Quali cartelle devo includere nel backup?

Salva almeno la configurazione e i dati di Jellyfin nella cartella config, il file Compose e la libreria multimediale. La cartella cache contiene dati generalmente rigenerabili.