Paano Mag-self-host ng Chaptarr sa VPS para sa Audiobook

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

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

Itinigil 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 ang repository. Dahil dito, naiwan ang mga collection ng libro at audiobook na walang maintained manager, kaya kinuha ng Chaptarr ang tungkuling ito. Pinananatili nito ang pamilyar nang structure mula sa Sonarr at Radarr (indexer, download client, quality profile, root folder) at nagdaragdag ng audiobook handling: organisasyong batay sa narrator, maraming edition ng isang title, suporta sa M4B at chaptered MP3, at conversion mula MP3 patungong M4B.

Ginamit ng walkthrough na ito ang image tag na chaptarr/chaptarr:0.9.925, na siyang pinakabagong release noong 9 August 2026. Noong 11 October 2026, ang pinakabagong release ay 0.9.965, na inilathala noong 27 September 2026. Sinubukan ang mga hakbang sa ibaba sa 0.9.925 lamang, kaya nananatili ang tag na iyon sa mga file; basahin ang release notes bago lumipat sa mas bagong bersyon. Tinutukoy ng Chaptarr ang sarili nito bilang beta software. Basahin ang maintenance section malapit sa dulo bago ito ituro sa library na hindi mo maaaring palitan.

Mga kailangan bago magsimula

Isang VPS na may Docker at Compose plugin, pati sapat na disk space para sa library. Malalaki ang audiobook, at kapag hindi gumamit ng hardlink ang import, pansamantalang nagkakaroon ng dalawang kopya ng isang file. Ipinapaliwanag ito sa seksyon tungkol sa volume sa ibaba. Kung wala pa ang Docker sa server, magsimula sa Naka-install at tumatakbo ang Docker sa isang VPS, at bumalik dito.

Sa kasalukuyan, Docker image lamang ang anyo ng release ng Chaptarr. Kasalukuyang ginagawa ang native support, may planong experimental Windows build, at walang distribution package. Ini-store 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

Ang service na ito ay isinasama sa isang umiiral na stack. Naka-pin ito sa isang specific na release tag, ipinapublish ang web UI sa loopback lamang, at sumasali 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, ikabit dito". Gamitin ito kapag ang Prowlarr at ang iyong torrent client ay galing sa ibang Compose project, dahil kung hindi, gagawa ang pangalawang Compose file ng sarili nitong isolated network at hindi na ma-resolve ng Chaptarr ang qbittorrent sa pamamagitan ng pangalan nito. Kunin ang tamang pangalan mula sa docker network ls. Kung ang iyong stack ay nasa iisang file na, idagdag ang chaptarr: service sa file na iyon at burahin na lang ang buong networks: block. Ang mas malawak na layout ay tinalakay sa isang buong arr stack sa ilalim ng Docker Compose, at ang mga panuntunan sa pagpapangalan sa kung paano nag-re-resolve ang mga Compose network at service name.

Ikaw na ang gumawa ng config directory, pagkatapos ay i-start ito.

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 nakalista bilang Restarting ay nabigong mag-start at sinusubukang ulitin; basahin ang logs nito upang mahanap ang sanhi. Humihinto ang pag-scroll ng log kapag ang app ay nakikinig na sa port 8789.

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

Ang Chaptarr ay gumagamit ng PUID=99 at PGID=100 bilang default kapag hindi mo ito itinakda. Ang mga ito ay value para sa unRAID, at sa isang plain Ubuntu VPS, wala itong katumbas na user, kaya ang mga file ay magkakaroon ng owner na hindi mo mababago gamit ang iyong login. Basahin ang sarili mong mga numero gamit ang id -u at id -g at ilagay ang mga ito sa file.

Ang bawat container na gumagamit ng parehong mga file ay nangangailangan ng parehong pares ng ID. Ang download client ay nagsusulat sa /srv/media/downloads, ililipat ng Chaptarr ang file sa /srv/media/audiobooks, at babasahin ito ng player mula roon. Kung ang download client ay nagsusulat bilang 1000:1000 at ang Chaptarr ay tumatakbo bilang 99:100, mabibigo ang import. Hindi lang ang pagmamay-ari ng file ang mahalaga: ang paggawa, pag-rename, o pagbura ng file ay nangangailangan ng write permission sa directory kung nasaan ito. Ang mga directory na ginawa ng user 1000 na may karaniwang 755 mode ay hindi nagbibigay ng write access sa 99:100, kaya hindi maililipat ng Chaptarr ang libro sa library o mabubura ito mula sa downloads. Ginagawa ng UMASK=002 na group-writable ang mga bagong file, na siyang kailangan mo kapag maraming container ang nagbabahagi ng iisang media group. Ang buong mapping ay nasa kung paano mapa-map ang PUID at PGID ng container user sa mga host file.

