Paano Mag-Host ng Chaptarr para sa Audiobooks sa VPS

Ano ang Chaptarr, at bakit ito kailangan ng mga user ng Readarr

Ang Chaptarr ay fork ng Readarr na namamahala sa mga audiobook at ebook mula sa iisang instance. Minomonitor nito ang mga bagong release, ipinapadala ang mga ito sa download client mo, pagkatapos ay nire-rename ang mga resulta at inaayos ang pagkaka-file ng mga ito sa library mo. Wala itong playback capability, kaya ipares ito sa player gaya ng Audiobookshelf.

Retired na ang Readarr noong 27 June 2025. Malinaw ang dahilan sa sariling notice ng Servarr team: hindi na magamit ang metadata ng proyekto, at natigil ang community effort na lumipat sa Open Library. Naka-archive na ang repository. Dahil dito, naiwan ang mga koleksyon ng libro at audiobook na walang maintained manager, kaya kinuha ng Chaptarr ang tungkuling iyon. Pinapanatili nito ang pamilyar na structure mula sa Sonarr at Radarr (indexers, download clients, quality profiles, root folders) at nagdadagdag ng audiobook handling: narrator-aware na organization, maraming edition ng iisang title, support para sa M4B at chaptered MP3, at conversion mula MP3 papuntang M4B.

Ginamit ng walkthrough na ito ang image tag na chaptarr/chaptarr:0.9.925, na siyang pinakabagong release noong 9 August 2026. Tinatawag ng Chaptarr ang sarili nito na beta software. Basahin ang maintenance section malapit sa dulo bago mo ito ituro sa library na hindi mo kayang palitan.

Mga kailangan bago magsimula

Isang VPS na may Docker at Compose plugin, at sapat na disk space para sa library. Malalaki ang audiobook, at kapag hindi makagamit ng hardlinks ang isang import, pansamantalang may dalawang kopya ng isang file. Ipinaliliwanag ito sa volume section sa ibaba. Kung wala pa ang Docker sa server, magsimula sa Naka-install at tumatakbo ang Docker sa isang VPS at bumalik dito.

Sa ngayon, Docker image lamang ang Chaptarr. Nakalista bilang ginagawa ang native Windows build, at walang distribution package. Iniimbak ng container ang database nito sa /config bilang SQLite by default. Maaari rin itong gumamit ng external PostgreSQL server sa pamamagitan ng Chaptarr__Postgres__* environment variables kung mayroon ka nang pinapatakbo. Ang SQLite ang tamang piliin para sa isang user sa isang server.

Ang Compose service para sa Chaptarr

Isinasama ang service na ito sa isang kasalukuyang stack. Naka-pin ito sa isang released tag, inilalathala lamang nito ang web UI sa loopback, at sumasali ito sa network na ginagamit na ng iyong download client.

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

Ang linyang external: true ay nangangahulugang “umiiral na ang network na ito; i-attach ito.” Gamitin ito kapag nagmumula sa ibang Compose project ang Prowlarr at ang iyong torrent client, dahil kung hindi, gagawa ang ikalawang Compose file ng sarili nitong isolated network at hindi kailanman mareresolba ng Chaptarr ang qbittorrent gamit ang pangalan nito. Kunin ang aktuwal na pangalan gamit ang docker network ls. Kung nasa iisang file na ang iyong stack, idagdag ang chaptarr: service sa file na iyon at burahin sa halip ang buong networks: block. Ipinaliliwanag ang mas malawak na layout sa kumpletong arr stack gamit ang Docker Compose, at ang mga panuntunan sa pagpapangalan sa kung paano nire-resolve ng Compose ang mga network at service name.

Ikaw mismo ang gumawa ng config directory, saka ito i-start.

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

Dapat ipakita ng docker compose ps ang container bilang Up. Ang container na nakalistang Restarting ay nabigong mag-start at sinusubukang muli, at ang sanhi ay halos palaging nasa config directory. Hihinto ang pag-scroll ng log kapag nakikinig na ang app sa port 8789.

PUID, PGID, at ang directory na ginagawa ng Docker bilang root

Naka-default ang Chaptarr sa PUID=99 at PGID=100 kapag hindi mo itinakda ang mga ito. Mga value ito ng unRAID. Sa plain Ubuntu VPS, wala itong kapaki-pakinabang na katumbas na user, kaya ang mga file ay nagkakaroon ng owner na hindi masusulatan ng iyong login. Kunin ang sarili mong mga numero gamit ang id -u at id -g, at ilagay ang mga iyon sa file.

