Instalar medialab Server (Jellyfin 12.2) con Docker Compose o apt

Por qué cambiar ahora

Si ejecutas Jellyfin en tu propio hardware, seguramente hayas seguido la publicación 12.2. medialab Server es nuestra variante de Jellyfin 12.2: las mismas bibliotecas, usuarios y apps, con nuestros plugins verificados integrados y MediaLab TV incluido. Es software libre bajo la GPL-2.0, sin clave de licencia y con el código fuente público.

Esto no es una migración. Las apps de Jellyfin para Android, iOS, TV y la web se conectan exactamente igual que a Jellyfin oficial. Lo que cambia es el hogar donde viven tus plugins: nuestro catálogo se añade automáticamente, nuestros plugins muestran Verified – medialab y van primeros entre los sintonizadores de TV en directo, las fuentes de guía y los proveedores de subtítulos, y puedes reordenar esa lista cuando quieras.

A continuación tienes dos formas de entrar —una pila jellyfin docker compose y los paquetes apt en Debian 12— además de lo primero que debes hacer: una copia de seguridad.

Antes de empezar: la puerta de un solo sentido

En el primer arranque, la base de datos de Jellyfin se actualiza al formato 12.2. Un Jellyfin anterior ya no puede volver a abrir esa base de datos. No hay vuelta atrás para los datos en sí, así que trata esto como una actualización de un solo sentido.

Por tanto, antes que nada:

• Haz una copia de seguridad de los ajustes y los datos. En una instalación con contenedor eso significa toda la carpeta /config; con apt, /etc/jellyfin y /var/lib/jellyfin.
• Guarda la copia en un lugar al que el servidor no pueda acceder y anota qué versión de Jellyfin estabas ejecutando.
• Si tienes usuarios cuyos nombres solo se diferencian en mayúsculas y minúsculas, revísalos antes de la actualización. La documentación lo señala como un punto a verificar antes de cambiar.

Hazlo y el resto es rutina.

Requisitos previos

• Una máquina de 64 bits x86 o ARM. Ubuntu vale para el contenedor.
• Para la ruta del contenedor: Docker (o Podman, Unraid, Portainer, Kubernetes), una carpeta para /config, otra para /cache, tu carpeta de medios y el PUID/PGID numérico de la cuenta que debe ser propietaria de los ajustes (id -u, id -g).
• Para la ruta de apt: Debian 12 (bookworm), amd64 o arm64. Los paquetes necesitan bibliotecas de Debian 12, así que no se instalan en Ubuntu: ahí usa el contenedor.
• Tus datos actuales de Jellyfin, con copia de seguridad.

Paso 1: Instalar con Docker Compose

La imagen es ghcr.io/cristiancasapu/medialab-server, compilada para linux/amd64 y linux/arm64 a partir de los mismos paquetes Debian firmados que el repositorio apt.

Crea un compose.yaml:

services:
  medialab-server:
    image: ghcr.io/cristiancasapu/medialab-server:12.2-ml.10
    container_name: medialab-server
    restart: unless-stopped
    ports:
      - "8096:8096"
      - "7359:7359/udp"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /srv/media:/media:ro
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Europe/Bucharest
      MLW_SERVER_NAME: Home media
      MLW_ADMIN_USER: admin
      MLW_ADMIN_PASSWORD_FILE: /run/secrets/admin_password
    secrets:
      - admin_password

secrets:
  admin_password:
    file: ./secrets/admin_password

Después:

mkdir -p secrets && printf '%s' 'a-long-password' > secrets/admin_password
docker compose up -d
docker compose logs -f

Algunas notas sobre las etiquetas: 12.2-ml.10 fija una versión concreta (recomendado si quieres elegir cuándo actualizar), 12.2 sigue la última versión 12.2 y latest la última versión en general. La etiqueta 12.2-ml10-deb12 nombra la versión apt exacta que hay dentro de la imagen.

Las variables de administrador solo funcionan en un servidor nuevo; en uno ya configurado se ignoran. La contraseña nunca aparece en los logs del contenedor, por eso va en un archivo y no en la línea de comandos. En el repositorio hay un ejemplo completo con un archivo .env (examples/compose.yaml, examples/.env.example).

En Unraid, añade un contenedor y pon la URL de la plantilla en el archivo medialab-server.xml de la carpeta examples/unraid/ del repositorio (o cópialo a /boot/config/plugins/dockerMan/templates-user/), comprueba que /config apunta a /mnt/user/appdata/medialab-server y /media a tu recurso compartido de medios, usa PUID 99 y PGID 100, y añade --device=/dev/dri en Extra Parameters si tienes una GPU Intel o AMD. Portainer y Kubernetes funcionan con la misma imagen y los mismos volúmenes.

Paso 2: Instalar con apt en Debian 12

Los paquetes vienen de https://apt.medialab.works/debian. Primero añade el repositorio, que se distribuye como paquete firmado:

curl -fsSLO https://apt.medialab.works/medialab-repo.deb
sudo apt install ./medialab-repo.deb

Eso crea /etc/apt/sources.list.d/medialab.sources e instala la clave de firma. Si prefieres hacerlo a mano, descarga la clave en /usr/share/keyrings/medialab-archive-keyring.gpg y comprueba la huella: debe ser 6B7D 46D8 2C3C 4D4C 0A14 2F92 4189 96EB 3CE1 59C7, de "medialab Server packages packages@medialab.works". Después escribe el mismo archivo medialab.sources. apt comprueba la firma en cada apt update.

