Ejecuta un servidor multimedia en Docker con Compose

La imagen oficial de Quven Server funciona en Linux AMD64 y ARM64. Es la edición Solo servidor: no tiene cliente de escritorio ni aloja la aplicación web. Estos pasos te llevan de un directorio vacío a un servidor vinculado y, después, por los perfiles de GPU y las actualizaciones.

Requisitos

Requisito	Lo que espera Quven
Host	Linux en AMD64 o ARM64
Entorno de contenedores	Docker Engine con Docker Compose v2. Docker Desktop no es compatible
Red	La red del host, para que las aplicaciones encuentren el servidor en la red local
Biblioteca	Una carpeta en la que pueda escribir el usuario del contenedor, uid 10001, o un montaje de solo lectura
Aceleración por hardware	Opcional: el NVIDIA Container Toolkit, un nodo de renderizado Intel o AMD, o un dispositivo V4L2 en ARM

Docker Desktop no puede ofrecer la red del host ni el descubrimiento en la red local, que es como Quven llega a sus clientes. Basta con un equipo modesto, y la guía del servidor multimedia autoalojado explica cuándo empieza a importar una tarjeta gráfica.

1. Descarga los archivos de 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

Abre .env y establece QUVEN_MEDIA_DIR con la ruta absoluta de tu biblioteca. Deja la imagen en ghcr.io/nickayl/quven:latest: un número de versión en ese lugar fija el servidor en la versión que indica, donde no puede alcanzarlo ninguna de las correcciones posteriores.

El volumen quven-data contiene la base de datos, la configuración y los registros, así que puedes volver a crear el contenedor sin perderlos.

2. Inícialo y vincula tu cuenta

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

Abre la dirección que muestra account link, inicia sesión en tu cuenta de Quven y aprueba el servidor. Los clientes nativos lo encuentran en la red local, o puedes indicarles http://<server-ip>:5181. Con Pro, app.quven.tv también llega a él a través del relé gestionado.

La imagen se ejecuta con el UID/GID 10001, descarta las capacidades de Linux, bloquea la escalada de privilegios y mantiene su sistema de archivos raíz en solo lectura. No conviertas el servicio en un contenedor con privilegios para sortear un problema de permisos del host.

3. Añade una biblioteca

Las bibliotecas se añaden desde la aplicación de escritorio de Quven, en cualquier ordenador de la misma red, o desde app.quven.tv con Pro. Los teléfonos y los televisores no pueden crearlas, así que un servidor que solo conoce un cliente de televisor se queda vacío.

Cuando la aplicación pida carpetas, elígelas por debajo de /media: una biblioteca del host situada en /srv/media aparece dentro de Quven como /media.

Permisos de la biblioteca

Tus medios se montan con permiso de escritura, porque Quven escribe los subtítulos que genera junto a la película, y las portadas de libros y álbumes cuando se lo pides, así que el uid 10001 tiene que poder escribir en la carpeta. Sin permiso de escritura, la copia falla con una advertencia en el registro del servidor, y el subtítulo sigue reproduciéndose desde el almacenamiento propio de Quven, en el volumen de datos.

Para que el servidor no escriba nunca en la biblioteca:

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

Solo renuncias a la copia que acompaña al archivo si lo mueves.

Una biblioteca hecha de enlaces

Quven sigue los enlaces simbólicos dentro de una biblioteca, siempre que el contenedor vea el destino en la ruta que nombra el enlace. Un enlace que apunta a /mnt/decypharr/film.mkv es inalcanzable dentro de un contenedor al que solo se le dio /media. Monta el destino en la misma ruta, en el mismo servicio, junto al montaje de los medios:

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

Comprueba lo que puede leer el contenedor antes de analizar una biblioteca entera:

docker compose exec quven ls /mnt/decypharr

Aceleración por hardware

Reproduce primero un título en el servicio base, porque así compruebas la red, la biblioteca y la ruta de la cuenta antes de que entre en juego una GPU. Después añade un solo archivo de anulación, el que corresponde a una interfaz que hayas visto en el host. Las opciones son alternativas: no las combines, salvo cuando el perfil de Raspberry Pi pide la base V4L2.