Dapat pareho ang pair ng bawat container na gumagamit ng parehong mga file. Nagsusulat ang download client sa /srv/media/downloads, inililipat ng Chaptarr ang file sa /srv/media/audiobooks, at binabasa ito roon ng player. Kung nagsusulat ang download client bilang 1000:1000 at tumatakbo ang Chaptarr bilang 99:100, mabibigo ang import dahil hindi made-delete o maililipat ng Chaptarr ang file na hindi nito pagmamay-ari. Ginagawa ng UMASK=002 na group-writable ang mga bagong file. Ito ang kailangan kapag maraming container ang gumagamit ng iisang media group. Makikita ang buong mapping sa kung paano inilalagay ng PUID at PGID ang user ng container sa mga file ng host.

Nagbibigay ng babala ang README tungkol sa isang partikular na problema, at mahalagang ulitin ito. Kung wala ang ./config kapag pinatakbo mo ang docker compose up, awtomatikong ginagawa ito ng Docker at inaari bilang root:root. Pagkatapos, tumatakbo ang container bilang UID 1000 at hindi nito masusulatan ang sarili nitong database, kaya patuloy itong nag-e-exit at nagre-restart. Suriin ito gamit ang ls -ln ./config, na nagpi-print ng mga numeric owner sa halip na mga pangalan. Kapag parehong zero ang lumabas, root ang may-ari nito. Ayusin ito gamit ang sudo chown -R 1000:1000 ./config, pagkatapos ay muling simulan ang container.

Bakit hindi gumagana ang hardlinks kapag magkahiwalay ang audiobook at ebook volumes

Naka-mount ang /audiobooks, /ebooks at /downloads bilang magkakahiwalay na bind mount, alinsunod sa sariling run command ng project. Madali itong basahin, pero may isang aktuwal na kapalit: hindi na gumagana ang hardlinks.

Ang hardlink ay pangalawang pangalan para sa parehong data sa disk. Wala itong dagdag na kinakailangang space at agad itong nalilikha, kaya mas gusto ito ng arr family kaysa sa pagkopya. Gumagana lamang ang hardlink sa loob ng iisang filesystem. Sa loob ng container, magkakahiwalay na mount point ang tatlong ito, kaya tinatanggihan ng kernel ang link kahit nasa iisang disk ang mga path sa host. Subukan ito mismo.

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

Nabibigo ang command at nagtatapos ang error sa Invalid cross-device link. Ibig sabihin, tinatanggihan ng kernel ang pag-link sa pagitan ng mga mount point. Ito ang eksaktong dahilan kung bakit bumabalik ang Chaptarr sa pagkopya ng file. Tama ang kopya pero mas mabagal, at dalawang beses na umiiral ang audiobook hanggang alisin mo ang torrent. Hindi mo ito aalisin habang patuloy mo pa itong bina-seed. Tanggalin ang /srv/media/downloads/linktest pagkatapos.

Para manatiling gumagana ang hardlinks, i-mount sa halip ang isang parent directory:

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

Pagkatapos, itakda ang root folders sa loob ng Chaptarr sa /data/audiobooks at /data/ebooks, at bigyan ang download client ng parehong /srv/media:/data mount upang makita ng dalawang container ang eksaktong parehong path. Suriin muna kung iisang filesystem ang nasa host side: dapat mag-print ang df -h /srv/media/downloads /srv/media/audiobooks ng parehong value sa column na Filesystem para sa dalawa. Magkaibang disk ang ibig sabihin ng magkaibang value, at walang mount layout na makagagawa ng hardlink sa pagitan ng mga ito. Tinalakay ang trade-off nito kumpara sa named storage sa bind mounts kumpara sa named volumes para sa media.

Pag-access sa web UI nang hindi ito inilalantad

May dahilan kung bakit nagpa-publish ang port line sa 127.0.0.1. Hindi pinoprotektahan ng ufw deny 8789 ang isang naka-publish na Docker port, dahil nagsusulat ang Docker ng sarili nitong NAT (network address translation) rules sa isang chain na inaabot ng kernel bago ang chain ng ufw. Kaya ipinapasa ang traffic bago man lang masuri ang rule mo. Palaging nagdudulot ng kalituhan ang behavior na ito, at ipinaliwanag ito sa kung bakit binabalewala ng naka-publish na Docker port ang iyong ufw rules. Lubusang nalalampasan ito kapag nag-bind sa loopback.

