Instalar Chaptarr para audiolibros en un VPS

Qué es Chaptarr y por qué los usuarios de Readarr lo necesitan

Chaptarr es una bifurcación de Readarr que gestiona audiolibros y libros electrónicos desde una sola instancia. Busca lanzamientos nuevos, los envía al cliente de descarga y después renombra los resultados y los organiza en la biblioteca. No reproduce contenido, por lo que debe combinarlo con un reproductor como Audiobookshelf.

Readarr dejó de mantenerse el 27 de junio de 2025. El aviso del propio equipo de Servarr indica el motivo: los metadatos del proyecto se habían vuelto inutilizables y el esfuerzo de la comunidad para migrar a Open Library se estancó. El repositorio está archivado. Esto dejó las colecciones de libros y audiolibros sin un gestor mantenido, y Chaptarr asumió esa función. Mantiene la estructura que ya conoce de Sonarr y Radarr (indexadores, clientes de descarga, perfiles de calidad y carpetas raíz) y añade gestión de audiolibros: organización basada en el narrador, varias ediciones de un mismo título, compatibilidad con M4B y MP3 por capítulos, y conversión de MP3 a M4B.

Este tutorial utilizó la etiqueta de imagen chaptarr/chaptarr:0.9.925, que era la versión más reciente el 9 de agosto de 2026. Chaptarr se considera software beta. Consulte la sección de mantenimiento cerca del final antes de usarlo con una biblioteca que no pueda reemplazar.

Qué necesita antes de empezar

Un VPS con Docker y el plugin Compose, además de espacio suficiente en disco para la biblioteca. Los audiolibros ocupan mucho espacio. Una importación que no puede usar enlaces duros mantiene dos copias de un archivo durante un tiempo. La sección sobre volúmenes explica este comportamiento. Si Docker todavía no está instalado en el servidor, empiece por Instalar y ejecutar Docker en un VPS y vuelva aquí.

Por ahora, Chaptarr sólo se distribuye como imagen de Docker. Hay una compilación nativa para Windows en desarrollo y no existe ningún paquete de distribución. De forma predeterminada, el contenedor almacena la base de datos SQLite en /config. También puede usar un servidor PostgreSQL externo mediante las variables de entorno Chaptarr__Postgres__* si ya ejecuta uno. SQLite es la opción adecuada para un usuario en un solo servidor.

El servicio de Compose para Chaptarr

Este servicio se integra en una pila existente. Fija una etiqueta publicada, expone la interfaz web sólo en loopback y se conecta a la red que ya usa el cliente de descargas.

services:
  chaptarr:
    image: chaptarr/chaptarr:0.9.925
    container_name: chaptarr
    environment:
      - PUID=1000
      - PGID=1000
      - UMASK=002
      - TZ=Europe/Berlin
    volumes:
      - ./config:/config
      - /srv/media/audiobooks:/audiobooks
      - /srv/media/ebooks:/ebooks
      - /srv/media/downloads:/downloads
    ports:
      - 127.0.0.1:8789:8789
    restart: unless-stopped
    networks:
      - arr

networks:
  arr:
    external: true

La línea external: true significa «esta red ya existe; conéctate a ella». Úsela cuando Prowlarr y el cliente torrent procedan de otro proyecto de Compose, porque, de lo contrario, un segundo archivo de Compose crea su propia red aislada y Chaptarr no puede resolver qbittorrent por nombre. Obtenga el nombre real con docker network ls. Si la pila ya está definida en un solo archivo, añada el servicio chaptarr: a ese archivo y elimine todo el bloque networks:. La estructura completa se explica en una pila arr completa con Docker Compose, y las reglas de nombres en cómo se resuelven las redes y los nombres de servicio de Compose.

Cree usted mismo el directorio de configuración y, después, inicie el servicio.

mkdir -p ./config
sudo chown 1000:1000 ./config
docker compose up -d
docker compose ps
docker compose logs -f chaptarr

docker compose ps debe mostrar el contenedor como Up. Un contenedor que aparece como Restarting no ha podido iniciarse y se está reintentando; la causa casi siempre está en el directorio de configuración. El desplazamiento del registro se detiene cuando la aplicación empieza a escuchar en el puerto 8789.

