Media server in Docker: avvio con Docker Compose

L’immagine ufficiale di Quven Server gira su Linux AMD64 e ARM64. È l’edizione Server-only: non ha un client desktop e non ospita l’app web. Questi passaggi ti portano da una cartella vuota a un server collegato, poi ai profili GPU e agli aggiornamenti.

Requisiti

Requisito	Cosa richiede Quven
Host	Linux su AMD64 o ARM64
Runtime dei container	Docker Engine con Docker Compose v2. Docker Desktop non è supportato
Rete	Rete host, così le app trovano il server nella rete locale
Libreria	Una cartella su cui l’utente del container, uid 10001, può scrivere, oppure un mount in sola lettura
Accelerazione hardware	Facoltativa: NVIDIA Container Toolkit, un nodo di rendering Intel o AMD, o un dispositivo V4L2 su ARM

Docker Desktop non offre la rete host né il rilevamento nella rete locale, che sono il modo in cui Quven raggiunge i suoi client. Basta una macchina modesta, e la guida al media server self-hosted spiega quando una scheda grafica comincia a contare.

1. Scarica i file Compose

mkdir -p quven && cd quven
curl -fsSLO https://quven.tv/docker/1.5.7/compose.yaml
curl -fsSL https://quven.tv/docker/1.5.7/env.example -o .env

Apri .env e imposta QUVEN_MEDIA_DIR sul percorso assoluto della tua libreria. Lascia l’immagine su ghcr.io/nickayl/quven:latest: un numero di versione scritto lì blocca il server sulla versione che nomina, dove nessuna delle correzioni successive può raggiungerlo.

Il volume quven-data contiene il database, la configurazione e i registri, quindi puoi ricreare il container senza perderli.

2. Avvialo e collega il tuo account

docker compose config
docker compose pull
docker compose up -d
docker compose ps
curl --fail --silent --show-error http://127.0.0.1:5181/health/container -o /dev/null
docker compose exec quven /app/Quven.Local.Server account link

Apri l’indirizzo che account link mostra, accedi al tuo Quven Account e approva il server. I client nativi lo trovano nella rete locale, oppure puoi indicare loro http://<ip-del-server>:5181. Con Pro, anche app.quven.tv lo raggiunge tramite il relay gestito.

L’immagine gira come UID/GID 10001, rimuove le capacità Linux, blocca l’escalation dei privilegi e tiene il file system radice in sola lettura. Non trasformare il servizio in un container privilegiato per aggirare un problema di permessi dell’host.

3. Aggiungi una libreria

Le librerie si aggiungono dall’app desktop Quven su un computer qualsiasi della stessa rete, oppure da app.quven.tv con Pro. Telefoni e televisori non possono crearle, quindi un server che incontra solo un client per televisore resta vuoto.

Quando l’app chiede le cartelle, scegli quelle sotto /media: una libreria dell’host in /srv/media compare in Quven come /media.

Permessi della libreria

I tuoi file multimediali sono montati in scrittura, perché Quven scrive i sottotitoli che genera accanto al film, e le copertine di libri e album quando lo chiedi, quindi la cartella deve essere scrivibile da uid 10001. Senza accesso in scrittura la copia fallisce con un avviso nel registro del server, e il sottotitolo si riproduce comunque dall’archivio di Quven nel volume dei dati.

Per impedire al server di scrivere nella libreria:

echo 'QUVEN_MEDIA_READ_ONLY=true' >> .env
docker compose up -d

Rinunci soltanto alla copia che viaggia con il file se lo sposti.

Una libreria fatta di collegamenti

Quven segue i collegamenti simbolici dentro una libreria, purché il container veda la destinazione al percorso che il collegamento nomina. Un collegamento che indica /mnt/decypharr/film.mkv è irraggiungibile in un container a cui è stato dato solo /media. Monta la destinazione con lo stesso percorso, nello stesso servizio, accanto al mount dei file multimediali:

volumes:
  - type: bind
    source: /mnt/decypharr
    target: /mnt/decypharr

Controlla cosa riesce a leggere il container prima di analizzare un’intera libreria:

docker compose exec quven ls /mnt/decypharr

Accelerazione hardware

Riproduci prima un titolo con il servizio di base: dimostra la rete, la libreria e il percorso dell’account prima che entri in gioco una GPU. Poi aggiungi un solo override, quello che corrisponde a un’interfaccia che hai visto sull’host. Le opzioni sono alternative: non combinarle, tranne dove il profilo Raspberry Pi richiede la base V4L2.

NVIDIA

Con NVIDIA Container Toolkit installato:

curl -fsSLO https://quven.tv/docker/1.5.7/compose.nvidia.yaml
docker compose -f compose.yaml -f compose.nvidia.yaml config
docker compose -f compose.yaml -f compose.nvidia.yaml up -d