I-access ang UI sa pamamagitan ng SSH tunnel mula sa sarili mong machine:

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

Panatilihing tumatakbo iyon at buksan ang http://127.0.0.1:8789 sa browser mo. Mag-set up ng authentication sa unang pag-run. Pagkatapos lamang nito dapat mong isaalang-alang ang paglalagay ng reverse proxy na may TLS (transport layer security) sa harap nito. Kapag nagtu-tunnel ka na sa tatlo o apat sa mga tool na ito at magkahiwalay ang password ng bawat isa, mas maayos na ilagay ang proxy sa likod ng self-hosted single sign-on server gaya ng Authentik, para isang login ang sumaklaw sa lahat ng app at isang revocation ang magsara sa access ng lahat.

Ikonekta ang mga indexer at download client

Sinusuportahan ng Chaptarr ang mga standard na protocol para sa arr indexer at download client. Kaya itinutulak ng Prowlarr ang mga indexer papunta rito sa parehong paraan tulad ng ginagawa nito para sa Sonarr. Kumokonekta rito ang karaniwang torrent at usenet client nang walang espesyal na configuration.

May isang setting na nakakalito sa halos lahat. Kapag hinihingi ng Chaptarr ang host ng download client, huwag ilagay ang localhost o 127.0.0.1. Sa loob ng container, ang address na iyon ay tumutukoy sa container mismo. Kaya sinusubukan ng Chaptarr na kumonekta sa sarili nitong port 8080 at nag-uulat na hindi ito makakonekta. Gamitin ang pangalan ng container, qbittorrent, kasama ang port 8080. Tiyaking nasa iisang network ang dalawang container gamit ang docker network inspect arr. Inililista nito ang lahat ng nakakabit na container ayon sa pangalan.

Kung tumatakbo ang download client sa pamamagitan ng VPN container gamit ang network_mode: "service:gluetun", wala itong sariling pangalan sa network dahil ibinabahagi nito ang network namespace ng Gluetun. Gamitin ang gluetun sa port na inilalantad ng Gluetun. Ang setup na iyon, pati ang routing na kasama nito, ay nasa pag-route ng download client sa pamamagitan ng Gluetun.

Ang Readarr break: ang tunay na gastos ng migration

Hindi compatible ang Chaptarr sa metadata sources ng Readarr. Tinutukoy nito ang mga title, author, at edition sa pamamagitan ng sarili nitong pipeline na gumagamit ng ilang provider. Kaya walang silbi rito ang mga identifier na inimbak ng Readarr. Walang database import at walang direktang upgrade path.

Para sa isang umiiral na library, ligtas ang mga file pero hindi ang settings. Walang bahagi ng prosesong ito ang gagalaw sa mga file na nasa disk na. Magdagdag ka ng root folder, magpatakbo ng library import, at itutugma ng Chaptarr ang mga file na makita nito sa sarili nitong metadata. Ito ang kailangan mong buuing muli nang mano-mano: quality profiles, naming format, indexer at client settings, pati ang bawat match na mali ang hula ng Chaptarr. Kakailanganin ng malaking library ng manual corrections, kaya maglaan ng isang gabi sa halip na sampung minuto.

Sundin ang pagkakasunod-sunod na ito. Ihinto ang Readarr container pero panatilihin ang config volume nito, para mabasa mo pa rin ang dati mong settings habang muli mong inilalagay ang mga ito. Ituro muna ang Chaptarr sa isang maliit na folder at suriin ang mga match bago mo i-import ang buong library. Alisin lamang ang lumang container kapag kuntento ka na.

May isang detalye tungkol sa privacy na dapat mong malaman bago i-scan ang buong library: ipinapadala ang metadata lookup sa api2.chaptarr.com. Ayon sa README, maaaring kasama sa mga request na ito ang provider IDs, search text, media type, tags, at filenames, at hindi kasama ang full paths, user identity, at credentials. Umaalis sa server mo ang filenames. Normal ito para sa isang metadata service, pero dapat mo pa ring pagpasiyahan ito nang sinasadya.

Ibigay ang mga audiobook sa isang player