PUID, PGID y el directorio que Docker crea como root

Chaptarr usa PUID=99 y PGID=100 de forma predeterminada si no los define. Esos son los valores de unRAID. En un VPS Ubuntu normal, pertenecen a una cuenta que no sirve para este caso. Por eso, los archivos quedan con un propietario sobre el que su usuario no puede escribir. Consulte sus propios valores con id -u y id -g y escríbalos en el archivo.

Todos los contenedores que acceden a los mismos archivos necesitan el mismo par de valores. El cliente de descargas escribe en /srv/media/downloads, Chaptarr mueve el archivo a /srv/media/audiobooks y el reproductor lo lee allí. Si el cliente de descargas escribe como 1000:1000 y Chaptarr se ejecuta como 99:100, la importación falla porque Chaptarr no puede eliminar ni mover un archivo que no le pertenece. UMASK=002 hace que los archivos nuevos tengan permisos de escritura para el grupo. Esto es lo que necesita cuando varios contenedores comparten un grupo de medios. La asignación completa está en cómo PUID y PGID asignan un usuario del contenedor a los archivos del host.

El README advierte de un problema concreto que conviene repetir. Si ./config no existe cuando ejecuta docker compose up, Docker lo crea automáticamente con el propietario root:root. El contenedor se ejecuta entonces con el UID 1000 y no puede escribir en su propia base de datos, por lo que se cierra y se reinicia continuamente. Compruébelo con ls -ln ./config, que muestra los propietarios numéricos en lugar de sus nombres. Dos ceros indican que root es el propietario. Corríjalo con sudo chown -R 1000:1000 ./config y vuelva a iniciar el contenedor.

Por qué separar los volúmenes de audiolibros y libros electrónicos impide usar hardlinks

La distribución anterior monta /audiobooks, /ebooks y /downloads como binds independientes, tal como indica el comando de ejecución del proyecto. Es fácil de leer, pero tiene un coste real: los hardlinks dejan de funcionar.

Un hardlink es un segundo nombre para los mismos datos del disco. No usa espacio adicional y se crea al instante. Por eso la familia arr lo prefiere frente a copiar archivos. Un hardlink sólo funciona dentro de un sistema de archivos. Dentro del contenedor, estos son tres puntos de montaje independientes. Por eso el kernel rechaza el enlace aunque las rutas del host estén en el mismo disco. Pruébelo:

docker exec chaptarr sh -c 'touch /downloads/linktest && ln /downloads/linktest /audiobooks/linktest'

El comando falla con un error que termina en Invalid cross-device link. El kernel rechaza el enlace entre puntos de montaje. Esta es la razón exacta por la que Chaptarr vuelve a copiar el archivo. La copia es correcta, pero más lenta. Además, el audiolibro existe dos veces hasta que elimine el torrent. Esto no se hará mientras se siga compartiendo. Elimine /srv/media/downloads/linktest después.

Para conservar los hardlinks, monte un directorio padre:

    volumes:
      - ./config:/config
      - /srv/media:/data

Después, establezca las carpetas raíz de Chaptarr como /data/audiobooks y /data/ebooks. Asigne al cliente de descargas el mismo punto de montaje /srv/media:/data para que ambos contenedores vean una ruta idéntica. Confirme primero que el lado del host usa un único sistema de archivos: df -h /srv/media/downloads /srv/media/audiobooks debe mostrar el mismo valor en la columna Filesystem para ambos. Los valores distintos indican discos diferentes. Ninguna distribución de montajes puede crear hardlinks entre ellos. La diferencia entre este método y el almacenamiento con nombre se explica en bind mounts frente a volúmenes con nombre para medios.

Acceder a la interfaz web sin exponerla

La línea del puerto publica en 127.0.0.1 por un motivo. ufw deny 8789 no protege un puerto de Docker publicado, porque Docker escribe sus propias reglas NAT (traducción de direcciones de red) en una cadena que el kernel procesa antes que las reglas de ufw. Por eso, el tráfico se reenvía antes de que se consulte su regla. Este comportamiento confunde constantemente a los administradores y se explica en por qué un puerto publicado de Docker ignora las reglas de ufw. El enlace a loopback evita por completo este problema.

