Chaptarr zelf hosten voor audioboeken op een VPS

Wat Chaptarr is en waarom Readarr-gebruikers het nodig hebben

Chaptarr is een fork van Readarr die audioboeken en e-books vanuit één instantie beheert. Het controleert op nieuwe releases, stuurt deze door naar uw downloadclient, hernoemt vervolgens de resultaten en plaatst ze in uw bibliotheek. Het speelt zelf niets af, dus u koppelt het aan een speler zoals Audiobookshelf.

Readarr werd op 27 juni 2025 stopgezet. De eigen mededeling van het Servarr-team geeft de reden: de metadata van het project was onbruikbaar geworden en de inspanningen van de community om over te stappen naar Open Library liepen vast. De repository is gearchiveerd. Hierdoor bleven boek- en audioboekcollecties achter zonder onderhouden beheerder, en Chaptarr heeft deze taak overgenomen. Het behoudt de structuur die u al kent van Sonarr en Radarr (indexers, downloadclients, kwaliteitsprofielen, root folders) en voegt daar audioboekbeheer aan toe: organisatie op basis van verteller, meerdere edities van één titel, ondersteuning voor M4B en MP3 met hoofdstukken, en conversie van MP3 naar M4B.

Deze handleiding gebruikte de image-tag chaptarr/chaptarr:0.9.925, wat de nieuwste release was op 9 augustus 2026. Chaptarr noemt zichzelf bètasoftware. Lees het gedeelte over onderhoud aan het einde voordat u het koppelt aan een bibliotheek die u niet kunt vervangen.

Wat u nodig heeft voordat u begint

Een VPS met Docker en de Compose-plugin, en voldoende schijfruimte voor de bibliotheek. Luisterboeken zijn grote bestanden en een import die geen hardlinks kan gebruiken, houdt tijdelijk twee kopieën van een bestand vast; dit wordt in de onderstaande sectie over volumes uitgelegd. Als Docker nog niet op de server staat, begin dan bij Docker geïnstalleerd en actief op een VPS en keer daarna terug.

Chaptarr wordt op dit moment uitsluitend als Docker-image uitgebracht. Een native Windows-versie is in ontwikkeling, maar er is momenteel geen distributiepakket beschikbaar. De container slaat de database standaard op als SQLite in /config, en kan via Chaptarr__Postgres__*-omgevingsvariabelen verbinding maken met een externe PostgreSQL-server als u die al gebruikt. SQLite is de juiste keuze voor één gebruiker op één server.

De Compose-service voor Chaptarr

Deze service past in een bestaande stack. Het gebruikt een specifieke release-tag, publiceert de web-UI uitsluitend op loopback en koppelt aan het netwerk dat uw downloadclient al gebruikt.

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

De regel external: true betekent "dit netwerk bestaat al, koppel hieraan". Gebruik dit wanneer Prowlarr en uw torrentclient uit een ander Compose-project komen, omdat een tweede Compose-bestand anders een eigen geïsoleerd netwerk aanmaakt en Chaptarr dan qbittorrent niet op naam kan resolven. Achterhaal de werkelijke naam via docker network ls. Als uw stack al in één bestand staat, voeg dan de service chaptarr: toe aan dat bestand en verwijder het volledige networks:-blok. De bredere opzet wordt behandeld in een volledige arr-stack onder Docker Compose, en de naamgevingsregels in hoe Compose-netwerken en servicenamen resolven.

Maak de configuratiemap zelf aan en start de service vervolgens.

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

docker compose ps hoort de container als Up te tonen. Een container die als Restarting wordt vermeld, is niet gestart en wordt opnieuw geprobeerd; de oorzaak is bijna altijd de configuratiemap. De log stopt met scrollen zodra de applicatie luistert op poort 8789.

PUID, PGID en de map die Docker als root aanmaakt

Chaptarr gebruikt standaard PUID=99 en PGID=100 wanneer u deze niet instelt. Dit zijn de waarden van unRAID; op een standaard Ubuntu VPS behoren deze tot niemand die nuttig is. Hierdoor krijgen bestanden een eigenaar waar uw account niet naar kan schrijven. Lees uw eigen nummers uit met id -u en id -g en voer deze in het bestand in.

