Comment installer Chaptarr sur un VPS avec Docker

Ce qu’est Chaptarr et pourquoi les utilisateurs de Readarr en ont besoin

Chaptarr est un fork de Readarr qui gère les livres audio et les ebooks depuis une seule instance. Il surveille les nouvelles releases, les transmet à votre client de téléchargement, puis renomme les fichiers récupérés et les classe dans votre bibliothèque. Il ne lit aucun contenu. Vous devez donc l’associer à un lecteur comme Audiobookshelf.

Readarr a été retiré le 27 June 2025. L’avis de l’équipe Servarr en donne la raison : les métadonnées du projet étaient devenues inutilisables et l’effort communautaire visant à migrer vers Open Library s’est enlisé. Le repository est archivé. Les collections de livres et de livres audio se sont ainsi retrouvées sans gestionnaire maintenu, et Chaptarr a repris le rôle. Il conserve l’interface que vous connaissez déjà avec Sonarr et Radarr (indexers, clients de téléchargement, profils de qualité, dossiers racine) et ajoute la gestion des livres audio : organisation selon le narrateur, plusieurs éditions d’un même titre, prise en charge de M4B et des MP3 avec chapitres, ainsi que la conversion de MP3 vers M4B.

Ce guide utilisait le tag d’image chaptarr/chaptarr:0.9.925, qui correspondait à la release la plus récente le 9 August 2026. Au 11 October 2026, la release la plus récente est 0.9.965, publiée le 27 September 2026. Les étapes ci-dessous ont été testées uniquement avec 0.9.925. Les fichiers conservent donc ce tag. Consultez les notes de release avant de passer à une version plus récente. Chaptarr se présente comme un logiciel en bêta. Consultez la section consacrée à la maintenance vers la fin du guide avant de le connecter à une bibliothèque que vous ne pouvez pas remplacer.

Ce qu’il vous faut avant de commencer

Un VPS avec Docker et le plugin Compose, ainsi que suffisamment d’espace disque pour la bibliothèque. Les livres audio sont volumineux. Une importation qui ne peut pas utiliser les hardlinks conserve temporairement deux copies d’un fichier. La section consacrée aux volumes ci-dessous l’explique. Si Docker n’est pas encore installé sur le serveur, commencez par Installer et exécuter Docker sur un VPS, puis revenez ici.

Chaptarr est actuellement disponible uniquement sous forme d’image Docker. La prise en charge native est en cours de développement. Une build Windows expérimentale est prévue, et aucun paquet pour les distributions n’est disponible. Par défaut, le conteneur stocke sa base de données SQLite dans /config. Il peut utiliser un serveur PostgreSQL externe via les variables d’environnement Chaptarr__Postgres__* si vous en exécutez déjà un. SQLite convient pour un seul utilisateur sur un seul serveur.

Le service Compose de Chaptarr

Ce service s’intègre à une stack existante. Il utilise un tag publié précis, expose l’interface web uniquement sur loopback et rejoint le réseau déjà utilisé par votre client de téléchargement.

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 ligne external: true signifie « ce réseau existe déjà, rattachez-vous à celui-ci ». Utilisez-la lorsque Prowlarr et votre client torrent proviennent d’un autre projet Compose. Sinon, le deuxième fichier Compose crée son propre réseau isolé et Chaptarr ne peut jamais résoudre qbittorrent par son nom. Récupérez le nom réel avec docker network ls. Si votre stack tient déjà dans un seul fichier, ajoutez le service chaptarr: à ce fichier et supprimez entièrement le bloc networks: à la place. La structure complète est présentée dans une stack arr complète avec Docker Compose, et les règles de nommage dans la résolution des réseaux et des noms de service Compose.

Créez vous-même le répertoire de configuration, puis démarrez le service.

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

docker compose ps doit afficher le conteneur avec l’état Up. Un conteneur affiché comme Restarting n’a pas réussi à démarrer et est relancé. La cause concerne presque toujours le répertoire de configuration. Le défilement des journaux s’arrête dès que l’application écoute sur le port 8789.

PUID, PGID et le répertoire que Docker crée avec root