Inaayos ng Chaptarr ang mga file. Ibang program ang nagpe-play sa mga ito. Karaniwang partner ang Audiobookshelf dahil sinusubaybayan nito ang posisyon ng pakikinig sa iba’t ibang device at may mga phone app ito. Ang official image nito ay ghcr.io/advplyr/audiobookshelf:latest, at ang documented Compose example nito ay nagpa-publish ng host port 13378 papunta sa container port 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

I-mount ang parehong host path na sinusulatan ng Chaptarr. Pagkatapos, idagdag ang /audiobooks bilang library sa web UI. Lalabas ang bagong import pagkatapos ng susunod na scan.

Kung nagpapatakbo ka na ng Jellyfin, maaari mong idagdag doon ang folder bilang library at maipe-play nito ang mga file. Gayunman, mas mahina ang resume behavior nito para sa isang audiobook file na mahaba kumpara sa isang purpose-built audiobook server. Saklaw ng pagpapatakbo ng Jellyfin bilang media server sa isang VPS ang pag-set up nito. Para sa bahagi ng ebook, ibigay ang /srv/media/ebooks sa isang reader application. Tapos na ang trabaho ng Chaptarr kapag napangalanan at nailagay na sa tamang folder ang file.

Panganib sa maintenance: licence, runtime, at mabilis magbago na tag

Naka-license ang Chaptarr sa GPL-3.0. Copyright ito ng mga contributor ng Chaptarr, na may ilang bahagi mula sa Servarr team. Dahil dito, nananatiling open ang code at maaaring gumawa ng panibagong fork ang sinuman kung tumigil ang maintainer na ito. Nakabatay ito sa .NET 10, ang kasalukuyang long term support release ng runtime noong August 2026. Ibig sabihin, suportado ang base sa loob ng maraming taon, hindi ilang buwan lamang. Mahalaga ang dalawang puntong ito kung sinusuri mo kung mananatili pa ang project sa susunod na taon.

Mabilis magbago ang mga version number. Inilalabas ang mga release bilang pre-release, at inilabas ang 0.9.925 sa mismong araw ng walkthrough na ito. Mag-pin ng eksaktong tag. Kapag gumamit ka ng latest, maaaring ilipat ka ng isang unattended docker compose pull sa ilang version sa loob ng isang linggo. Maaari ring magbago ang API ng isang fork na ganito kabago sa bawat release. Maaari nitong sirain ang anumang script o dashboard na ginawa mo para rito.

Mag-back up bago ang bawat upgrade, at magsagawa ng upgrade nang sinasadya.

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

Iniuulat ng project na walang naganap na data loss sa loob ng humigit-kumulang anim na buwan at sa mahigit labing-isang libong user. Gayunman, ipinapayo pa rin nitong magpanatili ng backups at huwag itong ituro sa library na hindi mo kayang mawala. Seryosohin ang dalawang bahaging ito. Kopyahin ang config archive palabas ng server, dahil hindi maituturing na backup ang backup na nasa parehong disk ng pinoprotektahan nito. Sapat ang iisang tarball dahil inilalagay ng Chaptarr ang state nito sa isang SQLite file sa ilalim ng /config. Anumang nasa hiwalay na database server ay kailangan ding i-dump ang database. Ito ang anyo ng backup step kapag nag-self-host ng Chatwoot sa isang VPS kasama ang Postgres data at mga na-upload na file.

Mga failure mode at mga string na makikita mo

Paulit-ulit na nagre-restart ang container. Ipinapakita ng docker compose ps ang Restarting. Patakbuhin ang ls -ln ./config. Ang dalawang zero sa mga column ng owner ay nangangahulugang ginawa ng Docker ang directory bilang root, kaya hindi maisulat ng container user ang database nito. Patakbuhin ang sudo chown -R 1000:1000 ./config.

Hindi nakukumpleto ang mga import at nananatili ang mga file sa downloads. Nababasang muli ng Chaptarr ang download, pero hindi ito makapagsulat sa library. Ikumpara ang ls -ln /srv/media/audiobooks sa iyong PUID at PGID. Pinipigilan ang paglipat ng file kapag ibang UID ang may-ari ng directory, o kapag sa iyong group ito pagmamay-ari pero walang group write permission. Pinipigilan ng UMASK=002 ang ikalawang kaso para sa mga bagong file.