Elke container die dezelfde bestanden benadert, heeft hetzelfde paar nodig. De downloadclient schrijft naar /srv/media/downloads, Chaptarr verplaatst het bestand naar /srv/media/audiobooks en de speler leest het daar. Als de downloadclient schrijft als 1000:1000 en Chaptarr draait als 99:100, dan mislukt het importeren omdat Chaptarr een bestand dat het niet bezit niet kan verwijderen of verplaatsen. UMASK=002 maakt nieuwe bestanden schrijfbaar voor de groep; dit is gewenst wanneer meerdere containers één mediagroep delen. De volledige toewijzing staat in hoe PUID en PGID een containergebruiker toewijzen aan hostbestanden.

De README waarschuwt voor één specifieke valkuil, die het herhalen waard is. Als ./config niet bestaat wanneer u docker compose up uitvoert, maakt Docker deze voor u aan, met root:root als eigenaar. De container draait vervolgens als UID 1000 en kan zijn eigen database niet beschrijven, waardoor deze afsluit en oneindig blijft herstarten. Controleer dit met ls -ln ./config, dat numerieke eigenaren toont in plaats van namen. Twee nullen betekenen dat root de eigenaar is. Herstel dit met sudo chown -R 1000:1000 ./config en start de container opnieuw.

Waarom gescheiden volumes voor audioboeken en ebooks hardlinks onmogelijk maken

De bovenstaande indeling koppelt /audiobooks, /ebooks en /downloads als afzonderlijke binds, conform het eigen run-commando van het project. Dit is overzichtelijk, maar heeft één concreet nadeel: hardlinks werken niet meer.

Een hardlink is een tweede naam voor dezelfde data op de schijf. Het verbruikt geen extra ruimte en is direct klaar, wat de reden is dat de arr-familie dit verkiest boven kopiëren. Een hardlink werkt alleen binnen één bestandssysteem. Binnen de container zijn dit drie afzonderlijke aankoppelpunten, waardoor de kernel de link weigert, zelfs als de host-paden op dezelfde schijf staan. Test dit zelf.

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

Het commando faalt met een foutmelding die eindigt op Invalid cross-device link. Dit is de kernel die weigert te linken over aankoppelpunten heen, en dit is precies de reden waarom Chaptarr terugvalt op het kopiëren van het bestand. De kopie is correct maar trager, en het audioboek bestaat vervolgens twee keer totdat u de torrent verwijdert, wat u niet zult doen zolang u deze nog seedt. Verwijder /srv/media/downloads/linktest achteraf.

Om hardlinks te behouden, koppelt u in plaats daarvan één bovenliggende map:

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

Stel vervolgens de root-mappen in Chaptarr in op /data/audiobooks en /data/ebooks, en geef de download-client hetzelfde /srv/media:/data-aankoppelpunt zodat beide containers één identiek pad zien. Controleer eerst of de host-zijde één enkel bestandssysteem is: df -h /srv/media/downloads /srv/media/audiobooks moet voor beide dezelfde waarde in de kolom Filesystem weergeven. Verschillende waarden betekenen verschillende schijven, en geen enkele aankoppelingsindeling kan daaroverheen hardlinken. De afweging tussen deze methode en named volumes wordt behandeld in bind mounts tegenover named volumes voor media.

De web-UI bereiken zonder deze bloot te stellen

De poortregel publiceert op 127.0.0.1 met een reden. ufw deny 8789 beschermt een gepubliceerde Docker-poort niet, omdat Docker zijn eigen NAT-regels (network address translation) schrijft naar een chain die de kernel bereikt vóór die van ufw. Het verkeer wordt dus doorgestuurd voordat uw regel ooit wordt geraadpleegd. Dit gedrag verrast gebruikers constant en wordt uitgelegd in waarom een gepubliceerde Docker-poort uw ufw-regels negeert. Binden aan loopback omzeilt dit volledig.

