Instalar Chaptarr en VPS tras el cierre de Readarr

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

Chaptarr es un fork de Readarr que gestiona audiolibros y libros electrónicos desde una única instancia. Monitoriza nuevos lanzamientos, los envía a su cliente de descargas, renombra los resultados y los organiza en su biblioteca. No reproduce contenido, por lo que debe combinarlo con un reproductor como Audiobookshelf.

Readarr fue retirado el 27 de junio de 2025. El aviso del equipo de Servarr explica el motivo: los metadatos del proyecto se volvieron inutilizables y el esfuerzo comunitario para migrar a Open Library se estancó. El repositorio está archivado. Esto dejó a las colecciones de libros y audiolibros sin un gestor con mantenimiento, y Chaptarr asumió la tarea. Mantiene la estructura que ya conoce de Sonarr y Radarr (indexadores, clientes de descarga, perfiles de calidad, carpetas raíz) y añade gestión de audiolibros: organización basada en narradores, múltiples ediciones de un mismo título, soporte para M4B y MP3 con capítulos, y conversión de MP3 a M4B.

Esta guía utilizó la etiqueta de imagen chaptarr/chaptarr:0.9.925, que era el lanzamiento más reciente el 9 de agosto de 2026. A fecha de 11 de octubre de 2026, el lanzamiento más reciente es 0.9.965, publicado el 27 de septiembre de 2026. Los pasos siguientes se probaron únicamente en la versión 0.9.925, por lo que los archivos mantienen esa etiqueta; lea las notas de la versión antes de actualizar a una más reciente. Chaptarr se define a sí mismo como software beta. Lea la sección de mantenimiento cerca del final antes de apuntarlo a una biblioteca que no pueda reemplazar.

Requisitos previos

Un VPS con Docker y el plugin Compose instalado, además de espacio en disco suficiente para la biblioteca. Los audiolibros ocupan mucho espacio y una importación que no pueda utilizar enlaces físicos (hardlinks) mantendrá dos copias de un archivo durante un tiempo, tal como se explica en la sección de volúmenes más abajo. Si Docker aún no está instalado en el servidor, comience por instalar y ejecutar Docker en un VPS y regrese aquí.

Chaptarr se distribuye únicamente como imagen de Docker por el momento. El soporte nativo figura como en desarrollo, con una compilación experimental para Windows prevista, y no existen paquetes de distribución. El contenedor almacena su base de datos en /config mediante SQLite de forma predeterminada, aunque puede utilizar un servidor PostgreSQL externo mediante las variables de entorno Chaptarr__Postgres__* si ya dispone de uno. SQLite es la opción adecuada para un solo usuario en un único 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 utiliza PUID=99 y PGID=100 por defecto si no se definen. Estos son los valores de unRAID y, en un VPS con Ubuntu estándar, no corresponden a ningún usuario útil, por lo que los archivos se crean con un propietario sobre el cual su usuario no tiene permisos de escritura. Consulte sus propios números con id -u y id -g e inclúyalos en el archivo.

Cada contenedor que interactúa con los mismos archivos necesita el mismo par de valores. El cliente de descarga escribe en /srv/media/downloads, Chaptarr mueve el archivo a /srv/media/audiobooks y el reproductor lo lee allí. Si el cliente de descarga escribe como 1000:1000 y Chaptarr se ejecuta como 99:100, la importación fallará. La propiedad del archivo no es lo que determina esto: crear, renombrar o eliminar un archivo requiere permisos de escritura en el directorio que lo contiene. Los directorios creados por el usuario 1000 con el modo común 755 no otorgan a 99:100 acceso de escritura, por lo que Chaptarr no puede organizar el libro en la biblioteca ni eliminarlo de las descargas. UMASK=002 permite que los archivos nuevos sean escribibles por el grupo, lo cual es necesario cuando varios contenedores comparten un mismo grupo de medios. El mapeo completo se encuentra en cómo PUID y PGID mapean un usuario de contenedor a archivos del host.

El archivo README advierte sobre una trampa específica que merece ser reiterada. Si ./config no existe al ejecutar docker compose up, Docker lo creará por usted, asignándole como propietario a root:root. El contenedor se ejecutará entonces como UID 1000 y no podrá escribir en su propia base de datos, por lo que se cerrará y reiniciará indefinidamente. Verifique esto con ls -ln ./config, que muestra los propietarios numéricos en lugar de los nombres. Dos ceros significan que el propietario es root. Solucione el problema con sudo chown -R 1000:1000 ./config e inicie el contenedor de nuevo.

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, entorno de ejecución y etiquetas de versión frecuentes

