Cómo instalar Jellyfin con Docker paso a paso

Instalar Jellyfin con Docker permite convertir un ordenador, servidor doméstico o NAS compatible en una plataforma privada para reproducir películas, series, música y fotografías. Los archivos permanecen bajo tu control y puedes acceder a ellos desde televisores, móviles, navegadores y otros dispositivos compatibles.

Docker mantiene Jellyfin y sus dependencias dentro de un contenedor, simplificando la instalación, el mantenimiento y las actualizaciones. Sin embargo, la configuración, la caché y los metadatos deben guardarse en volúmenes persistentes para que no desaparezcan cuando se recree el contenedor.

Esta guía utiliza Ubuntu Server con Docker Compose y la imagen oficial de Jellyfin. El procedimiento también puede adaptarse a otras distribuciones Linux, aunque los comandos de instalación y la gestión de permisos pueden variar.

Qué necesitas para instalar Jellyfin con Docker

Antes de comenzar, necesitas los siguientes componentes:

• Un servidor o equipo con una distribución Linux compatible.
• Docker Engine y el complemento Docker Compose.
• Una dirección IP fija o una reserva DHCP para el servidor.
• Espacio suficiente para la configuración, la caché y las transcodificaciones temporales.
• Acceso de lectura a las carpetas donde se almacenan los archivos multimedia.
• Una conexión de red estable, preferiblemente mediante Ethernet.

La instalación en contenedores está oficialmente orientada a Linux. Aunque Docker Desktop permite ejecutar contenedores en Windows y macOS, Jellyfin advierte de que algunas funciones, especialmente la transcodificación acelerada por hardware, pueden no funcionar correctamente en esos sistemas.

Qué hardware necesita un servidor Jellyfin

Los requisitos dependen menos del tamaño de la biblioteca que del tipo de reproducción. Cuando el dispositivo cliente admite el formato, el códec, el audio, los subtítulos y el bitrate del archivo, Jellyfin puede utilizar reproducción directa. En ese caso, el servidor apenas procesa el vídeo y puede funcionar en equipos modestos.

La carga aumenta cuando Jellyfin debe convertir el contenido en tiempo real. Esto puede ocurrir por un códec incompatible, subtítulos que deban incrustarse, un bitrate excesivo o la necesidad de convertir HDR a SDR. Por tanto, no existe una cantidad de núcleos o memoria que sirva para todos los usuarios.

Para varias transcodificaciones simultáneas resulta recomendable utilizar una GPU integrada Intel compatible con Quick Sync, una GPU NVIDIA compatible con NVENC o determinados modelos de AMD. También debes tener en cuenta el ancho de banda de subida si quieres acceder a Jellyfin fuera de casa.

Si todavía estás eligiendo el equipo y el almacenamiento, conviene valorar si necesitas un ordenador dedicado, un mini PC o un NAS doméstico.

Cómo instalar Docker Engine en Ubuntu Server

Actualiza primero los paquetes del sistema:

sudo apt update
sudo apt upgrade -y

Instala las herramientas necesarias y añade la clave oficial de Docker:

sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

A continuación, configura el repositorio oficial:

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Instala Docker Engine y el complemento de Compose:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

Comprueba que ambos componentes estén disponibles:

sudo docker run --rm hello-world
sudo docker compose version

Opcionalmente, puedes añadir tu usuario al grupo docker para ejecutar los comandos sin sudo:

sudo usermod -aG docker "$USER"

Cierra la sesión y vuelve a entrar para aplicar el cambio. Ten presente que pertenecer al grupo docker concede privilegios equivalentes a los de administrador sobre el sistema. No añadas usuarios que no sean de confianza.

Cómo preparar las carpetas persistentes

Crea una carpeta dedicada para el archivo de composición, la configuración y la caché:

sudo mkdir -p /opt/jellyfin/config
sudo mkdir -p /opt/jellyfin/cache
sudo chown -R "$(id -u)":"$(id -g)" /opt/jellyfin
cd /opt/jellyfin

Las carpetas multimedia pueden estar en otro disco. Esta sería una estructura sencilla:

/srv/media/
├── peliculas/
├── series/
└── musica/

No es obligatorio utilizar estas rutas. Lo importante es distinguir entre la ruta existente en el servidor anfitrión y la ruta que posteriormente verá Jellyfin dentro del contenedor.

Obtén el UID y el GID del usuario que ejecutará Jellyfin:

id -u
id -g

Crea un archivo llamado .env dentro de /opt/jellyfin y guarda los valores obtenidos:

JELLYFIN_UID=1000
JELLYFIN_GID=1000

Sustituye 1000 por los valores reales de tu sistema. Este usuario debe poder leer todos los directorios multimedia y escribir en las carpetas config y cache.