Bereik de UI via een SSH-tunnel vanaf uw eigen machine:

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

Laat dit draaien en open http://127.0.0.1:8789 in uw browser. Stel bij de eerste keer opstarten authenticatie in. Overweeg pas daarna een reverse proxy met TLS (transport layer security) ervoor te plaatsen. Zodra u via tunnels verbinding maakt met drie of vier van deze tools, elk met een apart wachtwoord, is de nettere oplossing om de proxy achter een zelfgehoste single sign-on server zoals Authentik te plaatsen, zodat één login alle applicaties dekt en één intrekking ze allemaal afsluit.

Indexers en de downloadclient koppelen

Chaptarr ondersteunt de standaard protocollen voor indexers en downloadclients van de arr-suite. Prowlarr pusht indexers daarom op dezelfde wijze naar Chaptarr als naar Sonarr, en de gebruikelijke torrent- en usenet-clients kunnen zonder extra configuratie worden gekoppeld.

Eén instelling zorgt bij bijna iedereen voor problemen. Wanneer Chaptarr vraagt om de host van de downloadclient, typ dan niet localhost of 127.0.0.1. Binnen een container verwijst dat adres naar de container zelf; Chaptarr probeert dan verbinding te maken met zijn eigen poort 8080 en meldt dat er geen verbinding mogelijk is. Gebruik de containernaam, qbittorrent, met poort 8080. Controleer of beide containers zich op hetzelfde netwerk bevinden met docker network inspect arr, waarmee alle gekoppelde containers op naam worden weergegeven.

Als uw downloadclient via een VPN-container met network_mode: "service:gluetun" draait, heeft deze geen eigen naam op het netwerk omdat de netwerk-namespace van Gluetun wordt gedeeld. Adresseer deze als gluetun op de poort die Gluetun openstelt. Die configuratie, inclusief de bijbehorende routering, staat beschreven in een downloadclient routeren via Gluetun.

De Readarr-breuk: wat een migratie werkelijk kost

Chaptarr is niet compatibel met de metadatabronnen van Readarr. Het programma herleidt titels, auteurs en edities via een eigen pipeline die gebruikmaakt van diverse aanbieders; de identifiers die Readarr heeft opgeslagen, zijn hierdoor onbruikbaar. Er is geen database-import en geen direct upgradepad.

Voor een bestaande bibliotheek betekent dit dat de bestanden veilig zijn, maar de instellingen niet. Niets in dit proces heeft invloed op wat er al op de schijf staat. U voegt een root folder toe, voert een bibliotheekimport uit en Chaptarr koppelt de gevonden bestanden aan zijn eigen metadata. Wat u handmatig moet herbouwen: kwaliteitsprofielen, naamgevingsformaten, indexer- en clientinstellingen, en elke koppeling die Chaptarr onjuist inschat. Een grote bibliotheek vereist een ronde handmatige correcties; houd daarom rekening met een avond werk in plaats van tien minuten.

Hanteer deze volgorde. Stop de Readarr-container, maar behoud het configuratievolume zodat u uw oude instellingen kunt inzien terwijl u ze overtypt. Wijs Chaptarr eerst naar één kleine map en controleer de koppelingen voordat u alles importeert. Verwijder de oude container pas zodra u tevreden bent.

Een privacy-detail dat de moeite waard is om te weten voordat u een volledige bibliotheek scant: metadata-opvragingen gaan naar api2.chaptarr.com. De README vermeldt dat deze verzoeken provider-ID's, zoektekst, mediatype, tags en bestandsnamen kunnen bevatten, en dat ze volledige paden, gebruikersidentiteit en inloggegevens uitsluiten. Bestandsnamen verlaten uw server. Dit is gebruikelijk voor een metadataservice, maar u dient hier bewust een besluit over te nemen.

Audioboeken overdragen aan een speler