Chaptarr utilise par défaut PUID=99 et PGID=100 si vous ne les définissez pas. Ce sont les valeurs d’unRAID. Sur un VPS Ubuntu standard, elles correspondent à un compte qui ne vous sert pas. Les fichiers sont donc créés avec un propriétaire sur lequel votre compte ne peut pas écrire. Affichez vos propres valeurs avec id -u et id -g, puis indiquez-les dans le fichier.

Tous les conteneurs qui utilisent les mêmes fichiers doivent utiliser la même paire. Le client de téléchargement écrit dans /srv/media/downloads, Chaptarr déplace le fichier vers /srv/media/audiobooks, puis le lecteur le lit à cet emplacement. Si le client de téléchargement écrit avec 1000:1000 alors que Chaptarr s’exécute avec 99:100, l’import échoue. Le propriétaire du fichier ne suffit pas à déterminer les droits nécessaires : créer, renommer ou supprimer un fichier exige un droit d’écriture sur le répertoire qui le contient. Les répertoires créés par l’utilisateur 1000 avec le mode courant 755 n’accordent aucun droit d’écriture à 99:100. Chaptarr ne peut donc ni classer le livre dans la bibliothèque ni le supprimer du répertoire des téléchargements. UMASK=002 rend les nouveaux fichiers accessibles en écriture au groupe. C’est ce qu’il faut lorsque plusieurs conteneurs partagent un même groupe de médias. Le mapping complet est décrit dans la correspondance entre PUID, PGID et les fichiers de l’hôte.

Le README signale un piège précis, qu’il est utile de rappeler. Si ./config n’existe pas lorsque vous exécutez docker compose up, Docker le crée avec root:root comme propriétaire. Le conteneur s’exécute alors avec l’UID 1000 et ne peut pas écrire dans sa propre base de données. Il s’arrête donc, puis redémarre indéfiniment. Vérifiez avec ls -ln ./config, qui affiche les propriétaires numériques au lieu de leurs noms. Deux zéros indiquent que root en est le propriétaire. Corrigez le problème avec sudo chown -R 1000:1000 ./config, puis redémarrez le conteneur.

Pourquoi séparer les volumes des livres audio et des ebooks empêche les hardlinks

La configuration ci-dessus monte /audiobooks, /ebooks et /downloads comme des bind mounts distincts, conformément à la commande de lancement du projet. Elle est facile à lire, mais elle a un coût réel : les hardlinks ne fonctionnent plus.

Un hardlink est un second nom pour les mêmes données sur le disque. Il n’utilise pas d’espace supplémentaire et sa création est instantanée. C’est pourquoi la famille arr le préfère à la copie. Un hardlink ne fonctionne qu’à l’intérieur d’un même filesystem. Dans le conteneur, ces chemins correspondent à trois points de montage distincts. Le kernel refuse donc le lien, même si les chemins de l’hôte se trouvent sur le même disque. Testez-le vous-même.

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

La commande échoue avec une erreur qui se termine par Invalid cross-device link. Le kernel refuse ainsi de créer un lien entre deux points de montage. C’est précisément pourquoi Chaptarr revient à la copie du fichier. La copie est correcte, mais plus lente. Le livre audio existe alors en double jusqu’à la suppression du torrent, ce que vous ne ferez pas tant que vous continuerez à le seeder. Supprimez ensuite /srv/media/downloads/linktest.

Pour conserver les hardlinks, montez plutôt un répertoire parent unique :

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

Définissez ensuite les root folders dans Chaptarr sur /data/audiobooks et /data/ebooks. Donnez au client de téléchargement le même mount /srv/media:/data, afin que les deux conteneurs voient un chemin identique. Vérifiez d’abord que le chemin côté hôte se trouve sur un seul filesystem : df -h /srv/media/downloads /srv/media/audiobooks doit afficher la même valeur dans la colonne Filesystem pour les deux chemins. Des valeurs différentes indiquent des disques différents. Aucune configuration de montage ne peut alors créer de hardlink entre eux. Le compromis entre cette approche et les named volumes est expliqué dans bind mounts et named volumes pour les médias.

Accéder à l’interface web sans l’exposer

La ligne de port publie le service sur 127.0.0.1 pour une raison précise. ufw deny 8789 ne protège pas un port Docker publié, car Docker écrit ses propres règles NAT (network address translation) dans une chaîne que le kernel parcourt avant celle d’ufw. Le trafic est donc transféré avant même que votre règle soit consultée. Ce comportement piège constamment les administrateurs. Il est expliqué dans pourquoi un port Docker publié ignore vos règles ufw. Une liaison sur la loopback contourne entièrement ce problème.