Cómo configurar el archivo Docker Compose de Jellyfin

Crea el archivo /opt/jellyfin/docker-compose.yml con esta configuración:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    user: "${JELLYFIN_UID}:${JELLYFIN_GID}"
    ports:
      - "8096:8096/tcp"
      - "7359:7359/udp"
    volumes:
      - type: bind
        source: ./config
        target: /config
      - type: bind
        source: ./cache
        target: /cache
      - type: bind
        source: /srv/media/peliculas
        target: /media/peliculas
        read_only: true
      - type: bind
        source: /srv/media/series
        target: /media/series
        read_only: true
      - type: bind
        source: /srv/media/musica
        target: /media/musica
        read_only: true
    restart: unless-stopped

El puerto 8096/TCP proporciona acceso a la interfaz web. El puerto 7359/UDP se utiliza para el descubrimiento automático dentro de la red local y puede eliminarse si no necesitas esta función.

Los archivos multimedia están montados como solo lectura. Esto reduce el riesgo de modificaciones accidentales, pero también impide que Jellyfin escriba archivos NFO, imágenes u otros datos junto a los medios. Si quieres utilizar esas funciones, elimina read_only: true únicamente en las carpetas necesarias.

Comprueba la sintaxis antes de iniciar el servicio:

docker compose config

Si el comando no muestra errores, descarga la imagen y levanta el contenedor:

docker compose pull
docker compose up -d

Comprueba su estado y consulta los registros:

docker compose ps
docker compose logs -f jellyfin

Pulsa Ctrl+C para salir de la vista de registros sin detener el contenedor.

Cómo completar la configuración inicial

Abre un navegador desde cualquier equipo de la red e introduce:

http://IP_DEL_SERVIDOR:8096

El asistente inicial permite seleccionar el idioma, crear la cuenta administradora y añadir las bibliotecas. Utiliza una contraseña segura y reserva esta cuenta para tareas administrativas.

Cuando añadas las carpetas multimedia, debes seleccionar las rutas internas del contenedor:

• /media/peliculas
• /media/series
• /media/musica

No introduzcas /srv/media/peliculas, porque esa ruta solamente existe en el sistema anfitrión. Dentro del contenedor ha sido asignada a /media/peliculas.

Selecciona un tipo de biblioteca específico para cada contenido. Evita mezclar películas, series y música en una misma biblioteca. Si necesitas configurar nombres, proveedores de metadatos y estructuras de carpetas, consulta cómo añadir y organizar películas y series en Jellyfin.

Cómo activar la aceleración Intel Quick Sync

En equipos Intel compatibles, comprueba primero que exista el dispositivo de renderizado:

ls -l /dev/dri/

Normalmente aparecerá como /dev/dri/renderD128. Obtén el identificador del grupo render:

getent group render | cut -d: -f3

Añade el resultado al archivo .env:

JELLYFIN_RENDER_GID=122

El valor 122 es solamente un ejemplo. Después añade estas líneas al servicio jellyfin del archivo Compose:

    group_add:
      - "${JELLYFIN_RENDER_GID}"
    devices:
      - /dev/dri/renderD128:/dev/dri/renderD128

Recrea el contenedor y verifica que Jellyfin pueda detectar la GPU:

docker compose up -d
docker exec -it jellyfin /usr/lib/jellyfin-ffmpeg/vainfo

Entra en Panel de control > Reproducción > Transcodificación, selecciona Intel Quick Sync o VA-API y habilita solamente los códecs compatibles con tu hardware.

Pasar el dispositivo al contenedor no activa automáticamente la aceleración. Conviene reproducir un archivo que requiera transcodificación y revisar los registros de FFmpeg para comprobar que la GPU está trabajando.

Cómo utilizar una GPU NVIDIA

La imagen oficial de Jellyfin no incorpora el controlador propietario de NVIDIA. Debes instalar en el anfitrión tanto el controlador como NVIDIA Container Toolkit.

Después añade al servicio de Jellyfin:

    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Recrea el contenedor y comprueba que la tarjeta sea visible:

docker compose up -d
docker exec -it jellyfin nvidia-smi

Finalmente, selecciona NVENC en los ajustes de transcodificación. No combines esta configuración con la de Intel salvo que conozcas exactamente qué dispositivo quieres utilizar.

Cómo montar una biblioteca almacenada en un NAS

Si los archivos están en un NAS o recurso Samba, lo más estable es montar primero el recurso de red en Ubuntu y después pasar esa ruta al contenedor mediante un bind mount.

Instala el soporte para CIFS y crea el punto de montaje:

sudo apt install -y cifs-utils
sudo mkdir -p /mnt/media

