Einen Medienserver in Docker mit Compose betreiben

Das offizielle Image von Quven Server läuft unter Linux AMD64 und ARM64. Dies ist die Fassung Nur Server: Sie hat keinen Desktop-Client und stellt die Web-App nicht bereit. Diese Schritte führen Sie von einem leeren Verzeichnis zu einem verknüpften Server und anschließend durch die GPU-Profile und Updates.

Voraussetzungen

Anforderung	Was Quven erwartet
Host	Linux auf AMD64 oder ARM64
Container-Laufzeit	Docker Engine mit Docker Compose v2. Docker Desktop wird nicht unterstützt
Netzwerk	Host-Netzwerk, damit die Apps den Server im LAN finden
Mediathek	Ein Ordner, in den der Benutzer des Containers, uid 10001, schreiben kann, oder ein schreibgeschützter Mount
Hardwarebeschleunigung	Optional: das NVIDIA Container Toolkit, ein Intel- oder AMD-Render-Node oder ein V4L2-Gerät auf ARM

Docker Desktop bietet weder Host-Netzwerk noch LAN-Erkennung, über die Quven seine Clients erreicht. Ein bescheidener Rechner genügt, und die Anleitung zum selbst gehosteten Medienserver erklärt, ab wann eine Grafikkarte eine Rolle spielt.

1. Compose-Dateien herunterladen

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

Öffnen Sie .env und setzen Sie QUVEN_MEDIA_DIR auf den absoluten Pfad Ihrer Mediathek. Belassen Sie das Image auf ghcr.io/nickayl/quven:latest: Eine Versionsnummer an dieser Stelle hält den Server auf der genannten Version fest, wo ihn keine der späteren Korrekturen erreicht.

Das Volume quven-data enthält die Datenbank, die Konfiguration und die Protokolle, sodass Sie den Container neu erstellen können, ohne sie zu verlieren.

2. Server starten und Konto verknüpfen

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

Öffnen Sie die URL, die account link ausgibt, melden Sie sich bei Ihrem Quven-Konto an und bestätigen Sie den Server. Native Clients finden ihn im LAN, oder Sie verweisen sie auf http://<server-ip>:5181. Mit Pro erreicht ihn app.quven.tv zusätzlich über das verwaltete Relay.

Das Image läuft als UID/GID 10001, verwirft Linux-Capabilities, blockiert die Rechteausweitung und hält sein Root-Dateisystem schreibgeschützt. Machen Sie den Dienst nicht zu einem privilegierten Container, um ein Berechtigungsproblem auf dem Host zu umgehen.

3. Mediathek hinzufügen

Mediatheken werden über die Desktop-App von Quven auf einem beliebigen Computer im selben Netzwerk hinzugefügt oder mit Pro über app.quven.tv. Smartphones und Fernseher können keine anlegen, daher bleibt ein Server, der nur einen Fernseher-Client kennt, leer.

Wenn die App nach Ordnern fragt, wählen Sie sie unterhalb von /media: Eine Mediathek des Hosts unter /srv/media erscheint in Quven als /media.

Berechtigungen der Mediathek

Ihre Medien werden beschreibbar eingebunden, weil Quven die erzeugten Untertitel neben dem Film ablegt und auf Wunsch auch die Cover von Büchern und Alben; der Ordner muss daher für uid 10001 beschreibbar sein. Ohne Schreibzugriff schlägt die Kopie mit einer Warnung im Serverprotokoll fehl, und der Untertitel wird weiterhin aus dem eigenen Speicher von Quven im Datenvolume abgespielt.

So verhindern Sie, dass der Server jemals in die Mediathek schreibt:

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

Sie verzichten lediglich auf die Kopie, die mit der Datei mitwandert, wenn Sie sie verschieben.

Eine Mediathek aus symbolischen Links

Quven folgt symbolischen Links innerhalb einer Mediathek, sofern der Container das Ziel unter dem Pfad sieht, den der Link angibt. Ein Link auf /mnt/decypharr/film.mkv ist in einem Container, dem nur /media übergeben wurde, nicht erreichbar. Binden Sie das Ziel unter demselben Pfad im selben Dienst neben dem Medien-Mount ein:

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

Prüfen Sie, was der Container lesen kann, bevor Sie eine ganze Mediathek scannen:

docker compose exec quven ls /mnt/decypharr

Hardwarebeschleunigung

Spielen Sie zuerst einen Titel über den Basisdienst ab, denn damit sind Netzwerk, Mediathek und Kontopfad bestätigt, bevor eine GPU ins Spiel kommt. Fügen Sie dann ein einziges Override hinzu, und zwar dasjenige, das zu einer Schnittstelle passt, die Sie auf dem Host gesehen haben. Die Optionen sind Alternativen: Kombinieren Sie sie nicht, außer wenn das Raspberry-Pi-Profil die V4L2-Basis verlangt.

NVIDIA

Bei installiertem NVIDIA Container Toolkit:

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