Acceda a la interfaz mediante un túnel SSH desde su propio equipo:

ssh -N -L 8789:127.0.0.1:8789 you@your-server

Deje el túnel en ejecución y abra http://127.0.0.1:8789 en el navegador. Configure la autenticación durante el primer inicio. Sólo después debería considerar colocar delante un reverse proxy con TLS (seguridad de la capa de transporte). Cuando acceda mediante túneles a tres o cuatro de estas herramientas y use una contraseña distinta en cada una, la opción más ordenada es colocar el proxy detrás de un servidor de inicio de sesión único autoalojado, como Authentik, de modo que un solo inicio de sesión cubra todas las aplicaciones y una sola revocación las cierre todas.

Conectar los indexadores y el cliente de descargas

Chaptarr admite los protocolos estándar de indexadores y clientes de descargas de arr. Por eso, Prowlarr le incorpora los indexadores del mismo modo que a Sonarr. Los clientes habituales de torrent y Usenet se conectan sin una configuración especial.

Hay un ajuste que causa problemas a casi todo el mundo. Cuando Chaptarr solicite el host del cliente de descargas, no escriba localhost ni 127.0.0.1. Dentro de un contenedor, esa dirección corresponde al propio contenedor. Por tanto, Chaptarr intenta conectarse a su propio puerto 8080 e informa de que no puede establecer la conexión. Use el nombre del contenedor, qbittorrent, con el puerto 8080. Confirme que ambos contenedores están en la misma red con docker network inspect arr, que muestra todos los contenedores conectados por nombre.

Si el cliente de descargas se ejecuta mediante un contenedor VPN con network_mode: "service:gluetun", no tiene un nombre propio en la red porque comparte el espacio de nombres de red de Gluetun. Diríjase a él como gluetun en el puerto que expone Gluetun. Esta configuración y el enrutamiento asociado se explican en enrutar un cliente de descargas a través de Gluetun.

La ruptura con Readarr: cuál es el coste real de una migración

Chaptarr no es compatible con las fuentes de metadatos de Readarr. Resuelve títulos, autores y ediciones mediante su propio flujo en varios proveedores, por lo que los identificadores que Readarr almacenó no tienen ningún significado aquí. No existe una importación de la base de datos ni una ruta de actualización directa.

En una biblioteca existente, esto significa que los archivos están a salvo, pero la configuración no. Este proceso no modifica nada de lo que ya está en el disco. Añada una carpeta raíz, ejecute una importación de la biblioteca y Chaptarr asociará los archivos encontrados con sus propios metadatos. Tendrá que reconstruir manualmente los perfiles de calidad, el formato de nombres, la configuración de indexadores y clientes, además de corregir todas las asociaciones que Chaptarr haga de forma incorrecta. Una biblioteca grande requerirá una revisión manual, así que reserve una tarde, no diez minutos.

Siga este orden. Detenga el contenedor de Readarr, pero conserve su volumen de configuración para poder consultar la configuración anterior mientras la vuelve a introducir. Configure primero una carpeta pequeña en Chaptarr y compruebe las asociaciones antes de importar toda la biblioteca. No elimine el contenedor antiguo hasta estar satisfecho con el resultado.

Hay un detalle de privacidad que conviene conocer antes de analizar toda la biblioteca: las consultas de metadatos se envían a api2.chaptarr.com. El README indica que esas solicitudes pueden incluir identificadores de proveedores, texto de búsqueda, tipo de contenido, etiquetas y nombres de archivo, y que excluyen las rutas completas, la identidad del usuario y las credenciales. Los nombres de archivo salen de su servidor. Es normal en un servicio de metadatos, pero aun así debe decidirlo de forma consciente.

Entregue los audiolibros a un reproductor