Inirerekomenda ng README na gawin muna ang config directory at iwasan ang pag-override sa user: ng Compose. Kung ang ./config ay hindi pa umiiral kapag pinatakbo mo ang docker compose up, gagawin ito ng Docker para sa iyo, na pagmamay-ari ng root:root. Sa naka-pin na 0.9.925 image, ang entrypoint ay nagsisimula bilang root at inaayos ang ownership ng /config at ang mga database file nito bago lumipat sa itinakdang UID at GID, kaya ang bagong gawang directory na pagmamay-ari ng root ay karaniwang hindi nagdudulot ng restart loop. Ang isang user: override ay lumalagpas sa setup na iyon, at ang isang read-only mount o filesystem na tumatanggi sa pagbabago ng ownership ay maaari pa ring humadlang sa pagsusulat sa database. Suriin ito gamit ang ls -ln ./config, na nagpapakita ng numeric owners sa halip na mga pangalan. Ang dalawang zero ay nangangahulugang root ang may-ari nito. Kung kumpirmado sa mga log na may permissions failure sa isang writable local directory, ayusin ito gamit ang sudo chown -R 1000:1000 ./config at simulan muli 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.

I-handa ang mga audiobook para sa player

Ang Chaptarr ang nag-oorganisa ng mga file. Ang pag-play sa mga ito ay trabaho ng ibang program, at ang Audiobookshelf ang karaniwang partner dahil sinusubaybayan nito ang iyong listening position sa iba't ibang device at mayroon itong mga phone app. Ang opisyal na image nito ay ghcr.io/advplyr/audiobookshelf:latest, at ang documented Compose example nito ay naglalathala ng host port 13378 patungo 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 ay idagdag ang /audiobooks bilang library sa loob ng web UI. Lalabas ang bagong import pagkatapos ng susunod na scan.

Kung gumagamit ka na ng Jellyfin, maaari mong idagdag ang folder bilang library doon at i-play nito ang mga file. Ang pag-set up ng bahaging iyon ay tinalakay sa pagpapatakbo ng Jellyfin bilang media server sa isang VPS. Para sa bahagi ng ebook, ibigay ang /srv/media/ebooks sa isang reader application; natatapos ang trabaho ng Chaptarr kapag ang file ay napangalanan at na-file na.

Maintenance risk: lisensya, runtime, at mabilis na pagbabago ng tag

Ang Chaptarr ay lisensyado sa ilalim ng GPL-3.0, na may copyright mula sa mga contributor ng Chaptarr at ilang bahagi mula sa Servarr team, kaya nananatiling open ang code at maaaring i-fork muli ng kahit sino kung sakaling huminto ang maintainer nito. Ito ay binuo sa .NET 10, ang kasalukuyang long term support release ng runtime simula noong Agosto 2026, na nangangahulugang ang base nito ay suportado sa loob ng maraming taon sa halip na buwan lamang. Mahalaga ang dalawang katotohanang ito kung sinusuri mo kung mananatili pa ang proyektong ito sa susunod na taon.

Mabilis ang pagbabago ng mga version number. Ang 0.9.925 ay inilathala noong 9 Agosto 2026, at lima pang release ang sumunod sa loob ng pitong linggo. Ang bawat release hanggang 0.9.958 ay inilathala bilang pre-release; ang 0.9.965, noong 27 Setyembre 2026, ang unang minarkahan bilang full release. I-pin ang eksaktong tag. Ang paggamit ng latest ay nangangahulugang ang isang unattended docker compose pull ay maaaring maglipat sa iyo ng ilang version sa loob ng isang linggo, at ang isang fork na kasing-bata nito ay maaaring magbago ng API sa pagitan ng mga release, na makakasira sa anumang script o dashboard na isinulat mo para rito. Ang pag-pin ay isang ugali na dapat dalhin sa bawat batang proyekto na ikaw mismo ang nag-ho-host, kaya naman ang walkthrough para sa pagpapatakbo ng openGym bilang self-hosted workout tracker ay nagde-deploy mula sa isang fixed git tag para sa parehong dahilan.

Mag-backup bago ang bawat upgrade, at mag-upgrade nang may layunin.

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

Ang proyekto ay nag-uulat ng zero data loss events sa loob ng halos anim na buwan at mahigit labing-isang libong user, at pinapayuhan pa rin nito ang pagpapanatili ng mga backup at huwag itong ituro sa isang library na hindi mo kayang mawala. Seryosohin ang dalawang bahaging ito. Kopyahin ang config archive palabas ng server, dahil ang backup na nasa parehong disk ng bagay na pinoprotektahan nito ay hindi maituturing na backup. Ang iisang tarball na iyon ang sumasaklaw sa local state ng app dahil kasama nito ang mga SQLite database at configuration sa ilalim ng /config; ang anumang nakalagay sa hiwalay na database server ay nangangailangan din ng dump ng database, na siyang anyo ng backup step kapag nag-se-self-host ng Chatwoot sa isang VPS kasama ang Postgres data at mga uploaded file nito.

Mga mode ng failure, kasama ang mga string na makikita mo