Das Profil 1.5.7 fordert die GPU mit runtime: nvidia an. Jede Compose-Version akzeptiert das, sobald das Container Toolkit seine Laufzeitumgebung registriert hat:

nvidia-ctk runtime configure --runtime=docker

Ein Host, der statt dieser Laufzeitumgebung für CDI eingerichtet ist, entfernt diesen Schlüssel und fordert die GPU mit gpus: all an, was ältere Compose-Versionen ablehnen. Lassen Sie NVIDIA_DRIVER_CAPABILITIES wie veröffentlicht: Ohne die Fähigkeit video stellt der Treiber kein NVENC bereit, und der Server kodiert ohne Hinweis in Software.

Intel oder AMD

Übergeben Sie die Gruppen-IDs render und video des Hosts an den Container:

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

Wenn die richtige GPU nicht /dev/dri/renderD128 ist, setzen Sie QUVEN_DRI_RENDER_DEVICE in .env, mit demselben Pfad innerhalb und außerhalb des Containers.

Raspberry Pi oder andere ARM-Boards

Dies ist eine fortgeschrittene Einrichtung, und der Basisdienst spielt die meisten Mediatheken bereits gut ab. Hosts, die V4L2-M2M-Codecs bereitstellen, können compose.v4l2m2m.yaml verwenden. Ein Raspberry Pi 4 kann zusätzlich compose.raspberry-pi.yaml für die HEVC-Dekodierung über die Request API hinzufügen. Beide Profile benötigen die tatsächlichen Gerätepfade, die das System meldet, und starten nicht, wenn die Einrichtung unvollständig ist.

Prüfen Sie zuerst die Schnittstellen und geben Sie niemals das gesamte /dev frei:

v4l2-ctl --list-devices

Neue Dateien automatisch scannen

Öffnen Sie die Einstellungen, dann die Registerkarte Server und dann die Karte Automatisches Scannen. Sie ist in Pro, Max und Lifetime enthalten und hat vier Schalter, die alle beim Speichern ohne Neustart übernommen werden:

• Neue Dateien in den Ordnern erkennen: startet einen inkrementellen Scan etwa dreißig Sekunden, nachdem sich die letzte Datei nicht mehr ändert. Er erzwingt nie eine neue Zuordnung und verbraucht kein KI-Guthaben.
• Periodischer Scan: scannt jede Mediathek einmal täglich, sofern Sie kein anderes Intervall wählen, und überspringt eine Mediathek, die bereits gescannt wird.
• Cover jedes Buchs neben seiner Datei speichern: schreibt das Cover unter demselben Namen neben das Buch, Dune.jpg neben Dune.epub, und behält ein bereits im Ordner vorhandenes Bild bei.
• Cover jedes Albums in seinem Ordner speichern: schreibt das in den Aufnahmen enthaltene Cover als cover.jpg, sofern der Ordner nicht bereits ein Bild enthält.

Ein Bind-Mount eines lokalen Laufwerks wird direkt überwacht. Eine über SMB oder NFS eingebundene Freigabe kann nicht überwacht werden, da der Kernel nicht sieht, was ein anderer Rechner dort schreibt. Daher vergleicht Quven diese Ordner alle fünf Minuten mit ihrem letzten Snapshot, und die Karte zeigt Polling an. Ein als nicht erreichbar angezeigter Ordner ist einer, den der Container unter diesem Pfad nicht öffnen kann; der Tooltip der Zeile nennt den Grund. Führen Sie nach dem Verschieben eines ganzen Ordners einen manuellen Scan aus.

Update

1. Notieren Sie den verwendeten Digest, damit Sie wissen, wohin Sie zurückkehren würden.

2. Stoppen Sie den Dienst und kopieren Sie das Datenvolume, .env und die Compose-Dateien. Löschen Sie diese niemals während eines Updates oder eines Rollbacks.

3. Laden und starten Sie die aktuelle Version:

   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. Prüfen Sie den Status und spielen Sie dann einen Titel per direkter Wiedergabe und einen, der transkodiert werden muss, ab.

Eine Version kann das Datenbankschema ändern, und ein älteres Image kann keine Datenbank lesen, die ein neueres bereits migriert hat. Die Rückkehr zu einem früheren Digest in QUVEN_IMAGE bedeutet daher, auch die Datenbank wiederherzustellen – aus Ihrer eigenen Kopie des Volumes oder aus dem Snapshot, den der Server vor einer Schemaänderung darin unter backups/quven-pre-migration-<timestamp>.db ablegt. Nur der neueste Snapshot wird aufbewahrt, da jeder neue den vorherigen ersetzt.

Überprüfen, was Sie ausführen

Das Image ist signiert und enthält eine SPDX-Attestierung:

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

Das öffentliche Manifest der Version 1.5.7 enthält den Digest des Image-Index und den jeder Plattform. Bewahren Sie es neben der von Ihnen freigegebenen Konfiguration auf.

Häufig gestellte Fragen