Chaptarr organiza los archivos. Reproducirlos es responsabilidad de otro programa. Audiobookshelf suele ser la opción habitual porque registra la posición de reproducción entre dispositivos y ofrece aplicaciones para teléfonos. Su imagen oficial es ghcr.io/advplyr/audiobookshelf:latest. El ejemplo de Compose documentado publica el puerto 13378 del host en el puerto 80 del contenedor.

  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    container_name: audiobookshelf
    ports:
      - 127.0.0.1:13378:80
    volumes:
      - ./abs/config:/config
      - ./abs/metadata:/metadata
      - /srv/media/audiobooks:/audiobooks
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

Monte la misma ruta del host en la que Chaptarr escribe los archivos. Después, añada /audiobooks como biblioteca en la interfaz web. La nueva importación aparecerá después del siguiente escaneo.

Si ya ejecuta Jellyfin, puede añadir la carpeta como biblioteca y reproducir los archivos desde allí. Sin embargo, la reanudación de la reproducción de un único archivo de audiolibro largo funciona peor que en un servidor diseñado específicamente para audiolibros. La configuración de esa opción se explica en ejecutar Jellyfin como servidor multimedia en un VPS. Para la parte de los libros electrónicos, entregue /srv/media/ebooks a una aplicación de lectura. El trabajo de Chaptarr termina cuando el archivo tiene el nombre y la ubicación correctos.

Riesgo de mantenimiento: licencia, runtime y una etiqueta que cambia rápido

Chaptarr tiene licencia GPL-3.0 y los derechos de autor corresponden a los colaboradores de Chaptarr, con partes aportadas por el equipo de Servarr. Por tanto, el código sigue siendo abierto y cualquiera puede crear otro fork si este mantenedor abandona el proyecto. Se basa en .NET 10, la versión actual con soporte a largo plazo del runtime en agosto de 2026. Esto significa que la base tendrá soporte durante años, no sólo meses. Ambos aspectos importan al evaluar si este proyecto seguirá existiendo el próximo año.

Los números de versión cambian rápido. Las releases se publican como pre-releases y la versión 0.9.925 se publicó el mismo día que esta guía. Fije una etiqueta exacta. Usar latest permite que un docker compose pull desatendido le haga saltar varias versiones en una semana. Además, un fork tan reciente puede cambiar su API entre releases, lo que rompe cualquier script o dashboard que haya creado para usarlo. Fijar versiones es una práctica que conviene aplicar a todos los proyectos recientes que aloje usted mismo. Por eso, la guía para ejecutar openGym como un tracker de entrenamientos autoalojado se despliega desde una etiqueta fija de git exactamente por el mismo motivo.

Haga una copia de seguridad antes de cada upgrade y actualice sólo de forma deliberada.

docker compose stop chaptarr
sudo tar czf chaptarr-config-backup.tgz ./config
docker compose start chaptarr

docker compose pull chaptarr
docker compose up -d chaptarr

El proyecto no informa de ninguna pérdida de datos en aproximadamente seis meses y con más de once mil usuarios. Aun así, recomienda mantener copias de seguridad y no apuntarlo a una biblioteca cuya pérdida no pueda asumir. Tome en serio ambas partes. Copie el archivo de configuración fuera del servidor, porque una copia de seguridad almacenada en el mismo disco que los datos que protege no es una copia de seguridad. Ese único archivo tar basta porque Chaptarr mantiene su estado en un solo archivo SQLite bajo /config. Cualquier dato almacenado en un servidor de bases de datos independiente también requiere un volcado de la base de datos. Ese es el procedimiento que se aplica al hacer una copia de seguridad cuando autoaloja Chatwoot en un VPS junto con sus datos de Postgres y los archivos cargados.

Modos de fallo y cadenas que verá

El contenedor se reinicia continuamente. docker compose ps muestra Restarting. Ejecute ls -ln ./config. Dos ceros en las columnas del propietario indican que Docker creó el directorio como root y que el usuario del contenedor no puede escribir en su base de datos. Ejecute sudo chown -R 1000:1000 ./config.

Las importaciones nunca terminan y los archivos permanecen en las descargas. Chaptarr puede leer la descarga, pero no puede escribir en la biblioteca. Compare ls -ln /srv/media/audiobooks con PUID y PGID. Un directorio cuyo propietario es un UID diferente, o cuyo propietario es su grupo pero no tiene permisos de escritura para el grupo, impide mover el archivo. UMASK=002 evita el segundo caso para los archivos nuevos.