Chaptarr tiene licencia GPL-3.0, con derechos de autor de los colaboradores de Chaptarr y partes del equipo de Servarr, por lo que el código permanece abierto y cualquiera puede realizar un fork nuevamente si este mantenedor se detiene. Se basa en .NET 10, la versión de soporte a largo plazo actual del entorno de ejecución a fecha de agosto de 2026, lo que significa que la base cuenta con soporte durante años en lugar de meses. Ambos hechos son relevantes si evalúa si este proyecto seguirá existiendo el próximo año.

Los números de versión cambian rápidamente. La 0.9.925 se publicó el 9 de agosto de 2026, y le siguieron cinco lanzamientos más en las siete semanas posteriores. Cada lanzamiento hasta la 0.9.958 se publicó como pre-release; la 0.9.965, del 27 de septiembre de 2026, es la primera marcada como lanzamiento completo. Fije una etiqueta exacta. Usar latest significa que una docker compose pull desatendida puede moverle varias versiones en una semana, y un fork tan joven puede cambiar su API entre lanzamientos, lo que rompe cualquier script o panel que haya escrito para él. Fijar versiones es un hábito que vale la pena aplicar a cada proyecto joven que aloje usted mismo, razón por la cual la guía para ejecutar openGym como un rastreador de ejercicios autohospedado se despliega desde una etiqueta de git fija exactamente por la misma razón.

Realice una copia de seguridad antes de cada actualización, luego actualice 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 reporta eventos de pérdida de datos en aproximadamente seis meses y más de once mil usuarios, y aun así recomienda mantener copias de seguridad y no apuntarlo a una biblioteca que no pueda permitirse perder. Tómese ambas partes en serio. Copie el archivo de configuración fuera del servidor, porque una copia de seguridad que reside en el mismo disco que lo que protege no es una copia de seguridad. Ese único archivo tarball es suficiente solo porque Chaptarr mantiene su estado en un archivo SQLite bajo /config; cualquier cosa que resida en un servidor de base de datos separado requiere que la base de datos también sea volcada, que es la forma que toma el paso de copia de seguridad cuando se autohospeda Chatwoot en un VPS junto con sus datos de Postgres y archivos subidos.

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 utiliza su propia canalización de proveedores, por lo que los identificadores almacenados por Readarr no tienen significado y no existe una conversión de base de datos. Sus archivos en el disco permanecen intactos. Debe añadir las mismas rutas como carpetas raíz, ejecutar una importación de biblioteca y dejar que Chaptarr identifique los archivos por sí mismo. Los perfiles de calidad, el formato de nombres, la configuración de indexadores y las coincidencias incorrectas requieren trabajo manual, así que comience con una carpeta pequeña antes de importar todo.

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

El usuario del contenedor no tiene permisos de escritura en ese directorio, generalmente porque se ejecuta con un UID diferente al del propietario. Chaptarr utiliza PUID=99 y PGID=100 por defecto cuando estas variables no están definidas; estos son valores de unRAID y son incorrectos en un VPS con Ubuntu estándar. Asígneles sus propios valores de id -u y id -g, utilice el mismo par en el cliente de descarga y configure 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, ya que muestra los números en lugar de los nombres y así podrá compararlos.

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

Chaptarr copió el archivo porque no pudo crear un enlace físico (hardlink). Montar /downloads y /audiobooks como enlaces (binds) separados los convierte en puntos de montaje distintos dentro del contenedor, y el kernel rechaza los enlaces físicos entre puntos de montaje con Invalid cross-device link. Monte un directorio padre común como /srv/media:/data y utilice /data/downloads y /data/audiobooks dentro de la aplicación. Ambas rutas deben estar además en el mismo sistema de archivos del host, lo cual puede confirmar con df -h.

¿Chaptarr reproduce mis audiolibros?

No. Se encarga de buscar, descargar, renombrar y organizar los archivos; la reproducción es una función de otro programa. Audiobookshelf es el complemento habitual porque recuerda su posición de escucha en varios dispositivos, utilizando la imagen oficial ghcr.io/advplyr/audiobookshelf:latest con la misma ruta de audiolibros del host montada. Jellyfin también reproducirá los archivos si añade la carpeta como biblioteca, aunque con un comportamiento de reanudación menos preciso en audiolibros largos de un solo archivo.

¿Es seguro ejecutar Chaptarr en una biblioteca importante?

Es software en fase beta proveniente de una bifurcación reciente, y el propio proyecto lo advierte, aunque no se han reportado eventos de pérdida de datos en aproximadamente seis meses y con más de once mil usuarios. Los aspectos tranquilizadores 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 desde agosto de 2026. Fije una etiqueta de imagen exacta como 0.9.925 en lugar de latest, realice una copia de seguridad de /config antes de cada actualización y mantenga ese archivo fuera del servidor.