Jellyfin en un VPS: transmite tu propia biblioteca

Qué vas a configurar

Un servidor multimedia Jellyfin en un VPS: un contenedor, tres volúmenes y un disco de almacenamiento en bloques que contiene tus películas y series, accesible desde cualquier navegador o aplicación de Jellyfin. La instalación usa un archivo compose de quince líneas. Todo lo que falla después se debe a dos causas: permisos de archivos que impiden que el contenedor los lea y el intento de transcodificar vídeo en un VPS sin GPU, que no está diseñado para esa tarea. Esta guía dedica la mayor parte de su contenido a esos dos problemas, porque ahí es donde se concentran las solicitudes de soporte.

Jellyfin es gratuito y completamente de código abierto. No requiere una cuenta, no incluye funciones de pago y no recopila telemetría. Por eso aparece en casi todas las listas de proyectos que merece la pena alojar por cuenta propia en 2026. Reproduce contenido que te pertenece. No incluye contenido, y esta guía no trata sobre cómo obtenerlo. Si también estás valorando Emby, cuya versión gratuita reserva parte de sus funciones para la suscripción Premiere, revisa qué añade Emby Premiere en un VPS sin GPU antes de decidir si ese pago te compensa. Si al final te quedas con Emby, la guía para instalar Emby Server en un VPS Ubuntu recorre los mismos puntos delicados que esta (permisos de las carpetas, el puerto 8096 cerrado y HTTPS delante), pero con el paquete .deb oficial en lugar de Docker.

La realidad de la transcodificación antes de contratar nada

Lea esto primero, porque cambia lo que debe contratar. Un servidor multimedia hace una de dos cosas cuando pulsa reproducir. La reproducción directa transmite el archivo tal cual: el VPS lee los bytes del disco y los envía por la red, con un consumo de CPU casi nulo. La transcodificación vuelve a codificar el vídeo sobre la marcha, ya sea para cambiar la resolución o el códec, o para incrustar los subtítulos, y eso consume CPU directamente.

Un VPS típico no tiene GPU. Por tanto, cada transcodificación de vídeo se ejecuta en la CPU con libx264/libx265, y la codificación por software es costosa. Una sola transcodificación de 1080p H.264 puede saturar varias vCPU compartidas. Una transcodificación de 4K o HEVC normalmente no puede mantener la reproducción en tiempo real, por lo que la reproducción se detiene y queda almacenada en búfer continuamente. La transcodificación por hardware, que abarata este proceso en un equipo doméstico con una iGPU Intel o una tarjeta Nvidia, simplemente no está disponible salvo que el proveedor alquile instancias con GPU.

Por tanto, toda la estrategia en un VPS consiste en evitar la transcodificación. Mantenga la biblioteca en códecs que los clientes reproduzcan de forma nativa: vídeo H.264, audio AAC o AC3, dentro de un contenedor MP4 o MKV. Elija aplicaciones cliente que admitan reproducción directa: las aplicaciones nativas de Jellyfin para Android TV, iOS y Roku, además de Infuse, Kodi y Jellyfin Media Player para equipos de escritorio. De este modo, el VPS nunca tendrá que ejecutar una transcodificación de ffmpeg durante la reproducción, y un equipo modesto con 2 vCPU podrá transmitir contenido a varias personas a la vez. Si planea transcodificar, necesitará un equipo mucho más grande y caro. Incluso entonces, 4K sigue siendo una mala opción. Con la reproducción directa, en cambio, a ese equipo de 2 vCPU le sobra CPU para servicios ligeros que delegan el cálculo pesado en otra parte, como FreeLLMAPI, que conecta Claude Code con las capas gratuitas de Groq, Gemini o Mistral: la inferencia se ejecuta en los servidores de esos proveedores, no en su VPS sin GPU.