NVIDIA

Con el NVIDIA Container Toolkit instalado:

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

El perfil 1.5.7 solicita la GPU con runtime: nvidia, que todas las versiones de Compose aceptan una vez que el Container Toolkit ha registrado su entorno de ejecución:

nvidia-ctk runtime configure --runtime=docker

Un host configurado para CDI en lugar de ese entorno de ejecución elimina esa clave y solicita la GPU con gpus: all, que las versiones antiguas de Compose rechazan. Mantén NVIDIA_DRIVER_CAPABILITIES tal como se publica: sin la capacidad video, el controlador no ofrece NVENC y el servidor codifica por software sin avisarte.

Intel o AMD

Pasa al contenedor los identificadores de los grupos render y video del 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

Si la GPU correcta no es /dev/dri/renderD128, establece QUVEN_DRI_RENDER_DEVICE en .env, con la misma ruta dentro y fuera del contenedor.

Raspberry Pi u otras placas ARM

Es una configuración avanzada, y el servicio base ya reproduce bien la mayoría de las bibliotecas. Los hosts que exponen códecs V4L2 M2M pueden usar compose.v4l2m2m.yaml. Una Raspberry Pi 4 también puede añadir compose.raspberry-pi.yaml para la decodificación HEVC mediante la Request API. Ambos perfiles necesitan las rutas de dispositivo reales que indica el sistema y se niegan a arrancar cuando la configuración está incompleta.

Inspecciona primero las interfaces y no expongas nunca todo /dev:

v4l2-ctl --list-devices

Analiza automáticamente los archivos nuevos

Abre Settings, luego la pestaña Server y luego la tarjeta Automatic scanning. Está incluida en Pro, Max y Lifetime y tiene cuatro interruptores, todos aplicados al guardar, sin reiniciar:

• Detect new files in the folders: inicia un análisis incremental unos treinta segundos después de que el último archivo deja de cambiar. Nunca fuerza una nueva identificación ni gasta créditos de IA.
• Periodic scan: analiza cada biblioteca una vez al día, salvo que elijas otro intervalo, y omite una biblioteca que ya se está analizando.
• Save each book’s cover beside its file: escribe la portada junto al libro con el mismo nombre, Dune.jpg junto a Dune.epub, y conserva una imagen que ya esté en la carpeta.
• Save each album’s cover in its folder: escribe como cover.jpg la portada que llevan las pistas, salvo que la carpeta ya contenga una imagen.

Un montaje vinculado de un disco local se vigila directamente. Un recurso compartido montado por SMB o NFS no se puede vigilar, porque el núcleo no ve lo que otro equipo escribe en él, así que Quven compara esas carpetas con su última instantánea cada cinco minutos y la tarjeta las marca con Polling. Una carpeta que aparece como inalcanzable es una que el contenedor no puede abrir en esa ruta, y la información emergente de la fila explica el motivo. Después de mover una carpeta entera, ejecuta un análisis manual.

Actualiza

1. Anota el digest en uso, para saber a qué volverías.

2. Detén el servicio y copia el volumen de datos, .env y los archivos de Compose. No los elimines nunca durante una actualización o una vuelta atrás.

3. Descarga e inicia la versión actual:

   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. Comprueba el estado y luego reproduce un título en reproducción directa y otro que deba transcodificarse.

Una versión puede cambiar el esquema de la base de datos, y una imagen anterior no puede leer una base de datos que una más reciente ya haya migrado. Por eso, volver a un digest anterior en QUVEN_IMAGE obliga a restaurar también la base de datos, desde tu propia copia del volumen o desde la instantánea que el servidor escribe en él, en backups/quven-pre-migration-<timestamp>.db, antes de un cambio de esquema. Solo se conserva la instantánea más reciente, porque cada una nueva sustituye a la anterior.

Verifica lo que ejecutas

La imagen está firmada y lleva una atestación 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

El manifiesto público de la versión 1.5.7 contiene el digest del índice de imágenes y el de cada plataforma. Guárdalo junto a la configuración que aprobaste.

Preguntas frecuentes