Dumodoble ang disk usage pagkatapos ng bawat import. Walang nagawang hardlink, kaya kinopya ang file. Patakbuhin ang test na ln mula sa seksyon ng volumes. Kinukumpirma ito ng error na nagtatapos sa Invalid cross-device link, at ang single-parent mount ang solusyon.

Hindi makakonekta ang download client. localhost ang inilagay mo bilang host. Sa loob ng container, ang Chaptarr mismo iyon. Gamitin ang pangalan ng container at tiyaking inililista ng docker network inspect arr ang parehong container.

Tumangging simulan ng Compose ang service. Ibig sabihin ng Bind for 127.0.0.1:8789 failed: port is already allocated ay may ibang gumagamit sa port. Hanapin ito gamit ang sudo ss -lntp | grep 8789.

Walang ipinapakita ang browser. Kapag naka-bind ang port sa 127.0.0.1, walang makokonektahan ang laptop mo sa internet. Ito ang inaasahang behavior. Buksan muna ang SSH tunnel.

FAQ

Maaari ko bang i-migrate ang Readarr library ko sa Chaptarr?

Hindi bilang import. Hindi compatible ang Chaptarr sa metadata sources ng Readarr at sarili nitong provider pipeline ang ginagamit nito, kaya walang kahulugan ang mga identifier na naka-store sa Readarr at walang database conversion. Hindi naaapektuhan ang mga file mo sa disk. Idagdag ang parehong path bilang root folders, magpatakbo ng library import, at hayaan ang Chaptarr na awtomatikong mag-match sa mga file. Mano-manong kailangang ayusin ang quality profiles, naming format, indexer settings, at anumang maling match, kaya magsimula muna sa isang maliit na folder bago i-import ang lahat.

Bakit hindi makapagsulat ang Chaptarr sa audiobook folder ko?

Hindi pagmamay-ari ng user ng container ang mga file. Nagfa-fallback ang Chaptarr sa PUID=99 at PGID=100 kapag hindi naka-set ang mga variable na iyon. Mga value iyon ng unRAID at mali sa karaniwang Ubuntu VPS. Itakda ang mga ito sa sarili mong id -u at id -g, gamitin ang parehong pair sa download client, at itakda ang UMASK=002 para manatiling group-writable ang mga bagong file. Suriin ang ownership gamit ang ls -ln sa library directory, dahil mga numero ang ipinapakita nito sa halip na mga pangalan at hindi mo maikukumpara ang mga ito.

Bakit dumoble ang disk usage ko pagkatapos ng import?

Kinopya ng Chaptarr ang file dahil hindi ito nakagawa ng hardlink. Kapag hiwalay na bind ang /downloads at /audiobooks, nagiging magkahiwalay na mount point ang mga ito sa loob ng container, at tinatanggihan ng kernel ang hardlink sa pagitan ng mga mount point gamit ang Invalid cross-device link. Mag-mount ng isang parent directory gaya ng /srv/media:/data at gamitin ang /data/downloads at /data/audiobooks sa loob ng app. Dapat nasa iisang host filesystem din ang parehong path. Kinukumpirma ito ng df -h.

Pinapatugtog ba ng Chaptarr ang mga audiobook ko?

Hindi. Hinahanap, dina-download, nire-rename, at inaayos nito ang mga file, pero hiwalay na program ang playback. Karaniwang ipinares ang Audiobookshelf dahil natatandaan nito ang iyong playback position sa iba’t ibang device. Gamitin ang official image na ghcr.io/advplyr/audiobookshelf:latest at i-mount ang parehong host audiobook path. Mapapatugtog din ng Jellyfin ang mga file kapag idinagdag mo ang folder bilang library, pero mas mahina ang resume behaviour nito sa mahahabang audiobook na iisang file.

Ligtas bang patakbuhin ang Chaptarr sa library na mahalaga sa akin?

Beta software ito mula sa isang bagong fork, at mismong project ang nagsasabi nito. Gayunman, wala itong naiulat na data loss event sa loob ng humigit-kumulang anim na buwan at mahigit labing-isang libong user. Kabilang sa mga positibong katangian nito ang GPL-3.0 licence, na nagpapanatiling maaaring i-fork ang code, at ang .NET 10 base, na isang long term support runtime noong August 2026. Mag-pin ng eksaktong image tag gaya ng 0.9.925 sa halip na latest, mag-backup ng /config bago ang bawat upgrade, at panatilihin ang archive na iyon sa labas ng server.