Chaptarr organiseert bestanden. Het afspelen ervan is de taak van een ander programma, en Audiobookshelf is de gebruikelijke partner omdat deze uw luisterpositie op verschillende apparaten bijhoudt en over mobiele apps beschikt. De officiële image is ghcr.io/advplyr/audiobookshelf:latest, en het gedocumenteerde Compose-voorbeeld publiceert hostpoort 13378 naar containerpoort 80.

  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

Koppel hetzelfde hostpad waarnaar Chaptarr schrijft en voeg vervolgens /audiobooks toe als bibliotheek in de web-UI. Na de volgende scan verschijnt er een nieuwe import.

Als u al Jellyfin gebruikt, kunt u de map daar als bibliotheek toevoegen en zullen de bestanden worden afgespeeld, hoewel de hervattingsfunctionaliteit bij een enkel lang audioboekbestand minder robuust is dan bij een specifieke audioboekserver. Het opzetten daarvan wordt behandeld in Jellyfin draaien als mediaserver op een VPS. Voor het e-boekgedeelte geeft u /srv/media/ebooks door aan een leesapplicatie; de taak van Chaptarr eindigt zodra het bestand is benoemd en opgeslagen.

Onderhoudsrisico: licentie, runtime en een snel veranderende tag

Chaptarr is gelicentieerd onder de GPL-3.0, met auteursrecht voor de Chaptarr-bijdragers en gedeelten van het Servarr-team. Hierdoor blijft de code open en kan iedereen het project opnieuw forken als deze beheerder stopt. Het is gebouwd op .NET 10, de huidige long-term support-release van de runtime per augustus 2026. Dit betekent dat de basis voor jaren in plaats van maanden wordt ondersteund. Beide feiten zijn van belang als u beoordeelt of dit project volgend jaar nog zal bestaan.

De versienummers veranderen snel. Releases worden gepubliceerd als pre-releases, en 0.9.925 verscheen op dezelfde dag als deze handleiding. Pin een exacte tag vast. Het gebruik van latest betekent dat een onbeheerde docker compose pull u in een week tijd meerdere versies verder kan brengen. Een fork die zo jong is, kan zijn API tussen releases wijzigen, wat elk script of dashboard dat u daarop heeft gebaseerd, kan verbreken.

Maak een back-up voor elke upgrade en voer upgrades bewust uit.

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

Het project meldt in ongeveer zes maanden en bij meer dan elfduizend gebruikers geen incidenten met dataverlies. Toch adviseert het om back-ups te bewaren en het niet te koppelen aan een bibliotheek die u niet kunt missen. Neem beide adviezen serieus. Kopieer het configuratiearchief van de server af. Een back-up op dezelfde schijf als de gegevens die deze moet beschermen, is geen back-up. Dat ene tar-archief volstaat alleen omdat Chaptarr zijn status in één SQLite-bestand onder /config bewaart. Alles wat op een afzonderlijke databaseserver staat, moet u ook naar een dump exporteren. Dat is ook de vorm die de back-upstap aanneemt wanneer u Chatwoot zelf hosten op een VPS naast de Postgres-gegevens en geüploade bestanden.

Foutmodi en de bijbehorende meldingen

De container start in een lus opnieuw op. docker compose ps toont Restarting. Voer ls -ln ./config uit. Twee nullen in de eigenaarskolommen betekenen dat Docker de map als root heeft aangemaakt en de containergebruiker niet naar de database kan schrijven. Voer sudo chown -R 1000:1000 ./config uit.

Imports voltooien nooit en bestanden blijven in de downloads staan. Chaptarr kan de download lezen, maar niet naar de bibliotheek schrijven. Vergelijk ls -ln /srv/media/audiobooks met uw PUID en PGID. Een map die eigendom is van een andere UID, of die eigendom is van uw groep zonder schrijfrechten voor de groep, blokkeert de verplaatsing. UMASK=002 voorkomt het tweede geval voor nieuwe bestanden.

Schijfgebruik verdubbelt na elke import. Er is geen hardlink gemaakt, waardoor het bestand is gekopieerd. Voer de ln-test uit vanuit de sectie volumes. Een foutmelding die eindigt op Invalid cross-device link bevestigt dit, en de mount met één bovenliggende map is de oplossing.

