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 beheert vanuit één instantie. Het controleert op nieuwe releases, stuurt deze naar uw downloadclient, hernoemt vervolgens de resultaten en slaat ze op 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 officiële 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 ondersteuning voor audioboeken 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. Sinds 11 oktober 2026 is de nieuwste release 0.9.965, gepubliceerd op 27 september 2026. De onderstaande stappen zijn alleen getest op 0.9.925, dus de bestanden behouden die tag; lees de release notes voordat u overstapt naar een nieuwere versie. 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 omvangrijk en een import die geen gebruik kan maken van hardlinks houdt tijdelijk twee kopieën van een bestand vast; dit wordt in de onderstaande sectie over volumes toegelicht. Als Docker nog niet op de server staat, begin dan met Docker geïnstalleerd en actief op een VPS en keer daarna terug.

Chaptarr wordt momenteel uitsluitend als Docker-image uitgebracht. Native ondersteuning staat als in ontwikkeling genoteerd, met een experimentele Windows-build in de planning, en er is geen distributiepakket beschikbaar. De container slaat de database standaard op in /config als SQLite, en kan via Chaptarr__Postgres__* omgevingsvariabelen gebruikmaken van een externe PostgreSQL-server als u daar al over beschikt. 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 als u deze niet instelt. Dit zijn de waarden voor unRAID; op een standaard Ubuntu VPS behoren deze tot geen enkele bruikbare gebruiker. Hierdoor krijgen bestanden een eigenaar waar uw account niet naar kan schrijven. Lees uw eigen nummers uit met id -u en id -g en vul 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. Het eigendom van het bestand is niet doorslaggevend: voor het aanmaken, hernoemen of verwijderen van een bestand is schrijftoegang tot de bovenliggende map vereist. Mappen die zijn aangemaakt door gebruiker 1000 met de gebruikelijke 755-modus, geven 99:100 geen schrijftoegang. Hierdoor kan Chaptarr het boek niet in de bibliotheek plaatsen en niet uit de downloads verwijderen. 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 opnieuw opstart. Controleer dit met ls -ln ./config, wat 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 delen van het Servarr-team. De code blijft hierdoor open en kan door anderen worden geforkt als de huidige 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. Versie 0.9.925 werd gepubliceerd op 9 augustus 2026 en in de zeven weken daarna volgden nog vijf releases. Elke release tot 0.9.958 werd gepubliceerd als pre-release; 0.9.965, van 27 september 2026, is de eerste die als volledige release is gemarkeerd. Pin een exacte tag. Het gebruik van latest betekent dat een onbeheerde docker compose pull u in een week tijd meerdere versies vooruit kan helpen. Een fork die zo jong is, kan de API tussen releases wijzigen, wat elk script of dashboard dat u daarop heeft gebaseerd, kan verbreken. Pinnen is een gewoonte die u bij elk jong project dat u zelf host moet toepassen. Dit is precies de reden waarom de handleiding voor het zelf hosten van openGym als workout-tracker implementeert vanaf een vaste git-tag.

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 rapporteert geen dataverlies over een periode van ongeveer zes maanden en meer dan elfduizend gebruikers. Toch adviseert het om back-ups te behouden en het niet te koppelen aan een bibliotheek die u niet kunt missen. Neem beide helften van dit advies serieus. Kopieer het configuratiearchief van de server, want een back-up die op dezelfde schijf staat als de data die het beschermt, is geen back-up. Die ene tarball is alleen voldoende omdat Chaptarr zijn status in één SQLite-bestand onder /config bijhoudt. Alles wat op een aparte databaseserver staat, moet ook worden gedumpt. Dit is de vorm die de back-upstap aanneemt bij het zelf hosten van Chatwoot op een VPS, inclusief de Postgres-data 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 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 heeft geen schrijfrechten op die map, meestal omdat deze draait onder een andere UID dan de eigenaar van de map. 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 op 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 weergeeft in plaats van 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 koppelen 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. Koppel éé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 programma 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 gekoppeld. Jellyfin speelt de bestanden ook af als u de map als bibliotheek toevoegt, 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, en het project geeft dit zelf aan, hoewel er over een periode van ongeveer zes maanden en bij meer dan elfduizend gebruikers geen incidenten met dataverlies zijn gemeld. De geruststellende aspecten zijn de GPL-3.0-licentie, die de code forkbaar houdt, en de .NET 10-basis, een runtime met langetermijnondersteuning 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.