Il profilo 1.5.7 chiede la GPU con runtime: nvidia, che ogni versione di Compose accetta dopo che il Container Toolkit ha registrato il suo runtime:

nvidia-ctk runtime configure --runtime=docker

Un host configurato per CDI al posto di quel runtime elimina quella chiave e chiede la GPU con gpus: all, che le versioni più vecchie di Compose rifiutano. Lascia NVIDIA_DRIVER_CAPABILITIES come pubblicato: senza la capacità video il driver non include NVENC, e il server codifica in software senza avvisarti.

Intel o AMD

Passa al container gli ID dei gruppi render e video dell’host:

curl -fsSLO https://quven.tv/docker/1.5.7/compose.vaapi.yaml
echo 'QUVEN_RENDER_GID='"$(getent group render | cut -d: -f3)" >> .env
echo 'QUVEN_VIDEO_GID='"$(getent group video | cut -d: -f3)" >> .env
docker compose -f compose.yaml -f compose.vaapi.yaml config
docker compose -f compose.yaml -f compose.vaapi.yaml up -d

Se la GPU giusta non è /dev/dri/renderD128, imposta QUVEN_DRI_RENDER_DEVICE in .env, con lo stesso percorso dentro e fuori dal container.

Raspberry Pi e altre schede ARM

È una configurazione avanzata, e il servizio di base riproduce già bene la maggior parte delle librerie. Gli host che espongono i codec V4L2 M2M possono usare compose.v4l2m2m.yaml. Un Raspberry Pi 4 può aggiungere anche compose.raspberry-pi.yaml per la decodifica HEVC con l’API Request. Entrambi i profili richiedono i percorsi reali dei dispositivi indicati dal sistema e non partono se la configurazione è incompleta.

Controlla prima le interfacce, e non esporre mai tutto /dev:

v4l2-ctl --list-devices

Analizza i nuovi file in automatico

Apri Impostazioni, poi la scheda Server, poi la scheda Scansione automatica. È inclusa in Pro, Max e Lifetime e ha quattro interruttori, tutti applicati al salvataggio, senza riavvio:

• Rileva i nuovi file nelle cartelle: avvia una scansione incrementale circa trenta secondi dopo che l’ultimo file smette di cambiare. Non forza mai un nuovo abbinamento e non spende crediti IA.
• Scansione periodica: analizza ogni libreria una volta al giorno, salvo un altro intervallo, e salta una libreria già in scansione.
• Salva la copertina di ogni libro accanto al file: scrive la copertina accanto al libro con lo stesso nome, Dune.jpg accanto a Dune.epub, e lascia com’è un’immagine già presente nella cartella.
• Salva la copertina di ogni album nella sua cartella: scrive come cover.jpg la copertina che portano le tracce, a meno che la cartella non contenga già un’immagine.

Un mount di un disco locale viene controllato direttamente. Una condivisione montata via SMB o NFS non si può controllare, perché il kernel non vede ciò che un’altra macchina scrive lì, quindi Quven confronta quelle cartelle con l’ultimo stato rilevato ogni cinque minuti e la scheda indica il polling. Una cartella segnalata come irraggiungibile è una che il container non riesce ad aprire a quel percorso, e il suggerimento della riga ne indica il motivo. Dopo aver spostato un’intera cartella, avvia una scansione manuale.

Aggiorna

1. Annota il digest in uso, così sai a cosa torneresti.

2. Ferma il servizio e copia il volume dei dati, .env e i file Compose. Non eliminarli mai durante un aggiornamento o un ripristino.

3. Scarica e avvia la versione attuale:

   docker compose stop
   docker volume ls --filter name=quven-data
   docker run --rm -v <nome-volume>:/data -v "$PWD":/backup alpine tar czf /backup/quven-data.tgz -C /data .
   docker compose pull
   docker compose up -d

4. Controlla lo stato di salute, poi riproduci un titolo in direct play e uno che deve essere transcodificato.

Una versione può cambiare lo schema del database, e un’immagine più vecchia non può leggere un database già migrato da una più recente. Tornare a un digest precedente in QUVEN_IMAGE significa quindi ripristinare anche il database, da una tua copia del volume o dall’istantanea che il server scrive in backups/quven-pre-migration-<timestamp>.db al suo interno prima di un cambio di schema. Viene conservata solo l’istantanea più recente, perché ogni nuova sostituisce la precedente.

Verifica ciò che esegui

L’immagine è firmata e porta un’attestazione SPDX:

curl -fsSLO https://quven.tv/docker/1.5.7/cosign-public-key.pem
cosign verify --key cosign-public-key.pem ghcr.io/nickayl/quven:latest
cosign verify-attestation --key cosign-public-key.pem --type spdxjson ghcr.io/nickayl/quven:latest

Il manifesto pubblico 1.5.7 contiene il digest dell’indice dell’immagine e quello di ogni piattaforma. Conservalo accanto alla configurazione che hai approvato.

Domande frequenti