Calcule también el ancho de banda, porque es la otra sorpresa. La reproducción directa envía el archivo a su propia tasa de bits. Un archivo 1080p comprimido usa 8-12 Mbps. Un remux de Blu-ray 1080p usa 20-30 Mbps. El contenido 4K HDR usa 40-80 Mbps. Tres personas reproduciendo directamente archivos de 10 Mbps generan 30 Mbps de tráfico de subida sostenido desde el VPS. Compruebe dos valores en su plan: la velocidad del puerto, para confirmar que puede transmitir 30 Mbps de subida, y el límite mensual de transferencia. Una película de dos horas a 10 Mbps genera aproximadamente 9 GB de salida. Por tanto, una cuota medida de 1 TB/mes permite algo más de cien películas de ese tipo al mes, es decir, tres o cuatro al día. Un hogar que reproduzca contenido 4K, con una tasa de bits entre cuatro y ocho veces mayor, agotará la cuota mucho más rápido. Cuente también cualquier otro tráfico de salida del mismo equipo dentro de ese presupuesto, incluido un relay de RustDesk autoalojado, que transporta una sesión completa de escritorio remoto cuando dos pares no pueden conectarse directamente.

Requisitos previos

• Un VPS KVM nuevo con Ubuntu 24.04, acceso como root o mediante sudo, Docker y el plugin Compose instalados.
• Un volumen de almacenamiento de bloques para los archivos multimedia, con capacidad suficiente para su biblioteca (consulte la sección sobre dimensionamiento). El disco raíz pequeño que incluye un VPS no es el lugar adecuado para almacenar sus películas.
• Un nombre de dominio si desea acceso HTTPS público, o una VPN WireGuard en el mismo VPS si prefiere mantener todo privado.
• Contenido multimedia que tenga derecho legal a transmitir: sus propias copias, sus propias grabaciones y archivos de su propiedad.

Monta primero el almacenamiento en bloques

Adjunta el volumen desde el panel de tu proveedor. Después, identifícalo y móntalo. Obtén el nombre del dispositivo con lsblk. Será algo parecido a /dev/sdb o /dev/vdb, nunca el disco raíz.

lsblk
sudo mkfs.ext4 /dev/sdb          # ONLY on a new, empty volume: this ERASES it
sudo mkdir -p /mnt/media
sudo blkid /dev/sdb              # copy the UUID shown for this device

Móntalo por UUID, no mediante /dev/sdb, porque las letras de los dispositivos pueden cambiar entre reinicios y podrías terminar formateando o montando el disco equivocado. Añade una línea a /etc/fstab:

UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  /mnt/media  ext4  defaults,nofail  0  2

sudo mount -a
df -h /mnt/media

nofail es importante: sin esta opción, si el volumen en bloques se desconecta alguna vez, el equipo no puede arrancar y pasa a un shell de emergencia. El error más grave en este punto es ejecutar mkfs.ext4 en un volumen que ya contiene datos, porque los borra. Formatea sólo los volúmenes nuevos. Si el disco ya contiene tu biblioteca, pasa directamente a la línea de fstab.

Organice el contenido multimedia como espera Jellyfin

Jellyfin asocia los metadatos según los nombres de las carpetas y los archivos. Si la estructura es incorrecta, las películas aparecen como archivos sin título y sin póster, o un episodio se asocia con la serie equivocada. Cuatro convenciones resuelven casi todos los casos: cada película debe estar en su propia carpeta y tener un nombre de archivo coincidente, con el formato Name (Year) (Jellyfin considera opcional el año, pero incluirlo mejora mucho la precisión de la asociación); las carpetas de temporada deben llamarse Season 01, no S01; los archivos de episodios deben usar S01E01; y los especiales deben ir en Season 00.

/mnt/media
├── Movies
│   ├── Blade Runner (1982)
│   │   └── Blade Runner (1982).mkv
│   └── Arrival (2016)
│       └── Arrival (2016).mkv
└── Shows
    └── Severance (2022)
        ├── Season 01
        │   ├── Severance - S01E01.mkv
        │   └── Severance - S01E02.mkv
        └── Season 00
            └── Severance - The Lexington Letter.mkv

El (Year) de las películas no es decorativo. Permite distinguir los remakes para que el asociador seleccione el título correcto. Mantenga Movies y Shows como carpetas de nivel superior independientes, porque cada una se convierte en una biblioteca de Jellyfin de un tipo de contenido específico, y mezclarlas confunde al proveedor de metadatos. Jellyfin también puede indexar sin problemas una tercera carpeta de fotos, pero la experiencia es limitada frente a la de un servidor de fotos específico. Si sus álbumes son importantes, asígneles un equipo independiente con PhotoPrism o Immich y deje este servidor para películas y series.