Instala:

sudo apt update
sudo apt install medialab-server medialab-server-web jellyfin-ffmpeg8

medialab-server sustituye a jellyfin-server y medialab-server-web sustituye a jellyfin-web. Si Jellyfin ya está instalado desde el repositorio de Jellyfin, apt elimina esos dos paquetes y conserva tus datos, porque medialab Server usa las mismas carpetas. Si el repositorio de Jellyfin sigue configurado, apt mantiene instalados los paquetes de medialab; puedes quitar el repositorio antiguo cuando ya no lo necesites.

El servidor se ejecuta como el servicio habitual jellyfin bajo el usuario jellyfin:

sudo systemctl status jellyfin
sudo systemctl restart jellyfin
sudo journalctl -u jellyfin -f

Las rutas son las de siempre: /etc/jellyfin para los ajustes, /var/lib/jellyfin para la base de datos, los plugins y los metadatos, /var/log/jellyfin, /var/cache/jellyfin, /etc/default/jellyfin para las opciones de arranque, /usr/share/jellyfin/web para la interfaz web y /usr/lib/jellyfin-ffmpeg/ffmpeg. Para cambiar el usuario del servicio u otras opciones de systemd, usa sudo systemctl edit jellyfin. Para la transcodificación por hardware en una GPU Intel o AMD, el paquete añade el usuario jellyfin a los grupos render y video.

Paso 3: Primer arranque y comprobaciones

Abre http://<server>:8096. En un servidor nuevo, el asistente de configuración te pide el primer administrador, el idioma y tus bibliotecas desde /media. En uno existente, tus datos ya están ahí, así que repásalos:

• Bibliotecas: las rutas siguen resolviéndose y los escaneos terminan.
• Usuarios: todos pueden iniciar sesión y no hay dos nombres que solo se diferencien en mayúsculas y minúsculas.
• Plugins: nuestro catálogo se añade solo y nuestros plugins muestran Verified – medialab; el servidor comprueba sus firmas y señala un plugin modificado después de su publicación.
• Aceleración por hardware: confirma que la transcodificación funciona y que los grupos render/video (apt) o /dev/dri (contenedor) están en su sitio.

MediaLab TV, incluido

Desde 12.2-ml.8 la app de TV forma parte del servidor, gratis: sin plugin y sin suscripción aparte. En un televisor sin app de Jellyfin, abre https://<server>:8096/web/tv/ o usa la entrada MediaLab TV del menú de los usuarios y tendrás la interfaz al estilo Netflix: Continuar viendo, A continuación, bibliotecas, Mi lista, TV en directo, páginas de títulos, búsqueda con teclado en pantalla y perfiles, con su propio reproductor para pistas de audio, subtítulos, reanudar y Saltar intro / resumen / créditos.

Los ajustes están en el menú de los usuarios, en MediaLab TV – admin: nombre, logo (PNG/SVG), colores, idioma, ruta de acceso y Turnstile. Si tenías instalado el plugin jf-tvapp, el servidor asume sus ajustes, su logo y su clave de Turnstile y deja de cargar el plugin; las mismas direcciones siguen funcionando. En Jellyfin oficial, MediaLab TV sigue siendo el plugin jf-tvapp.

Actualizar y volver atrás

• Contenedor: descarga la nueva etiqueta 12.2-ml.N y recrea el contenedor; los ajustes de /config se mantienen.
• apt: sudo apt update && sudo apt upgrade, o usa el plugin Self-Update desde la interfaz web.

Cada versión aparece en el changelog. Para volver a Jellyfin oficial, reinstala sus paquetes o su imagen sobre los mismos datos, pero recuerda que la base de datos ya está en formato 12.2, así que necesitas un Jellyfin oficial que pueda abrirla. Por eso precisamente la copia de seguridad va primero.

Consejos y solución de problemas

• Conserva la copia de seguridad hasta que todo te convenza. La actualización de la base de datos es de un solo sentido; una copia de /config (o de /etc/jellyfin más /var/lib/jellyfin) es tu única vuelta atrás.
• Ubuntu y apt no se mezclan aquí. Los paquetes necesitan bibliotecas de Debian 12; en Ubuntu, usa la imagen de contenedor.
• Primero los logs. docker compose logs -f para contenedores, sudo journalctl -u jellyfin -f para apt.
• Permisos. Un PUID/PGID incorrecto se manifiesta como medios ilegibles o un /config en el que no se puede escribir.
• El orden de los plugins es tuyo. Nuestros plugins van primero entre sintonizadores, fuentes de guía y proveedores de subtítulos, pero puedes cambiar el orden en cualquier momento.

Conclusión

medialab Server es la actualización menos dramática que puedes hacer: las mismas apps, los mismos datos, las mismas carpetas — con Jellyfin 12.2 debajo, nuestros plugins verificados delante y MediaLab TV integrado. Haz la copia de seguridad, elige Docker Compose o apt y arráncalo. La página del producto y la guía de usuario cubren los detalles, y la base de conocimiento tiene los artículos completos sobre contenedor y apt. ¿Dudas? La FAQ y la página de contacto están abiertas.