Guarda las credenciales del NAS en un archivo accesible solamente por el administrador y utiliza /etc/fstab para mantener el montaje después de reiniciar. Después incorpora la ruta al archivo Compose:

      - type: bind
        source: /mnt/media
        target: /media/nas
        read_only: true

Si Jellyfin ve la carpeta, pero aparece vacía, revisa los permisos del recurso, el UID y GID empleados en el montaje y los permisos de ejecución de todos los directorios superiores. Puedes ampliar esta configuración en la guía de almacenamiento en un NAS doméstico.

Cómo acceder a Jellyfin desde fuera de casa

No publiques directamente el puerto 8096 en Internet. La documentación de Jellyfin recomienda utilizar una VPN o colocar un proxy inverso con HTTPS delante del servidor.

Una VPN como Tailscale permite entrar en la red privada sin publicar Jellyfin directamente. También puedes utilizar Caddy, Nginx o Traefik como proxy inverso.

Caddy puede obtener y renovar automáticamente los certificados TLS, pero normalmente necesita que el dominio apunte a tu dirección pública y que los puertos 80 y 443 lleguen al servidor. Por tanto, un proxy inverso no significa necesariamente acceder sin abrir puertos.

Si quieres evitar una exposición pública convencional, consulta cómo acceder a Jellyfin desde fuera de casa sin abrir puertos.

Para centralizar usuarios mediante inicio de sesión único también puedes conectar Authentik con Jellyfin. Antes tendrás que instalar Authentik con Docker y configurar cuidadosamente los grupos y permisos.

Cómo actualizar Jellyfin con Docker

Antes de actualizar, crea una copia de seguridad desde Panel de control > Copias de seguridad. Las versiones actuales de Jellyfin permiten generar una copia mientras el servidor sigue funcionando, aunque conviene hacerlo cuando no haya usuarios reproduciendo contenido ni un escaneo activo.

Después actualiza la imagen y recrea el contenedor:

cd /opt/jellyfin
docker compose pull
docker compose up -d

Comprueba los registros después de la actualización:

docker compose logs --tail=100 jellyfin

Los datos persistentes permanecerán en las carpetas config y cache. Sin embargo, algunas versiones aplican migraciones sobre la base de datos y Jellyfin no dispone de un mecanismo de degradación. Si necesitas volver a una versión anterior, tendrás que restaurar una copia compatible.

Errores frecuentes al instalar Jellyfin con Docker

El contenedor se reinicia continuamente

Ejecuta docker compose logs jellyfin y revisa los permisos de las carpetas config y cache. El UID y el GID definidos en .env deben tener permiso de escritura.

La biblioteca aparece vacía

Comprueba que la ruta del anfitrión exista, que el volumen esté correctamente montado y que el usuario del contenedor pueda recorrer y leer todos sus directorios. Dentro de Jellyfin debes seleccionar la ruta interna, como /media/peliculas.

Permission denied al escanear archivos

No soluciones el problema aplicando permisos 777. Revisa el propietario, el grupo y los permisos de lectura y ejecución. Si utilizas un NAS, comprueba también las opciones con las que se ha montado el recurso.

No se puede abrir el puerto 8096

Otro proceso puede estar utilizando el puerto. Compruébalo mediante:

sudo ss -ltnp | grep 8096

Si está ocupado, detén el servicio responsable o cambia el puerto izquierdo del mapeo, por ejemplo 8097:8096.

La GPU aparece en el anfitrión, pero no en Jellyfin

En Intel, revisa el dispositivo /dev/dri/renderD128 y el identificador del grupo render. En NVIDIA, verifica el controlador, NVIDIA Container Toolkit y el resultado de docker exec -it jellyfin nvidia-smi.

El vídeo sigue utilizando la CPU

Que la GPU sea visible no significa que todos los formatos estén acelerados. Comprueba los códecs admitidos, los ajustes de transcodificación y los registros de FFmpeg. Algunos subtítulos y filtros pueden seguir utilizando la CPU.

Jellyfin funciona, pero no aparece automáticamente en los dispositivos

Comprueba que el puerto 7359/UDP esté publicado y permitido en la red local. Si necesitas DLNA, la documentación oficial indica que puede ser necesario utilizar el modo de red host.

Instalar Jellyfin con Docker Compose permite mantener el servidor multimedia aislado y facilita su administración, pero la fiabilidad final depende de los volúmenes, los permisos y las rutas utilizadas. Una vez que el contenedor funcione, podrás añadir tus bibliotecas, crear usuarios y activar la transcodificación adecuada para tu hardware.

Antes de exponer el servicio fuera de casa, configura HTTPS o una VPN y conserva copias de seguridad de la carpeta de configuración. De esta forma podrás actualizar el servidor sin perder usuarios, metadatos ni el historial de reproducción.