Un buon container dovrebbe farsi dimenticare. Quven Server vive accanto alla tua libreria, conserva il proprio stato tra un aggiornamento e l’altro e lascia i file multimediali esattamente dove sono. L’immagine ufficiale porta questa esperienza su Linux AMD64 e ARM64, con una configurazione ripetibile e senza rinunciare all’accelerazione hardware.
È un’edizione Server-only: non include il client desktop e non ospita la web app. Serve Docker Engine su Linux con Docker Compose v2. Docker Desktop non è supportato, perché il collegamento con i client Quven usa la rete dell’host e la discovery sulla LAN.
Parti da una base ripetibile
Dedica una cartella a Quven e scarica i file Compose della release 1.1.22. Sono versionati: la stessa configurazione continuerà a puntare alla stessa immagine anche dopo una nuova pubblicazione.
mkdir -p quven && cd quven
curl -fsSLO https://quven.tv/docker/1.1.22/compose.yaml
curl -fsSL https://quven.tv/docker/1.1.22/env.example -o .envApri .env e assegna a QUVEN_MEDIA_DIR il percorso assoluto della tua libreria. Il file punta già a ghcr.io/nickayl/quven:v1.1.22: lascia il tag versionato al suo posto. Usare latest renderebbe ogni riavvio una sorpresa.
Database, configurazione e log vivono nel volume quven-data; il container può essere ricreato senza perderli. I media entrano in scrittura, perché Quven scrive accanto al film i sottotitoli che genera. Quella cartella deve essere scrivibile dall’uid 10001, l’utente con cui gira il container.
Quando Quven trascrive, traduce, riconosce o modifica un sottotitolo, tiene il risultato nel proprio archivio dentro il volume dati, e ogni client lo riproduce da lì. Ne scrive anche una copia accanto al video, così il testo viaggia insieme al film se lo sposti su un’altra macchina o passi la cartella a qualcun altro. Se l’uid 10001 non può scrivere in quella cartella, la copia fallisce e l’unica traccia è un avviso nel log del server. Il sottotitolo non ne risente e si riproduce normalmente; semplicemente non si trova nella cartella accanto al film.
Se preferisci che il server non tocchi la tua libreria, imposta QUVEN_MEDIA_READ_ONLY=true in .env e ricrea il container con docker compose up -d. Quven catalogherà e riprodurrà i media senza scriverci dentro nulla, e l’unica cosa a cui rinunci è quella seconda copia. È uno scambio fra una garanzia e una comodità, e quale delle due valga di più dipende dalla tua installazione.
Se la tua libreria è fatta di collegamenti
Quven segue i collegamenti simbolici dentro una libreria, quindi una cartella di media che contiene link verso un mount remoto viene letta come i film a cui puntano. C’è una condizione, ed è quella su cui si inciampa: il container deve vedere il target allo stesso percorso che il collegamento nomina. Un link che dice /mnt/decypharr/film.mkv non significa niente dentro un container a cui è stata data solo /media, e tutti quei collegamenti verranno segnalati come irraggiungibili a fine scansione.
Monta anche il target, sotto il percorso con cui viene nominato, come hai montato la radice dei media:
- type: bind
source: /mnt/decypharr
target: /mnt/decypharrDove va il secondo montaggio? Sotto volumes:, accanto al primo, nello stesso servizio. Se preferisci controllare prima di scansionare una libreria intera, esegui docker compose exec quven ls /mnt/decypharr e guarda se il container riesce a leggere ciò a cui puntano i tuoi collegamenti.
Accendi il server
Prima chiedi a Compose di validare la configurazione, poi scarica l’immagine e avvia il servizio. L’ultimo comando genera il collegamento sicuro al tuo Quven 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 linkApri l’URL mostrato da account link, accedi al tuo Quven Account e approva il server. Da quel momento i client nativi possono trovarlo sulla LAN oppure collegarsi a http://<ip-server>:5181. Con Pro, anche app.quven.tv può raggiungerlo attraverso il relay gestito.
Le librerie si aggiungono dall’app desktop di Quven, da un qualunque computer della stessa rete, oppure da app.quven.tv se hai Pro. Una TV o un telefono non possono crearle. Riproducono solo quello che un desktop ha già preparato, ed è per questo che un server che incontra soltanto un client TV resta vuoto e la prima cosa da installare è l’app desktop su un computer di casa. Quando te lo chiede, scegli le cartelle sotto /media: una libreria host in /srv/media appare in Quven come /media.
L’immagine gira come UID/GID 10001, senza capability Linux, senza elevazione dei privilegi e con il filesystem radice in sola lettura. Queste protezioni fanno parte del prodotto. Non trasformare il servizio in un container privilegiato per aggirare un permesso errato sull’host.
Affida il video all’hardware giusto
Avvia prima un contenuto con il profilo base. Saprai così che rete, libreria e account funzionano prima di aggiungere la GPU. Poi applica un solo override, quello corrispondente a un’interfaccia realmente presente sull’host.
Scegli un solo profilo. Le opzioni qui sotto sono alternative: NVIDIA, Intel/AMD oppure ARM. Non eseguire tutti i blocchi e non sommare gli override, salvo quando il profilo Raspberry Pi richiede esplicitamente la base V4L2.
Profilo NVIDIA
Con NVIDIA Container Toolkit installato, aggiungi il profilo dedicato e ricrea il servizio:
curl -fsSLO https://quven.tv/docker/1.1.22/compose.nvidia.yaml
docker compose -f compose.yaml -f compose.nvidia.yaml config
docker compose -f compose.yaml -f compose.nvidia.yaml up -dIl profilo 1.1.22 chiede la GPU con runtime: nvidia, la forma che ogni versione di Compose accetta dopo che il Container Toolkit ha registrato il proprio runtime (nvidia-ctk runtime configure --runtime=docker). Un host configurato per CDI anziché per quel runtime toglie la chiave e chiede con gpus: all, che le versioni più vecchie di Compose rifiutano in blocco: è la ragione per cui non è la forma pubblicata. Lascia NVIDIA_DRIVER_CAPABILITIES come pubblicato: senza la capability video il driver iniettato non porta NVENC e il server codifica in software senza dirlo.
Profilo Intel o AMD
Per una GPU Intel o AMD, individua il render node e passa al container i GID dei gruppi render e video dell’host:
curl -fsSLO https://quven.tv/docker/1.1.22/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 -dSe la GPU corretta non è /dev/dri/renderD128, imposta QUVEN_DRI_RENDER_DEVICE in .env. Il percorso deve restare identico dentro e fuori dal container: mascherare un render node con il nome di un altro rende la diagnosi ambigua.
Profilo Raspberry Pi o ARM avanzato
Questa è una configurazione avanzata. Se Quven riproduce bene i tuoi contenuti, non devi aggiungere nulla.
Per i dispositivi che espongono codec V4L2 M2M è disponibile il profilo compose.v4l2m2m.yaml. Raspberry Pi 4 può aggiungere anche compose.raspberry-pi.yaml per il decode HEVC tramite Request API. Entrambi richiedono i percorsi reali dei device mostrati dal sistema e si rifiutano di partire se la configurazione è incompleta.
Non indovinare i nodi e non esporre tutto /dev. Su hardware ARM o NAS diverso, verifica prima le interfacce disponibili con v4l2-ctl --list-devices. Il profilo base resta sempre la scelta sicura e mantiene il decode software quando l’accelerazione non è utilizzabile.
Aggiorna senza giocarti la libreria
Un aggiornamento deve essere noioso. Scarica il nuovo bundle versionato, leggilo, registra il digest in uso e soltanto dopo esegui docker compose pull e docker compose up -d.
Copia il volume quven-data a servizio fermo, insieme a .env e ai file Compose, prima di ogni aggiornamento: sono il tuo punto di ripartenza e non vanno mai eliminati durante un update o un rollback. La copia serve perché una release può cambiare lo schema del database, e un’immagine più vecchia non sa leggere un database che una più recente ha già migrato. Rimettere il digest precedente in QUVEN_IMAGE significa quindi ripristinare anche il database: la tua copia del volume, oppure lo snapshot che il server scrive al suo interno in backups/quven-pre-migration-<data>.db prima di applicare modifiche allo schema. Vengono conservati i cinque snapshot più recenti.
Dopo ogni modifica, controlla la health e riproduci sia un titolo in direct play sia uno che richieda transcodifica.
Verifica cosa stai eseguendo
L’immagine Quven è firmata e accompagnata da un’attestazione SPDX. Con Cosign puoi verificare la release esatta prima che raggiunga la tua libreria:
curl -fsSLO https://quven.tv/docker/1.1.22/cosign-public-key.pem
cosign verify --key cosign-public-key.pem ghcr.io/nickayl/quven:v1.1.22
cosign verify-attestation --key cosign-public-key.pem --type spdxjson ghcr.io/nickayl/quven:v1.1.22Il manifest pubblico della 1.1.22 contiene il digest dell’image index e quelli delle singole piattaforme. È il riferimento da conservare insieme alla configurazione che hai approvato.
Domande frequenti
Posso usare Docker Desktop?
No. Quven raggiunge i suoi client con host networking e discovery sulla LAN, che Docker Desktop non offre. Serve Docker Engine su Linux con Docker Compose v2.
Meglio fissare la versione o seguire latest?
Fissala. Il bundle Compose è legato a una release pubblicata invece che a un tag mobile, così riavviare il server non può trasformarsi di nascosto in un aggiornamento, e il digest pubblicato dice cosa è arrivato davvero, non cosa avevi chiesto.
Quven scrive nella mia cartella dei media?
Solo i sottotitoli che genera per te, accanto al film a cui appartengono. Non ci finisce altro, e una scansione non scrive niente. Se preferisci che non la tocchi mai, metti QUVEN_MEDIA_READ_ONLY=true nel .env e ricrea il container. Quven conserva quei sottotitoli nel proprio volume e li serve comunque, quindi l’unica cosa che perdi è la copia che viaggia insieme al file.
Quale profilo hardware aggiungo?
Uno solo, e solo dopo aver visto l’interfaccia corrispondente sull’host. Riproduci un titolo con il servizio base, poi aggiungi l’override NVIDIA, Intel/AMD o ARM che corrisponde a ciò che hai osservato. Attivarne più di uno produce una configurazione che sembra comoda e cede al primo file difficile.