Installer Chaptarr sur un VPS pour livres audio

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 livres numériques depuis une seule instance. Il surveille les nouvelles releases, les transmet à votre download client, puis renomme les fichiers obtenus et les classe dans votre bibliothèque. Il ne lit aucun contenu. Vous devez donc l’associer à un player comme Audiobookshelf.

Readarr a été retiré le 27 June 2025. L’avis publié par l’équipe Servarr indique la raison : les métadonnées du projet étaient devenues inutilisables et les travaux communautaires visant à migrer vers Open Library ont stagné. Le repository est archivé. Les collections de livres et de livres audio se sont donc retrouvées sans gestionnaire maintenu, et Chaptarr a repris cette fonction. Il conserve l’organisation que vous connaissez déjà avec Sonarr et Radarr (indexers, download clients, quality profiles, root folders) et ajoute la gestion des livres audio : organisation prenant en compte le narrateur, gestion de plusieurs éditions d’un même titre, prise en charge des formats M4B et MP3 découpés en chapitres, ainsi que conversion de MP3 vers M4B.

Ce guide utilise l’image tag chaptarr/chaptarr:0.9.925, qui était la release la plus récente le 9 August 2026. Chaptarr se présente comme un logiciel beta. 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 occupent beaucoup d’espace. Un import qui ne peut pas utiliser de hard links conserve deux copies d’un fichier pendant un certain temps, comme l’explique la section consacrée aux volumes ci-dessous. Si Docker n’est pas encore installé sur le serveur, commencez par Installer et exécuter Docker sur un VPS, puis revenez ici.

Pour le moment, Chaptarr est uniquement distribué sous forme d’image Docker. Un build natif pour Windows est annoncé comme étant en cours de développement, et aucun package n’est disponible pour les distributions. Par défaut, le conteneur stocke sa base de données SQLite dans /config. Vous pouvez 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 lorsque vous ne les définissez pas. Ce sont les valeurs d’unRAID. Sur un VPS Ubuntu classique, elles correspondent à un compte qui ne permet pas d’écrire dans les fichiers. Lisez vos propres valeurs avec id -u et id -g, puis indiquez-les dans le fichier.

Tous les conteneurs qui manipulent 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 et que Chaptarr s’exécute avec 99:100, l’import échoue, car Chaptarr ne peut pas supprimer ni déplacer un fichier dont il n’est pas propriétaire. UMASK=002 rend les nouveaux fichiers accessibles en écriture au groupe. C’est ce qu’il faut lorsque plusieurs conteneurs partagent un groupe dédié aux médias. Le mappage complet est décrit dans le mappage de PUID et PGID entre l’utilisateur du conteneur et les fichiers de l’hôte.

Le README signale un piège précis, qui mérite d’être rappelé. 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 et redémarre indéfiniment. Vérifiez avec ls -ln ./config, qui affiche les propriétaires sous forme numérique 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 versions qui évoluent rapidement

Chaptarr est sous licence GPL-3.0. Les contributeurs de Chaptarr en détiennent les droits d’auteur, avec des portions provenant de l’équipe Servarr. Le code reste donc ouvert, et chacun peut de nouveau créer un fork si ce mainteneur arrête le projet. Chaptarr repose sur .NET 10, qui est la version LTS actuelle du runtime en août 2026. Le socle est ainsi pris en charge pendant des années, et non 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. Les releases sont publiées en pre-release, et la version 0.9.925 est sortie le jour même de ce tutoriel. Épinglez un tag précis. Utiliser latest signifie qu’un docker compose pull sans intervention peut vous faire changer de plusieurs versions en une semaine. Un fork aussi récent peut également modifier son API entre deux releases, ce qui casse les scripts ou les dashboards que vous avez écrits pour l’utiliser. Épingler les versions est une habitude à appliquer à tous les projets récents que vous hébergez vous-même. C’est pourquoi le tutoriel exécuter openGym comme tracker d’entraînement auto-hébergé déploie lui aussi le projet depuis un tag git fixe.

Sauvegardez avant chaque upgrade, puis lancez l’upgrade 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 néanmoins 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. Cette seule archive tar suffit uniquement parce que Chaptarr conserve son état dans un fichier SQLite sous /config. Toute donnée stockée sur un serveur de base de données distinct doit également faire l’objet d’un dump. C’est la méthode utilisée à l’étape de sauvegarde pour auto-héberger Chatwoot sur un VPS avec ses données Postgres et ses fichiers téléversé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 sous forme d’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 le disque ne sont pas modifiés. Ajoutez les mêmes chemins comme dossiers racine, lancez un import de bibliothèque et laissez Chaptarr identifier lui-même les fichiers. Les profils de qualité, le format de nommage, les paramètres des indexers et les correspondances 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’est pas propriétaire des fichiers. Chaptarr utilise PUID=99 et PGID=100 par défaut lorsque ces variables ne sont pas définies. Ce sont les valeurs d’unRAID et elles sont incorrectes sur un VPS Ubuntu classique. Définissez vos propres id -u et id -g, utilisez la même paire sur 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 numéros 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 distincts 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 un même système de fichiers de l’hôte, ce que confirme df -h.

Chaptarr lit-il mes livres audio ?

Non. Il les trouve, les télécharge, les renomme et les classe. La lecture est assurée par un autre programme. Audiobookshelf est généralement utilisé avec Chaptarr, car il mémorise votre position entre les appareils. Utilisez l’image officielle ghcr.io/advplyr/audiobookshelf:latest et montez le même chemin hôte vers les livres audio. 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 longs constitués d’un seul fichier.

Chaptarr peut-il être exécuté sans risque sur une bibliothèque importante ?

Il s’agit d’un logiciel en version beta issu d’un fork récent. Le projet l’indique lui-même et ne signale aucune perte de données sur environ six mois, avec plus de onze mille utilisateurs. Les éléments rassurants sont la licence GPL-3.0, qui permet de continuer à maintenir le code dans un fork, 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.