Exécuter un serveur multimédia dans Docker avec Compose

L’image officielle de Quven Server fonctionne sur Linux AMD64 et ARM64. Il s’agit de l’édition Serveur seul : elle ne comporte pas de client de bureau et n’héberge pas l’application web. Ces étapes vous mènent d’un répertoire vide à un serveur lié, puis vous guident à travers les profils GPU et les mises à jour.

Prérequis

Prérequis	Ce que Quven attend
Hôte	Linux sur AMD64 ou ARM64
Environnement de conteneurs	Docker Engine avec Docker Compose v2. Docker Desktop n’est pas pris en charge
Réseau	Le réseau de l’hôte, pour que les applications trouvent le serveur sur le réseau local
Bibliothèque	Un dossier dans lequel l’utilisateur du conteneur, uid 10001, peut écrire, ou un montage en lecture seule
Accélération matérielle	Facultative : le NVIDIA Container Toolkit, un nœud de rendu Intel ou AMD, ou un périphérique V4L2 sur ARM

Docker Desktop ne peut offrir ni le réseau de l’hôte ni la découverte sur le réseau local, qui sont la façon dont Quven atteint ses clients. Une machine modeste suffit, et le guide du serveur multimédia auto-hébergé explique à partir de quand une carte graphique commence à compter.

1. Télécharger les fichiers 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

Ouvrez .env et réglez QUVEN_MEDIA_DIR sur le chemin absolu de votre bibliothèque. Laissez l’image sur ghcr.io/nickayl/quven:latest : un numéro de version à cet endroit fige le serveur sur la version qu’il désigne, où aucune des corrections ultérieures ne peut l’atteindre.

Le volume quven-data contient la base de données, la configuration et les journaux : vous pouvez donc recréer le conteneur sans les perdre.

2. Le démarrer et lier votre compte

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

Ouvrez l’adresse qu’affiche account link, connectez-vous à votre compte Quven et approuvez le serveur. Les clients natifs le trouvent sur le réseau local, ou vous pouvez les diriger vers http://<server-ip>:5181. Avec Pro, app.quven.tv l’atteint également par le relais géré.

L’image s’exécute sous l’UID/GID 10001, supprime les capacités Linux, bloque l’élévation de privilèges et garde son système de fichiers racine en lecture seule. Ne transformez pas le service en conteneur privilégié pour contourner un problème de permissions sur l’hôte.

3. Ajouter une bibliothèque

Les bibliothèques s’ajoutent depuis l’application de bureau Quven, sur n’importe quel ordinateur du même réseau, ou depuis app.quven.tv avec Pro. Les téléphones et les téléviseurs ne peuvent pas en créer : un serveur qui ne rencontre qu’un client de téléviseur reste donc vide.

Quand l’application demande des dossiers, choisissez-les sous /media : une bibliothèque de l’hôte située dans /srv/media apparaît dans Quven sous /media.

Permissions de la bibliothèque

Vos médias sont montés en écriture, car Quven écrit les sous-titres qu’il génère à côté du film, ainsi que les couvertures des livres et les pochettes des albums si vous le demandez : le dossier doit donc être accessible en écriture à l’uid 10001. Sans accès en écriture, la copie échoue avec un avertissement dans le journal du serveur, et le sous-titre se lit toujours depuis le stockage propre à Quven, dans le volume de données.

Pour empêcher le serveur d’écrire un jour dans la bibliothèque :

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

Vous ne renoncez qu’à la copie qui accompagne le fichier si vous le déplacez.

Une bibliothèque faite de liens

Quven suit les liens symboliques à l’intérieur d’une bibliothèque, à condition que le conteneur voie la cible au chemin que nomme le lien. Un lien qui indique /mnt/decypharr/film.mkv est inaccessible dans un conteneur auquel on n’a donné que /media. Montez la cible sous le même chemin, dans le même service, à côté du montage des médias :

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

Vérifiez ce que le conteneur peut lire avant d’analyser une bibliothèque entière :

docker compose exec quven ls /mnt/decypharr

Accélération matérielle

Lisez d’abord un titre sur le service de base : cela valide le réseau, la bibliothèque et le chemin du compte avant qu’un GPU n’entre en jeu. Ajoutez ensuite une seule surcharge, celle qui correspond à une interface que vous avez constatée sur l’hôte. Les options sont des alternatives : ne les combinez pas, sauf lorsque le profil Raspberry Pi demande la base V4L2.