El uso de disco se duplica después de cada importación. No se creó ningún hard link, por lo que el archivo se copió. Ejecute la prueba ln de la sección sobre volúmenes. Un error que termine en Invalid cross-device link lo confirma; la solución es usar un único montaje padre.

El cliente de descargas no puede conectarse. Introdujo localhost como host. Dentro del contenedor, ese host es el propio Chaptarr. Use el nombre del contenedor y compruebe que docker network inspect arr muestra ambos contenedores.

Compose rechaza iniciar el servicio. Bind for 127.0.0.1:8789 failed: port is already allocated significa que otro proceso ya utiliza el puerto. Localícelo con sudo ss -lntp | grep 8789.

El navegador no muestra nada. Si el puerto está enlazado a 127.0.0.1, su portátil no tiene ningún servicio al que conectarse a través de Internet. Ese es el comportamiento previsto. Abra primero el túnel SSH.

FAQ

¿Puedo migrar mi biblioteca de Readarr a Chaptarr?

No como una importación. Chaptarr no es compatible con las fuentes de metadatos de Readarr y usa su propia canalización de proveedores, por lo que los identificadores almacenados por Readarr no tienen utilidad y no existe una conversión de la base de datos. Los archivos del disco no se modifican. Añada las mismas rutas como carpetas raíz, ejecute una importación de la biblioteca y deje que Chaptarr busque coincidencias por su cuenta. Los perfiles de calidad, el formato de nombres, la configuración de los indexadores y las coincidencias incorrectas requieren trabajo manual. Empiece con una carpeta pequeña antes de importarlo todo.

¿Por qué Chaptarr no puede escribir en mi carpeta de audiolibros?

El usuario del contenedor no es el propietario de los archivos. Chaptarr usa PUID=99 y PGID=100 como valores alternativos cuando esas variables no están definidas. Esos son los valores de unRAID y no son correctos en un VPS Ubuntu normal. Defina sus propios valores id -u y id -g, use el mismo par en el cliente de descargas y establezca UMASK=002 para que los archivos nuevos mantengan permisos de escritura para el grupo. Compruebe la propiedad con ls -ln en el directorio de la biblioteca. Este comando muestra los números en lugar de los nombres, por lo que puede compararlos.

¿Por qué se duplicó el uso de disco después de una importación?

Chaptarr copió el archivo porque no pudo crear un enlace duro. Montar /downloads y /audiobooks como enlaces independientes los convierte en puntos de montaje separados dentro del contenedor. El kernel rechaza un enlace duro entre puntos de montaje con Invalid cross-device link. Monte un directorio principal, como /srv/media:/data, y use /data/downloads y /data/audiobooks dentro de la aplicación. Ambas rutas también deben estar en un único sistema de archivos del host, lo que confirma df -h.

¿Chaptarr reproduce mis audiolibros?

No. Busca, descarga, renombra y organiza los archivos. La reproducción corresponde a otro programa. Audiobookshelf es una combinación habitual porque conserva la posición entre dispositivos. Use la imagen oficial ghcr.io/advplyr/audiobookshelf:latest y monte la misma ruta de audiolibros del host. Jellyfin también reproducirá los archivos si añade la carpeta como biblioteca, aunque reanuda la reproducción con menos precisión en audiolibros largos almacenados en un único archivo.

¿Es seguro ejecutar Chaptarr en una biblioteca que me importa?

Es software beta de una bifurcación reciente. El propio proyecto lo indica, aunque también informa de que no se han producido pérdidas de datos durante unos seis meses y con más de once mil usuarios. Los aspectos favorables son la licencia GPL-3.0, que permite bifurcar el código, y la base .NET 10, un entorno de ejecución con soporte a largo plazo en agosto de 2026. Fije una etiqueta exacta de imagen, como 0.9.925, en lugar de latest. Haga una copia de seguridad de /config antes de cada actualización y conserve ese archivo fuera del servidor.