De downloadclient maakt geen verbinding. U heeft localhost ingevoerd als host. Binnen de container is dat Chaptarr zelf. Gebruik de containernaam en controleer of docker network inspect arr beide containers vermeldt.

Compose weigert de service te starten. Bind for 127.0.0.1:8789 failed: port is already allocated betekent dat iets anders de poort bezet houdt. Zoek dit op met sudo ss -lntp | grep 8789.

De browser toont helemaal niets. Met de poort gebonden aan 127.0.0.1 is er niets waar uw laptop via internet verbinding mee kan maken. Dat is het beoogde gedrag. Open eerst de SSH-tunnel.

FAQ

Kan ik mijn Readarr-bibliotheek migreren naar Chaptarr?

Niet als een directe import. Chaptarr is niet compatibel met de metadatabronnen van Readarr en gebruikt een eigen provider-pipeline. De opgeslagen identifiers van Readarr hebben daarom geen betekenis en er is geen databaseconversie mogelijk. Uw bestanden op de schijf blijven onaangetast. U voegt dezelfde paden toe als root-mappen, voert een bibliotheekimport uit en laat Chaptarr de bestanden zelf matchen. Kwaliteitsprofielen, naamgevingsformaten, indexer-instellingen en eventuele onjuiste matches vereisen handmatig werk. Begin daarom met één kleine map voordat u alles importeert.

Waarom kan Chaptarr niet naar mijn luisterboekenmap schrijven?

De gebruiker van de container is niet de eigenaar van de bestanden. Chaptarr valt terug op PUID=99 en PGID=100 wanneer deze variabelen niet zijn ingesteld; dit zijn unRAID-waarden die onjuist zijn op een standaard Ubuntu VPS. Stel deze in op uw eigen id -u en id -g, gebruik hetzelfde paar voor de downloadclient en stel UMASK=002 in zodat nieuwe bestanden schrijfbaar blijven voor de groep. Controleer het eigenaarschap met ls -ln op de bibliotheekmap, aangezien dit de nummers toont in plaats van de namen, waardoor u ze niet kunt vergelijken.

Waarom is mijn schijfgebruik verdubbeld na een import?

Chaptarr heeft het bestand gekopieerd omdat het geen hardlink kon maken. Het mounten van /downloads en /audiobooks als afzonderlijke binds maakt er aparte mount points van binnen de container, en de kernel weigert een hardlink over mount points heen met Invalid cross-device link. Mount één bovenliggende map zoals /srv/media:/data en gebruik /data/downloads en /data/audiobooks binnen de applicatie. Beide paden moeten zich ook op hetzelfde host-bestandssysteem bevinden, wat df -h bevestigt.

Speelt Chaptarr mijn luisterboeken af?

Nee. Het zoekt, downloadt, hernoemt en ordent ze; het afspelen is een taak voor een ander programma. Audiobookshelf is de gebruikelijke combinatie omdat dit uw positie onthoudt op verschillende apparaten. Gebruik hiervoor de officiële image ghcr.io/advplyr/audiobookshelf:latest met hetzelfde host-pad voor luisterboeken gemount. Jellyfin kan de bestanden ook afspelen als u de map toevoegt als bibliotheek, al is de hervattingsfunctie bij lange luisterboeken in één bestand minder accuraat.

Is het veilig om Chaptarr te draaien op een bibliotheek die ik belangrijk vind?

Het is bèta-software van een jonge fork. Het project geeft dit zelf aan, hoewel er over een periode van ongeveer zes maanden en bij meer dan elfduizend gebruikers geen meldingen zijn van dataverlies. De geruststellende factoren zijn de GPL-3.0 licentie, die de code forkbaar houdt, en de .NET 10 basis, een runtime met langdurige ondersteuning (LTS) vanaf augustus 2026. Pin een exacte image-tag zoals 0.9.925 in plaats van latest, maak een back-up van /config vóór elke upgrade en bewaar dat archief buiten de server.