NVIDIA

Avec le NVIDIA Container Toolkit installé :

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

Le profil 1.5.7 demande le GPU avec runtime: nvidia, que toutes les versions de Compose acceptent une fois que le Container Toolkit a enregistré son environnement d’exécution :

nvidia-ctk runtime configure --runtime=docker

Un hôte configuré pour CDI plutôt que pour cet environnement d’exécution retire cette clé et demande le GPU avec gpus: all, que les anciennes versions de Compose refusent. Gardez NVIDIA_DRIVER_CAPABILITIES tel qu’il est publié : sans la capacité video, le pilote ne fournit pas NVENC, et le serveur encode en logiciel sans vous le signaler.

Intel ou AMD

Transmettez au conteneur les identifiants des groupes render et video de l’hôte :

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

Si le bon GPU n’est pas /dev/dri/renderD128, réglez QUVEN_DRI_RENDER_DEVICE dans .env, avec le même chemin à l’intérieur et à l’extérieur du conteneur.

Raspberry Pi ou autres cartes ARM

Il s’agit d’une configuration avancée, et le service de base lit déjà bien la plupart des bibliothèques. Les hôtes qui exposent des codecs V4L2 M2M peuvent utiliser compose.v4l2m2m.yaml. Un Raspberry Pi 4 peut aussi ajouter compose.raspberry-pi.yaml pour le décodage HEVC par la Request API. Les deux profils exigent les chemins de périphériques réels que signale le système et refusent de démarrer lorsque la configuration est incomplète.

Inspectez d’abord les interfaces, et n’exposez jamais l’ensemble de /dev :

v4l2-ctl --list-devices

Analyser automatiquement les nouveaux fichiers

Ouvrez Paramètres, puis l’onglet Serveur, puis la carte Analyse automatique. Elle est incluse dans Pro, Max et Lifetime et comporte quatre interrupteurs, tous appliqués à l’enregistrement, sans redémarrage :

• Détecter les nouveaux fichiers dans les dossiers : lance une analyse incrémentale environ trente secondes après que le dernier fichier a cessé de changer. Elle ne force jamais une nouvelle identification et ne dépense aucun crédit d’IA.
• Analyse périodique : analyse chaque bibliothèque une fois par jour, sauf si vous choisissez un autre intervalle, et ignore une bibliothèque déjà en cours d’analyse.
• Enregistrer la couverture de chaque livre à côté du fichier : écrit la couverture à côté du livre sous le même nom, Dune.jpg à côté de Dune.epub, et conserve une image déjà présente dans le dossier.
• Enregistrer la pochette de chaque album dans son dossier : écrit sous le nom cover.jpg la pochette que portent les pistes, sauf si le dossier contient déjà une image.

Un montage lié d’un disque local est surveillé directement. Un partage monté par SMB ou NFS ne peut pas être surveillé, car le noyau ne voit pas ce qu’une autre machine y écrit : Quven compare donc ces dossiers à leur dernier instantané toutes les cinq minutes, et la carte les signale par la mention Sondage. Un dossier signalé comme injoignable est un dossier que le conteneur ne peut pas ouvrir à ce chemin, et l’info-bulle de la ligne en donne la raison. Après avoir déplacé un dossier entier, lancez une analyse manuelle.

Mettre à jour

1. Notez l’empreinte (digest) en service, afin de savoir à quoi vous reviendriez.

2. Arrêtez le service et copiez le volume de données, .env et les fichiers Compose. Ne les supprimez jamais pendant une mise à jour ou un retour en arrière.

3. Récupérez et démarrez la version actuelle :

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

4. Vérifiez l’état de santé, puis lisez un titre en lecture directe et un titre qui doit être transcodé.

Une version peut modifier le schéma de la base de données, et une image plus ancienne ne peut pas lire une base qu’une image plus récente a déjà migrée. Revenir à une empreinte antérieure dans QUVEN_IMAGE implique donc de restaurer aussi la base de données, à partir de votre propre copie du volume ou de l’instantané que le serveur y écrit sous backups/quven-pre-migration-<timestamp>.db avant un changement de schéma. Seul le dernier instantané est conservé, car chaque nouvel instantané remplace le précédent.

Vérifier ce que vous exécutez

L’image est signée et porte une attestation 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

Le manifeste public de la version 1.5.7 contient l’empreinte de l’index d’images et celle de chaque plateforme. Conservez-le à côté de la configuration que vous avez validée.

Questions fréquentes