Nag-re-restart nang paulit-ulit ang container. Ipinapakita ng docker compose ps ang Restarting. Basahin muna ang docker compose logs chaptarr. Hindi sapat na dahilan ang ./config na pagmamay-ari ng root para mag-loop: karaniwang inaayos ng entrypoint ang ownership nito bago simulan ang app. Kung nakasaad sa logs na hindi writable ang data directory, tingnan kung may Compose user: override, read-only mount, o filesystem na hindi tumatanggap ng pagbabago sa ownership. Alisin ang override para magawa ng entrypoint ang setup nito; para sa maling ownership sa isang writable na local directory, patakbuhin ang sudo chown -R 1000:1000 ./config.

Hindi natatapos ang mga import at nananatili ang mga file sa downloads. Nababasa ng Chaptarr ang download pero hindi ito makapagsulat sa library. Ipaghambing ang ls -ln /srv/media/audiobooks laban sa iyong PUID at PGID. Ang directory na pagmamay-ari ng ibang UID, o pagmamay-ari ng iyong group pero walang group write permission, ang humaharang sa paglipat. Pinipigilan ng UMASK=002 ang pangalawang kaso para sa mga bagong file.

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

Hindi kumokonekta ang download client. Inilagay mo ang localhost bilang host. Sa loob ng container, iyon ay ang Chaptarr mismo. Gamitin ang pangalan ng container at tingnan kung nakalista ang parehong container sa docker network inspect arr.

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

Walang lumalabas sa browser. Dahil naka-bind ang port sa 127.0.0.1, walang konektado sa iyong laptop sa internet. Ito ang inaasahang behavior. Buksan muna ang SSH tunnel.

FAQ

Maaari ko bang ilipat ang aking Readarr library sa Chaptarr?

Hindi ito pwedeng i-import. Hindi compatible ang Chaptarr sa mga metadata source ng Readarr at gumagamit ito ng sariling provider pipeline, kaya walang saysay ang mga stored identifier ng Readarr at walang database conversion na magaganap. Hindi mababago ang iyong mga file sa disk. Idagdag mo lang ang parehong path bilang root folders, patakbuhin ang library import, at hayaan ang Chaptarr na mag-match ng mga file nang kusa. Ang quality profiles, naming format, indexer settings, at anumang maling match ay kailangang gawin nang manual, kaya magsimula muna sa isang maliit na folder bago i-import ang lahat.

Bakit hindi makapagsulat ang Chaptarr sa aking audiobook folder?

Walang write permission ang user ng container sa directory na iyon, kadalasan dahil tumatakbo ito gamit ang ibang UID kumpara sa may-ari nito. Nag-fa-fallback ang Chaptarr sa PUID=99 at PGID=100 kapag hindi naka-set ang mga variable na ito; ang mga ito ay default values ng unRAID at mali para sa isang normal na Ubuntu VPS. I-set ang mga ito sa sarili mong id -u at id -g, gamitin ang parehong pair sa download client, at i-set ang UMASK=002 para manatiling group-writable ang mga bagong file. I-check ang ownership gamit ang ls -ln sa library directory, dahil ipinapakita nito ang mga numero sa halip na pangalan kaya hindi mo ito maihahambing nang direkta.

Bakit dumoble ang disk usage ko matapos ang import?

Kinopya ng Chaptarr ang file dahil hindi nito magawang i-hardlink ang mga ito. Ang pag-mount sa /downloads at /audiobooks bilang magkahiwalay na bind ay gumagawa ng magkahiwalay na mount point sa loob ng container, at tinatanggihan ng kernel ang hardlink sa pagitan ng magkaibang mount point gamit ang Invalid cross-device link. I-mount ang isang parent directory gaya ng /srv/media:/data at gamitin ang /data/downloads at /data/audiobooks sa loob ng app. Dapat ding nasa iisang host filesystem ang parehong path, na kumpirmado ng df -h.

Nagpe-play ba ang Chaptarr ng aking mga audiobook?

Hindi. Ang trabaho nito ay maghanap, mag-download, mag-rename, at mag-file ng mga ito; ang playback ay ginagawa ng ibang program. Ang Audiobookshelf ang karaniwang kapareha nito dahil naaalala nito ang iyong posisyon sa iba't ibang device, gamit ang official image na ghcr.io/advplyr/audiobookshelf:latest na may parehong host audiobook path na naka-mount. Magpe-play din ang Jellyfin ng mga file kung idadagdag mo ang folder bilang isang library.

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

Ito ay beta software mula sa isang bagong fork, at mismong ang proyekto ang nagsasabi nito habang nag-uulat na walang data loss event sa loob ng halos anim na buwan at mahigit labing-isang libong user. Ang mga nakaka-reassure na bahagi ay ang GPL-3.0 licence, na nagpapahintulot na ma-fork ang code, at ang .NET 10 base, isang long term support runtime simula noong August 2026. Mag-pin ng eksaktong image tag gaya ng 0.9.925 sa halip na latest, mag-back up ng /config bago ang bawat upgrade, at itago ang archive na iyon sa labas ng server.