Permisos: el motivo principal por el que las bibliotecas aparecen vacías

Este es el error de concepto que puede hacerle perder una tarde. La imagen oficial de jellyfin/jellyfin no utiliza las variables de entorno PUID/PGID; esas variables pertenecen a la imagen de LinuxServer.io (lscr.io/linuxserver/jellyfin). En la imagen oficial, el usuario se controla con la clave user: en compose. Si se omite, el contenedor se ejecuta como root. En ambos casos, la regla es la misma: el uid/gid con el que se ejecuta el contenedor debe poder leer y atravesar todos los directorios de medios.

Se ejecutará con uid/gid 1000, el primer usuario que no es root en una instalación estándar de Ubuntu. Confirme el suyo y establezca el propietario:

id                                  # confirm your user is uid=1000 gid=1000
sudo chown -R 1000:1000 /mnt/media
sudo find /mnt/media -type d -exec chmod 755 {} \;
sudo find /mnt/media -type f -exec chmod 644 {} \;
mkdir -p ~/jellyfin/config ~/jellyfin/cache
sudo chown -R 1000:1000 ~/jellyfin

Los directorios necesitan el bit de ejecución (el x de 755), no sólo permisos de lectura. Sin él, el contenedor no puede entrar en la carpeta aunque pueda listar su nombre. El problema que deja vacía una biblioteca completa suele estar en el directorio padre: si el uid del contenedor no puede atravesar el punto de montaje, nunca llega a /media/Movies ni a /media/Shows, y todas las bibliotecas aparecen vacías al mismo tiempo, con Access to the path ... is denied en el registro. Cualquier carpeta de medios que no pueda leer se registra y se omite. Por eso, un conjunto de archivos copiados como root desaparece de la biblioteca sin mostrar un error evidente. Esta es la razón por la que cambiamos el propietario de forma recursiva y establecemos el bit de ejecución en todos los directorios, en lugar de corregir una sola carpeta.

El archivo docker-compose

services:
  jellyfin:
    image: jellyfin/jellyfin:12
    container_name: jellyfin
    user: "1000:1000"
    restart: unless-stopped
    ports:
      - "127.0.0.1:8096:8096"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /mnt/media:/media:ro
    environment:
      - JELLYFIN_PublishedServerUrl=https://jellyfin.example.com

Línea por línea: jellyfin/jellyfin:12 sigue la línea de versiones 12.x actual (12.2 a fecha de 2026-10-10). user: "1000:1000" establece el uid/gid con el que se ejecuta el proceso de Jellyfin. No cambia el propietario ni los permisos de ningún archivo, porque Docker conserva el uid/gid del host en los directorios montados. Por eso chown debe coincidir con esos valores. /config contiene todo el servidor, las cuentas, las bibliotecas, los metadatos y el estado de reproducción, por lo que debe permitir escritura y es lo que debe incluir en las copias de seguridad. /cache es espacio de trabajo temporal. El montaje de medios es :ro (de solo lectura) de forma intencionada: Jellyfin guarda por defecto las ilustraciones y los metadatos en /config, por lo que nunca necesita escribir en la biblioteca. El modo de solo lectura protege los archivos frente a un borrado accidental o un complemento defectuoso. El puerto está enlazado deliberadamente a 127.0.0.1. El inicio de sesión web de Jellyfin usa HTTP sin cifrar, por lo que nunca publicamos 8096 en Internet. JELLYFIN_PublishedServerUrl es la dirección que el servidor anuncia para la autodetección local mediante una difusión UDP en la LAN. Los clientes de Internet nunca la ven y simplemente usan la URL que se introduce en la aplicación. Establézcala como la dirección que deben recibir los clientes y prevea introducir esa URL manualmente en los dispositivos remotos.

Inícielo desde el directorio de compose:

docker compose up -d
docker logs -f jellyfin

Primera ejecución: el asistente de configuración y las bibliotecas

Como el puerto está enlazado a localhost, abra el asistente mediante un túnel SSH desde su portátil en lugar de abrir un acceso en el firewall:

ssh -L 8096:127.0.0.1:8096 you@your-vps-ip