Accédez à l’interface depuis votre propre machine au moyen d’un tunnel SSH :

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

Laissez ce tunnel actif et ouvrez http://127.0.0.1:8789 dans votre navigateur. Configurez l’authentification lors du premier démarrage. Ce n’est qu’ensuite que vous devriez envisager de placer un reverse proxy avec TLS (transport layer security) devant l’application. Lorsque vous utilisez trois ou quatre de ces outils avec un mot de passe distinct pour chacun, la solution la plus propre consiste à placer le proxy derrière un serveur single sign-on auto-hébergé tel qu’Authentik, afin qu’une seule connexion couvre toutes les applications et qu’une seule révocation les désactive toutes.

Connecter les indexers et le client de téléchargement

Chaptarr utilise les protocoles standard des indexers et des clients de téléchargement de la famille arr. Prowlarr y transmet donc les indexers de la même manière que pour Sonarr. Les clients torrent et Usenet habituels se connectent sans configuration particulière.

Un paramètre pose problème dans la plupart des installations. Lorsque Chaptarr demande l’hôte du client de téléchargement, ne saisissez pas localhost ni 127.0.0.1. Dans un conteneur, cette adresse désigne le conteneur lui-même. Chaptarr tente donc de se connecter à son propre port 8080 et signale que la connexion est impossible. Utilisez le nom du conteneur, qbittorrent, avec le port 8080. Vérifiez que les deux conteneurs sont connectés au même réseau avec docker network inspect arr. Cette commande liste tous les conteneurs connectés avec leur nom.

Si votre client de téléchargement utilise un conteneur VPN avec network_mode: "service:gluetun", il n’a pas de nom propre sur le réseau, car il partage le network namespace de Gluetun. Adressez-le avec gluetun sur le port exposé par Gluetun. Cette configuration et le routage associé sont décrits dans faire passer le trafic d’un client de téléchargement par Gluetun.

La rupture avec Readarr : ce qu’une migration coûte réellement

Chaptarr n’est pas compatible avec les sources de métadonnées de Readarr. Il résout les titres, les auteurs et les éditions via son propre pipeline auprès de plusieurs fournisseurs. Les identifiants enregistrés par Readarr n’ont donc aucune signification ici. Il n’existe ni import de base de données ni chemin de mise à niveau direct.

Pour une bibliothèque existante, cela signifie que les fichiers sont préservés, mais pas les paramètres. Cette procédure ne modifie rien de ce qui se trouve déjà sur le disque. Vous ajoutez un dossier racine, lancez un import de bibliothèque, puis Chaptarr associe les fichiers trouvés à ses propres métadonnées. Vous devrez recréer manuellement les profils de qualité, le format de nommage, les paramètres des indexers et des clients, ainsi que chaque association incorrecte proposée par Chaptarr. Une grande bibliothèque nécessitera une vérification et des corrections manuelles. Prévoyez donc une soirée plutôt que dix minutes.

Procédez dans cet ordre. Arrêtez le conteneur Readarr, mais conservez son volume de configuration afin de pouvoir consulter vos anciens paramètres pendant que vous les ressaisissez. Configurez d’abord Chaptarr sur un petit dossier et vérifiez les associations avant d’importer toute la bibliothèque. Supprimez l’ancien conteneur uniquement lorsque le résultat vous convient.

Avant d’analyser toute une bibliothèque, vous devez connaître un point concernant la confidentialité : les recherches de métadonnées sont envoyées à api2.chaptarr.com. Le README indique que ces requêtes peuvent contenir des identifiants de fournisseurs, le texte recherché, le type de média, des tags et des noms de fichiers. Elles n’incluent pas les chemins complets, l’identité de l’utilisateur ni les identifiants d’authentification. Les noms de fichiers quittent votre serveur. C’est normal pour un service de métadonnées, mais vous devez prendre cette décision en connaissance de cause.

Transmettez les livres audio à un lecteur

Chaptarr organise les fichiers. Leur lecture relève d’un autre programme. Audiobookshelf est le partenaire habituel, car il suit votre position d’écoute entre les appareils et propose des applications mobiles. Son image officielle est ghcr.io/advplyr/audiobookshelf:latest. Son exemple Compose documenté publie le port 13378 de l’hôte vers le port 80 du conteneur.

  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

Montez le même chemin hôte que celui dans lequel Chaptarr écrit, puis ajoutez /audiobooks comme bibliothèque dans l’interface web. Le nouvel import apparaît après l’analyse suivante.

Si vous utilisez déjà Jellyfin, vous pouvez y ajouter le dossier comme bibliothèque. Jellyfin lira alors les fichiers, mais la reprise de lecture d’un seul fichier de livre audio long est moins fiable qu’avec un serveur dédié aux livres audio. La configuration de cette solution est présentée dans exécuter Jellyfin comme serveur multimédia sur un VPS. Pour la partie ebooks, transmettez /srv/media/ebooks à une application de lecture. Le rôle de Chaptarr s’arrête une fois que le fichier est nommé et classé.

Risque de maintenance : licence, runtime et version qui évolue rapidement

Chaptarr est distribué sous licence GPL-3.0. Les droits d’auteur appartiennent aux contributeurs de Chaptarr, avec certaines portions provenant de l’équipe Servarr. Le code reste donc ouvert et n’importe qui peut à nouveau créer un fork si ce mainteneur abandonne le projet. Chaptarr repose sur .NET 10, la version LTS actuelle du runtime en août 2026. Le socle est ainsi pris en charge pendant des années plutôt que pendant quelques mois. Ces deux éléments comptent pour évaluer si le projet existera encore l’année prochaine.

Les numéros de version évoluent rapidement. La version 0.9.925 a été publiée le 9 août 2026, puis cinq autres versions sont sorties au cours des sept semaines suivantes. Toutes les versions jusqu’à 0.9.958 ont été publiées en préversion. La version 0.9.965, publiée le 27 septembre 2026, est la première indiquée comme version stable. Utilisez un tag précis. Avec latest, un docker compose pull sans intervention peut vous faire passer plusieurs versions en une semaine. Un fork aussi récent peut modifier son API entre deux versions, ce qui casse les scripts ou les tableaux de bord que vous avez écrits pour l’utiliser. Épingler la version est une habitude à conserver pour tout jeune projet que vous auto-hébergez. C’est pour cette raison que le tutoriel exécuter openGym comme suivi d’entraînement auto-hébergé déploie lui aussi un tag git fixe.

Effectuez une sauvegarde avant chaque mise à niveau, puis lancez la mise à niveau volontairement.

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

Le projet ne signale aucune perte de données sur environ six mois et auprès de plus de onze mille utilisateurs. Il recommande toutefois de conserver des sauvegardes et de ne pas le connecter à une bibliothèque dont la perte serait inacceptable. Prenez ces deux recommandations au sérieux. Copiez l’archive de configuration hors du serveur. Une sauvegarde stockée sur le même disque que les données qu’elle protège n’est pas une sauvegarde. Ce seul tarball suffit uniquement parce que Chaptarr stocke son état dans un seul fichier SQLite sous /config. Tout ce qui se trouve sur un serveur de base de données distinct doit également être exporté. C’est la procédure suivie lorsque vous auto-hébergez Chatwoot sur un VPS avec ses données Postgres et ses fichiers importés.

Modes d’échec et messages affichés

Le conteneur redémarre en boucle. docker compose ps affiche Restarting. Exécutez ls -ln ./config. Deux zéros dans les colonnes du propriétaire indiquent que Docker a créé le répertoire avec root comme propriétaire et que l’utilisateur du conteneur ne peut pas écrire dans sa base de données. Exécutez sudo chown -R 1000:1000 ./config.

Les imports ne se terminent jamais et les fichiers restent dans downloads. Chaptarr peut lire le téléchargement, mais ne peut pas écrire dans la bibliothèque. Comparez ls -ln /srv/media/audiobooks avec votre PUID et PGID. Un répertoire appartenant à un autre UID, ou à votre groupe sans droit d’écriture pour le groupe, empêche le déplacement. UMASK=002 évite le second cas pour les nouveaux fichiers.