Ahora vaya a http://localhost:8096. El asistente le guía para seleccionar el idioma y crear un usuario administrador con una contraseña segura. Esta cuenta controla el servidor, así que no reutilice una contraseña temporal. Añada la primera biblioteca: seleccione el tipo de contenido Películas, indique /media/Movies (la ruta dentro del contenedor, no la ruta del host) y repita el proceso con Series en /media/Shows. Finalice el asistente y Jellyfin iniciará el análisis. El resultado esperado es que los carteles y títulos aparezcan en uno o dos minutos para una biblioteca pequeña. Más adelante puede añadir o editar bibliotecas en Dashboard → Libraries y forzar un nuevo análisis con Scan All Libraries. Esos carteles también son lo que hace interesante probar una interfaz alternativa cuando lo básico ya funciona, porque Halcyon reconstruye la misma biblioteca como un videoclub transitable de los años 90 a partir de las imágenes que Jellyfin ya ha descargado.

Si utiliza cualquier tipo de transcodificación, abra Dashboard → Playback → Transcoding y establezca la ruta temporal de transcodificación en /cache/transcodes para que la actividad se almacene en el volumen de caché en lugar de aumentar /config. Mantenga la aceleración por hardware en None; no hay ninguna GPU disponible para acelerarla.

Acceso remoto: reverse proxy TLS o mantenerlo en la VPN

Hay dos formas seguras de acceder a Jellyfin desde fuera y una forma insegura que debe evitar. La forma insegura consiste en publicar el puerto 8096 directamente en Internet: el inicio de sesión viaja en texto sin cifrar y el puerto recibe ataques de fuerza bruta en pocas horas.

Opción A, reverse proxy TLS. Coloque Jellyfin en un subdominio detrás de Traefik con TLS automático para sus aplicaciones Docker o detrás de nginx con un certificado de Let's Encrypt emitido por Certbot. Jellyfin usa WebSockets para las actualizaciones en tiempo real, por lo que el proxy debe reenviar las cabeceras de actualización. Traefik lo hace automáticamente. nginx necesita especificarlas y también necesita HTTP/1.1 hacia el backend; de lo contrario, la actualización nunca se produce:

location / {
    proxy_pass http://127.0.0.1:8096;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Configure JELLYFIN_PublishedServerUrl con la dirección https:// para que cualquier autodetección local anuncie la URL correcta y las aplicaciones remotas usen la dirección que les proporcione. Añada fail2ban para ralentizar los intentos de fuerza bruta contra el inicio de sesión. Cuando el servidor sea público, configure Uptime Kuma con la URL para recibir avisos de una interrupción antes que sus usuarios. Dirija sus notificaciones a un servidor ntfy autohospedado para que una comprobación fallida llegue como notificación push al teléfono en lugar de como un correo que leerá a la mañana siguiente. Publicar un inicio de sesión en Internet también es un buen momento para auditar el resto del servidor, en lugar de suponer que sólo responde el puerto 443: sudo ss -tlnp muestra todos los puertos en escucha y el proceso asociado a cada uno. Si también implementa código propio en el servidor, open-kritt analiza los repositorios y sus dependencias en busca de vulnerabilidades; audita el código fuente, no los puertos en escucha.

Opción B, mantenerlo privado en una VPN. No publique el puerto 8096 en Internet; acceda a Jellyfin únicamente mediante un túnel WireGuard terminado en el mismo servidor. Para un entorno doméstico, es la opción segura más sencilla: no requiere certificado ni exposición pública y no ofrece superficie para ataques de fuerza bruta. La vinculación a localhost del archivo compose no basta por sí sola, porque un puerto publicado en 127.0.0.1 sólo es accesible desde el propio VPS, no desde los pares de la VPN. Publíquelo en la dirección del túnel del servidor (por ejemplo, "10.8.0.1:8096:8096", usando la IP de su propio servidor WireGuard) o mantenga localhost y coloque delante un proxy que escuche en la dirección del túnel. Después, conéctese mediante la VPN. Consulte Configuración de una VPN WireGuard para un VPS privado para configurar el túnel.

Dimensionamiento del almacenamiento y copias de seguridad

Planifique según la calidad, no según el número de archivos. Las películas comprimidas en 1080p ocupan entre 4 y 15 GB cada una; un remux en 1080p, entre 20 y 40 GB; una temporada de TV en 1080p, entre 15 y 40 GB; y cualquier contenido en 4K ocupa entre 40 y 100 GB por película. Una biblioteca de varios cientos de películas y algunas series necesita un volumen de 2-4 TB. Es más barato sobredimensionar el volumen de bloques una vez que migrarlo más adelante.

/config contiene todo el estado del servidor, por lo que es el único elemento que debe respaldar. Cree una snapshot, o detenga el servicio y empaquételo con tar, y conserve la copia fuera del servidor:

docker compose down
sudo tar czf jellyfin-config-$(date +%F).tgz -C ~/jellyfin config
docker compose up -d

/cache y la carpeta de transcodificación se pueden eliminar sin consecuencias. Realice una copia independiente del contenido multimedia de /mnt/media o acepte que tendrá que volver a copiarlo desde el original. La mayoría de los administradores elige la segunda opción debido al tamaño. Las actualizaciones se controlan mediante docker compose pull && docker compose up -d. La etiqueta :12 anterior se mantiene dentro de la línea 12.x, por lo que pasar a la siguiente versión principal requiere editar la etiqueta de forma deliberada. Revise brevemente las notas de la versión de Jellyfin antes de hacerlo, porque las migraciones del esquema de la biblioteca se producen en las versiones principales. Jellyfin eliminó el prefijo "10." de sus números de versión con 12.0 (septiembre de 2026): 12.0 es la versión que antes habría sido 10.12, no existe una versión 11.x y 10.11.x fue la última línea del esquema anterior. Si algún archivo de compose antiguo todavía contiene jellyfin/jellyfin:10, está fijado en 10.11; esa etiqueta cambió por última vez el 2026-06-06, a 10.11.11, y nunca descargará 12.x. Cambiarla a :12 no consiste sólo en editar una etiqueta: 12.0 cambia el esquema de la base de datos y reescribe los datos durante el primer arranque. Por tanto, detenga el servidor y cree primero la copia de seguridad anterior, porque esa copia es la única forma de volver atrás. 12.0 se actualiza directamente desde 10.10.7 o cualquier versión 10.11.x, y después necesita un análisis completo de la biblioteca, que tarda bastante más de lo habitual. Una etiqueta fijada y un único directorio de estado respaldado constituyen toda la receta para cualquier contenedor que deba estar siempre activo. Es el mismo patrón que permite mantener activa la memoria y las programaciones de un agente autohospedado tras los reinicios.

Modos de fallo y mensajes que verá

La biblioteca está vacía después de un escaneo. El registro de Dashboard → Logs (o ~/jellyfin/config/log/log_*.log) muestra:

System.UnauthorizedAccessException: Access to the path '/media/Movies' is denied.

El uid del contenedor no puede leer esa ruta. Causa: los archivos multimedia pertenecen a root o a un uid distinto del valor de user:, un directorio no tiene el bit de ejecución, o el propio punto de montaje padre no permite el recorrido de ese uid. Solución: chown -R 1000:1000 /mnt/media, directorios 755 y archivos 644; después, vuelva a escanear.

La reproducción lleva la CPU al máximo y se interrumpe para cargar. docker stats jellyfin muestra un uso de CPU cercano al 100% multiplicado por el número de núcleos, y Dashboard → Playback muestra la sesión como Transcode con una velocidad inferior a 1.0x. El cliente no está reproduciendo directamente. Por eso, el VPS transcodifica con la CPU más despacio que el tiempo real y se queda atrás. Causa: un códec o contenedor no compatible, la incrustación de subtítulos o el mapeo de tonos HDR. Solución: cambie a un cliente compatible con reproducción directa, mantenga las fuentes en H.264/AAC, use subtítulos de texto (SRT) en lugar de subtítulos de imagen (PGS/VOBSUB), que la mayoría de los clientes de Jellyfin no pueden dibujar por sí mismos y, por tanto, fuerzan la incrustación, y no reproduzca contenido 4K HDR en una máquina que dependa únicamente de la CPU.

"No hay flujos compatibles disponibles". El mensaje completo suele ser "This client isn't compatible with the media and the server isn't sending a compatible media format." El cliente rechazó la fuente y la transcodificación alternativa tampoco pudo iniciarse. Causa: un comando de ffmpeg incorrecto, un archivo ilegible o el perfil del usuario bloquea la conversión de vídeo. Solución: lea la línea de ffmpeg en Dashboard → Logs, confirme que el archivo se reproduce correctamente, compruebe los permisos de reproducción del usuario si depende de la transcodificación y pruebe con un segundo cliente para descartar problemas con los códecs del navegador.

Las películas no tienen póster o muestran uno incorrecto. Los metadatos no coincidieron. Causa: una carpeta o un nombre de archivo que no coincide con el título que usa el proveedor de metadatos, un remake o un título común sin año para distinguir las versiones, una carpeta de temporada llamada S01 en lugar de Season 01 o episodios que no siguen el formato S01E01. Solución: cambie los nombres para usar la estructura anterior y, después, seleccione Refresh metadata → Replace all, o use Identify en un elemento individual para fijar la entrada correcta de TMDB/TVDB.

FAQ

¿Puede un VPS transcodificar vídeo sin GPU?

Sí, pero sólo con la CPU y con un coste elevado. Una única transcodificación de software a 1080p puede saturar varias vCPU, y 4K o HEVC normalmente no puede mantener el tiempo real, por lo que la reproducción se almacena en búfer. La mejor opción es evitar la transcodificación: mantenga la biblioteca en H.264/AAC y use aplicaciones cliente que reproduzcan directamente, de modo que el VPS sólo transfiera bytes. Alquile una instancia con GPU sólo si realmente necesita transcodificación sobre la marcha.

¿Por qué mi biblioteca de Jellyfin está vacía después de un análisis?

Casi siempre se debe a los permisos. La imagen oficial de jellyfin/jellyfin se ejecuta con el usuario indicado en user: (o como root), y si ese uid no puede leer los archivos, el análisis registra Access to the path ... is denied y los omite. Corrija el propietario con chown -R 1000:1000 /mnt/media, asigne el permiso de ejecución a los directorios (755), vuelva a analizar y compruebe también el directorio padre, porque si el uid del contenedor no puede atravesar /mnt/media, nunca llega a las carpetas de la biblioteca y todo aparece vacío. La segunda causa más común es una estructura de directorios que no coincide con la esperada por Jellyfin.

¿Cómo accedo a Jellyfin de forma remota y segura?

Hay dos opciones adecuadas. Colóquelo detrás de un reverse proxy TLS en un subdominio para cifrar el inicio de sesión y la transmisión, y añada fail2ban. Nunca exponga el puerto sin cifrado 8096, porque envía la contraseña en texto claro. Otra opción es mantenerlo completamente privado y acceder sólo mediante una VPN, que es la alternativa segura más sencilla para un hogar. Configure las aplicaciones con la dirección pública directamente. La autodetección es una difusión de la red local, por lo que no llega a los clientes que se conectan desde Internet.

¿Cuánto disco y ancho de banda necesita un VPS de Jellyfin?

El espacio en disco depende de la calidad: calcule 4-15 GB por película 1080p comprimida, 20-40 GB por remux y 40-100 GB para 4K. Por tanto, la mayoría de las bibliotecas necesitan un volumen en bloque de 2-4 TB. El ancho de banda lo determina la tasa de bits de la reproducción directa: 8-12 Mbps por flujo 1080p y mucho más para 4K. Confirme que la velocidad de su puerto admite el número de espectadores simultáneos y supervise el límite mensual de transferencia. Añada margen de CPU si planea transcodificar. Priorice el ancho de banda sobre los núcleos si planea usar la reproducción directa.

¿Es legal ejecutar Jellyfin en un VPS?

Jellyfin es software gratuito y de código abierto, y ejecutarlo es completamente legal. Lo importante es el contenido: transmita sólo contenido multimedia que posea o cuya custodia tenga autorizada, como sus propias copias de discos, grabaciones o archivos para los que tenga derechos. Jellyfin no incluye contenido multimedia ni proporciona ningún medio para obtenerlo. Es un reproductor para una biblioteca que ya posee.