L’utilisation du disque double après chaque import. Aucun hardlink n’a été créé : le fichier a donc été copié. Exécutez le test ln de la section sur les volumes. Une erreur se terminant par Invalid cross-device link le confirme. Le montage avec un parent unique corrige le problème.

Le client de téléchargement ne se connecte pas. Vous avez saisi localhost comme hôte. Dans le conteneur, il s’agit de Chaptarr lui-même. Utilisez le nom du conteneur et vérifiez que docker network inspect arr répertorie les deux conteneurs.

Compose refuse de démarrer le service. Bind for 127.0.0.1:8789 failed: port is already allocated signifie qu’un autre processus utilise le port. Trouvez-le avec sudo ss -lntp | grep 8789.

Le navigateur n’affiche absolument rien. Lorsque le port est lié à 127.0.0.1, votre ordinateur portable ne peut rien joindre sur Internet. C’est le comportement attendu. Ouvrez d’abord le tunnel SSH.

FAQ

Puis-je migrer ma bibliothèque Readarr vers Chaptarr ?

Pas en tant qu’import. Chaptarr n’est pas compatible avec les sources de métadonnées de Readarr et utilise son propre pipeline de fournisseurs. Les identifiants enregistrés par Readarr n’ont donc aucune utilité et il n’existe pas de conversion de base de données. Vos fichiers sur disque ne sont pas modifiés. Ajoutez les mêmes chemins comme dossiers racine, lancez un import de bibliothèque et laissez Chaptarr associer lui-même les fichiers. Les profils de qualité, le format de nommage, les paramètres des indexers et les associations incorrectes doivent être traités manuellement. Commencez donc par un petit dossier avant d’importer toute la bibliothèque.

Pourquoi Chaptarr ne peut-il pas écrire dans mon dossier de livres audio ?

L’utilisateur du conteneur n’a pas la permission d’écriture sur ce répertoire, généralement parce qu’il utilise un UID différent de celui qui en est propriétaire. Lorsque ces variables ne sont pas définies, Chaptarr utilise PUID=99 et PGID=100 par défaut. Ce sont les valeurs d’unRAID et elles sont incorrectes sur un VPS Ubuntu standard. Définissez vos propres valeurs id -u et id -g, utilisez la même paire dans le client de téléchargement et définissez UMASK=002 afin que les nouveaux fichiers restent accessibles en écriture pour le groupe. Vérifiez le propriétaire avec ls -ln sur le répertoire de la bibliothèque. Cette commande affiche les nombres plutôt que les noms, ce qui permet de les comparer.

Pourquoi l’utilisation de mon disque a-t-elle doublé après un import ?

Chaptarr a copié le fichier parce qu’il ne pouvait pas créer de hard link. Monter /downloads et /audiobooks comme des bind mounts distincts crée des points de montage différents dans le conteneur. Le kernel refuse alors un hard link entre ces points de montage avec Invalid cross-device link. Montez un répertoire parent tel que /srv/media:/data, puis utilisez /data/downloads et /data/audiobooks dans l’application. Les deux chemins doivent également se trouver sur le même système de fichiers de l’hôte, ce que df -h permet de confirmer.

Chaptarr lit-il mes livres audio ?

Non. Il les recherche, les télécharge, les renomme et les classe. La lecture est assurée par un autre programme. Audiobookshelf est souvent associé à Chaptarr, car il mémorise votre position entre les appareils. Il utilise l’image officielle ghcr.io/advplyr/audiobookshelf:latest, avec le même chemin des livres audio monté depuis l’hôte. Jellyfin peut également lire les fichiers si vous ajoutez le dossier comme bibliothèque, mais la reprise de lecture est moins fiable pour les livres audio constitués d’un seul fichier long.

Est-il sûr d’exécuter Chaptarr sur une bibliothèque à laquelle je tiens ?

Il s’agit d’un logiciel en version bêta issu d’un fork récent. Le projet le précise lui-même, tout en ne signalant aucune perte de données sur environ six mois et auprès de plus de onze mille utilisateurs. Les éléments rassurants sont la licence GPL-3.0, qui permet de forker le code, et la base .NET 10, un runtime à support long terme en août 2026. Épinglez un tag d’image exact tel que 0.9.925 plutôt que latest, sauvegardez /config avant chaque mise à niveau et conservez cette archive hors du serveur.