Jinsi ya kusakinisha Chaptarr kwenye VPS yako

Chaptarr ni nini, na kwa nini watumiaji wa Readarr wanaihitaji

Chaptarr ni fork ya Readarr inayodhibiti vitabu vya sauti (audiobooks) na vitabu vya kielektroniki (ebooks) kutoka kwenye mfumo mmoja. Inafuatilia matoleo mapya, inayatuma kwenye mteja wako wa kupakua (download client), kisha inabadilisha majina ya matokeo na kuyahifadhi kwenye maktaba yako. Haitumiki kucheza faili, kwa hivyo unaiunganisha na kichezaji kama Audiobookshelf.

Readarr ilisitishwa tarehe 27 Juni 2025. Notisi ya timu ya Servarr yenyewe inatoa sababu: metadata ya mradi huo ilikuwa imekuwa haiwezi kutumika, na juhudi za jamii kuhamia Open Library zilikwama. Hifadhi (repository) hiyo imewekwa kwenye kumbukumbu (archived). Hilo liliacha makusanyo ya vitabu na vitabu vya sauti bila meneja anayesimamiwa, na Chaptarr ikachukua jukumu hilo. Inadumisha muundo unaoufahamu tayari kutoka Sonarr na Radarr (indexers, download clients, quality profiles, root folders) na kuongeza usimamizi wa vitabu vya sauti: mpangilio unaozingatia msomaji (narrator-aware), matoleo mengi ya kichwa kimoja, usaidizi wa M4B na MP3 zenye sura (chaptered MP3), na ubadilishaji wa MP3 kuwa M4B.

Mwongozo huu umetumia image tag chaptarr/chaptarr:0.9.925, ambayo ilikuwa toleo jipya zaidi mnamo 9 Agosti 2026. Chaptarr inajiita programu ya beta. Soma sehemu ya matengenezo (maintenance) karibu na mwisho kabla ya kuielekeza kwenye maktaba ambayo huwezi kuibadilisha.

Unachohitaji kabla ya kuanza

VPS inayoendesha Docker na Compose plugin, pamoja na nafasi ya kutosha ya diski kwa ajili ya maktaba yako. Vitabu vya sauti (audiobooks) vinachukua nafasi kubwa, na uingizaji wa data (import) ambao hauwezi kutumia hardlinks utahifadhi nakala mbili za faili kwa muda, jambo ambalo sehemu ya volume hapa chini inalifafanua. Ikiwa Docker haijawekwa kwenye seva yako, anza na Docker ikiwa imewekwa na inaendeshwa kwenye VPS kisha urudi hapa.

Chaptarr inatolewa kama Docker image pekee kwa sasa. Toleo la asili la Windows linatajwa kuwa linafanyiwa kazi, na hakuna kifurushi cha usambazaji (distribution package). Container hii huhifadhi database yake katika /config kama SQLite kwa chaguo-msingi, na inaweza kutumia seva ya nje ya PostgreSQL kupitia vigezo vya mazingira (environment variables) vya Chaptarr__Postgres__* ikiwa tayari unayo moja. SQLite ndilo chaguo sahihi kwa mtumiaji mmoja kwenye seva moja.

Huduma ya Compose kwa ajili ya Chaptarr

Huduma hii inaingia kwenye stack iliyopo. Inatumia tag iliyotolewa, inachapisha web UI kwenye loopback pekee, na inaunganisha kwenye mtandao ambao mteja wako wa kupakua (download client) anautumia.

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

Mstari wa external: true unamaanisha "mtandao huu tayari upo, jiunge nao". Itumie wakati Prowlarr na mteja wako wa torrent wanatoka kwenye mradi mwingine wa Compose, kwa sababu faili la pili la Compose huunda mtandao wake uliotengwa na Chaptarr haitaweza kutatua qbittorrent kwa jina. Pata jina halisi kutoka docker network ls. Ikiwa stack yako iko kwenye faili moja tayari, ongeza huduma ya chaptarr: kwenye faili hilo na ufute kizuizi chote cha networks: badala yake. Mpangilio mpana zaidi umeelezwa katika stack kamili ya arr chini ya Docker Compose, na kanuni za utoaji majina katika jinsi mitandao ya Compose na majina ya huduma yanavyotatuliwa.

Unda saraka ya usanidi (config directory) mwenyewe, kisha uianzishe.

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

docker compose ps inapaswa kuonyesha container kama Up. Container iliyoorodheshwa kama Restarting imeshindwa kuanza na inajaribiwa tena, na sababu karibu kila mara ni saraka ya usanidi. Log huacha kusonga mara tu programu inaposikiliza kwenye port 8789.

PUID, PGID, na saraka inayoundwa na Docker kama root

Chaptarr hutumia PUID=99 na PGID=100 kama chaguo-msingi unapoziacha bila kusanidiwa. Hizo ni thamani za unRAID, na kwenye VPS ya kawaida ya Ubuntu hazimilikiwi na mtumiaji yeyote muhimu, kwa hivyo faili huwekwa na mmiliki ambaye akaunti yako haiwezi kuandikia. Soma namba zako mwenyewe kwa kutumia id -u na id -g kisha uziweke kwenye faili hiyo.

Kila kontena linalogusa faili zilezile linahitaji jozi hiyo hiyo. Mteja wa kupakua (download client) huandika kwenye /srv/media/downloads, Chaptarr huhamisha faili hiyo kwenda /srv/media/audiobooks, na kichezaji huisoma hapo. Ikiwa mteja wa kupakua anaandika kama 1000:1000 na Chaptarr inaendeshwa kama 99:100, uingizaji (import) utafeli kwa sababu Chaptarr haiwezi kufuta au kuhamisha faili isiyoimiliki. UMASK=002 hufanya faili mpya ziweze kuandikika na kundi (group-writable), jambo ambalo ni muhimu wakati makontena kadhaa yanashiriki kundi moja la media. Ramani kamili iko kwenye jinsi PUID na PGID zinavyounganisha mtumiaji wa kontena na faili za host.

README inaonya kuhusu mtego mmoja mahususi, na inafaa kurudiwa. Ikiwa ./config haipo unapoendesha docker compose up, Docker itakuundia saraka hiyo, ikimilikiwa na root:root. Kontena kisha litaendeshwa kama UID 1000 na halitaweza kuandika hifadhidata yake yenyewe, kwa hivyo litaacha kufanya kazi na kuanza upya milele. Hakiki kwa kutumia ls -ln ./config, ambayo huchapisha wamiliki wa namba badala ya majina. Sifuri mbili inamaanisha root ndiye mmiliki. Rekebisha kwa sudo chown -R 1000:1000 ./config na uanzishe kontena hilo tena.

Kwa nini ujazo tofauti wa audiobook na ebook hugharimu hardlinks

Mpangilio hapo juu huweka /audiobooks, /ebooks na /downloads kama binds tofauti, kulingana na amri ya uendeshaji ya mradi wenyewe. Ni rahisi kusoma, na ina gharama moja halisi: hardlinks huacha kufanya kazi.

Hardlink ni jina la pili la data ileile kwenye diski. Haitumii nafasi ya ziada na ni ya papo hapo, ndiyo maana familia ya arr huipendelea kuliko kunakili. Hardlink hufanya kazi ndani ya filesystem moja pekee. Ndani ya container hizi ni sehemu tatu tofauti za mount, kwa hivyo kernel hukataa link hiyo hata kama njia za host ziko kwenye diski moja. Jipime mwenyewe.

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

Amri hiyo inafeli na hitilafu inayoishia na Invalid cross-device link. Hiyo ni kernel inayokataa kuunganisha (link) kwenye sehemu tofauti za mount, na ndiyo sababu hasa Chaptarr hurudi kwenye kunakili faili. Nakala hiyo ni sahihi lakini ni ya polepole, na audiobook kisha huwepo mara mbili hadi utakapofuta torrent, jambo ambalo hutalifanya wakati bado una-seed. Futa /srv/media/downloads/linktest baadaye.

Ili kuhifadhi hardlinks, weka saraka moja kuu (parent directory) badala yake:

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

Kisha weka root folders ndani ya Chaptarr kuwa /data/audiobooks na /data/ebooks, na upe download client mount ileile ya /srv/media:/data ili container zote mbili zione njia moja inayofanana. Thibitisha kwanza kuwa upande wa host ni filesystem moja: df -h /srv/media/downloads /srv/media/audiobooks lazima ichapishe thamani ileile kwenye safu ya Filesystem kwa zote mbili. Thamani tofauti inamaanisha diski tofauti, na hakuna mpangilio wa mount unaoweza kufanya hardlink kuvuka diski hizo. Uwiano kati ya njia hii na named storage umejadiliwa katika bind mounts dhidi ya named volumes kwa ajili ya media.

Kufikia kiolesura cha wavuti bila kukiweka hadharani

Mstari wa port huchapisha kwenye 127.0.0.1 kwa sababu maalum. ufw deny 8789 haikulindi port ya Docker iliyochapishwa, kwa sababu Docker huandika sheria zake za NAT (network address translation) kwenye mnyororo ambao kernel huufikia kabla ya ufw, hivyo trafiki husambazwa kabla ya sheria yako kuangaliwa. Tabia hiyo huwashangaza watu mara kwa mara, na inaelezwa katika kwa nini port ya Docker iliyochapishwa hupuuza sheria zako za ufw. Kujifunga kwenye loopback huiepuka hali hiyo kabisa.

Fikia kiolesura hicho kupitia SSH tunnel kutoka kwenye mashine yako:

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

Iache hiyo ikiendelea kufanya kazi na ufungue http://127.0.0.1:8789 kwenye kivinjari chako. Sanidi uthibitishaji (authentication) wakati wa kuanza kwa mara ya kwanza. Baada ya hapo ndipo unapaswa kufikiria kutumia reverse proxy yenye TLS (transport layer security) mbele yake. Mara tu unapokuwa ukitumia tunnel kufikia zana tatu au nne za aina hii ukiwa na nenosiri tofauti kwa kila moja, jibu nadhifu zaidi ni kuweka proxy nyuma ya seva ya single sign-on inayojiendesha yenyewe kama vile Authentik, ili login moja ifunike kila programu na ubatilishaji mmoja uifunge yote.

Unganisha indexers na mteja wa kupakua

Chaptarr inatumia itifaki za kawaida za indexer na mteja wa kupakua za arr, kwa hivyo Prowlarr inasukuma indexers ndani yake kama inavyofanya kwa Sonarr, na wateja wa kawaida wa torrent na usenet huunganishwa bila kuhitaji hatua maalum.

Kuna mpangilio mmoja ambao huwakwaza karibu watu wote. Chaptarr inapouliza host ya mteja wa kupakua, usichape localhost au 127.0.0.1. Ndani ya container, anwani hiyo ni container yenyewe, kwa hivyo Chaptarr hujaribu kuongea na port yake yenyewe ya 8080 na kuripoti kuwa haiwezi kuunganishwa. Tumia jina la container, qbittorrent, pamoja na port 8080. Thibitisha kuwa container zote mbili ziko kwenye mtandao mmoja kwa kutumia docker network inspect arr, ambayo huorodhesha kila container iliyounganishwa kwa jina lake.

Ikiwa mteja wako wa kupakua anaendeshwa kupitia container ya VPN na network_mode: "service:gluetun", haina jina lake kwenye mtandao, kwa sababu inashiriki namespace ya mtandao ya Gluetun. Ielekeze kama gluetun kwenye port ambayo Gluetun inafungua. Mpangilio huo, na routing inayoambatana nao, iko kwenye routing a download client through Gluetun.

Kikwazo cha Readarr: gharama halisi ya kuhama

Chaptarr haioani na vyanzo vya metadata vya Readarr. Inatafuta majina ya vitabu, waandishi na matoleo kupitia mfumo wake wa ndani unaotumia watoa huduma mbalimbali, kwa hivyo vitambulishi vilivyohifadhiwa na Readarr havina maana hapa. Hakuna uwezekano wa kuingiza database (import) wala njia ya moja kwa moja ya kuboresha (upgrade).

Kwa maktaba iliyopo, hii inamaanisha kuwa faili zako ziko salama lakini mipangilio si salama. Hakuna hatua yoyote katika mchakato huu inayogusa faili zilizopo kwenye diski. Unaongeza folda kuu (root folder), unafanya import ya maktaba, na Chaptarr inalinganisha faili inazozipata na metadata yake yenyewe. Mambo unayopaswa kujenga upya kwa mikono ni: quality profiles, muundo wa majina (naming format), mipangilio ya indexer na client, pamoja na kila kitabu ambacho Chaptarr imekosea kukilinganisha. Maktaba kubwa itahitaji muda wa kufanya marekebisho ya mikono, kwa hivyo tenga jioni nzima badala ya dakika kumi.

Fuata utaratibu huu. Simamisha container ya Readarr lakini usifute volume yake ya config, ili uweze kusoma mipangilio yako ya zamani wakati unaiandika upya. Elekeza Chaptarr kwenye folda moja ndogo kwanza na uhakiki ulinganifu kabla ya kuingiza kila kitu. Ondoa container ya zamani pale tu utakapokuwa umeridhika.

Kuna jambo moja la faragha unalopaswa kulijua kabla ya kuchanganua maktaba nzima: utafutaji wa metadata unaelekezwa kwenye api2.chaptarr.com. README inaeleza kuwa maombi hayo yanaweza kubeba vitambulishi vya mtoa huduma, maandishi ya utafutaji, aina ya maudhui, vitambulisho (tags) na majina ya faili, na kwamba hayajumuishi njia kamili za faili (full paths), utambulisho wa mtumiaji au nywila. Majina ya faili yanatoka nje ya seva yako. Hilo ni jambo la kawaida kwa huduma ya metadata, na bado unapaswa kuliamua kwa makusudi.

Kukabidhi vitabu vya sauti kwa kichezaji

Chaptarr hupanga faili. Uchezaji wa faili hizo ni kazi ya programu nyingine, na Audiobookshelf ndiyo mshirika wa kawaida kwa sababu hufuatilia nafasi yako ya kusikiliza kwenye vifaa mbalimbali na ina programu za simu. Image yake rasmi ni ghcr.io/advplyr/audiobookshelf:latest, na mfano wake wa Compose uliowekwa kwenye nyaraka huchapisha port ya seva 13378 kwenye port ya container 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

Mount njia ileile ya seva ambayo Chaptarr huandikia, kisha ongeza /audiobooks kama maktaba ndani ya web UI. Import mpya itaonekana baada ya scan inayofuata.

Ikiwa tayari unatumia Jellyfin, unaweza kuongeza folda hiyo kama maktaba huko na itacheza faili hizo, ingawa uwezo wa kuendelea kusikiliza (resume) kwenye faili moja ndefu ya kitabu cha sauti ni dhaifu kuliko seva iliyoundwa mahususi kwa ajili ya vitabu vya sauti. Usanidi wa upande huo umeelezwa katika kuendesha Jellyfin kama media server kwenye VPS. Kwa upande wa vitabu vya kielektroniki, kabidhi /srv/media/ebooks kwa programu ya kusomea; kazi ya Chaptarr huishia pale faili inapopewa jina na kuhifadhiwa.

Hatari ya matengenezo: leseni, runtime, na tag inayobadilika haraka

Chaptarr ina leseni ya GPL-3.0, hakimiliki inamilikiwa na wachangiaji wa Chaptarr huku sehemu nyingine zikitoka kwa timu ya Servarr, hivyo msimbo unabaki wazi na yeyote anaweza kuufanyia fork tena ikiwa msimamizi huyu ataacha. Inajengwa juu ya .NET 10, toleo la sasa la long term support la runtime kufikia Agosti 2026, jambo linalomaanisha kuwa msingi wake unaungwa mkono kwa miaka badala ya miezi. Mambo yote mawili ni muhimu ikiwa unataathmini kama mradi huu utakuwepo mwaka ujao.

Namba za toleo hubadilika haraka. Releases huchapishwa kama pre-releases, na 0.9.925 ilitoka siku ile ile ya mwongozo huu. Bandika (pin) tag kamili. Kutumia latest kunamaanisha kuwa docker compose pull isiyosimamiwa inaweza kukuhamisha matoleo kadhaa ndani ya wiki moja, na fork changa kama hii inaweza kubadilisha API yake kati ya releases, jambo linalovunja script au dashboard yoyote uliyoiandika dhidi yake.

Hifadhi nakala (backup) kabla ya kila upgrade, kisha fanya upgrade kwa makusudi.

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

Mradi unaripoti kutokuwepo kwa matukio ya upotevu wa data kwa takribani miezi sita na zaidi ya watumiaji elfu kumi na moja, lakini bado unapendekeza kuweka backups na kutokuelekeza programu kwenye library ambayo huwezi kumudu kuipoteza. Zingatia pande zote mbili kwa uzito. Nakili archive ya usanidi nje ya seva, kwa sababu backup iliyo kwenye disk ileile na data inayolinda si backup. Tarball hiyo moja inatosha kwa sababu Chaptarr huhifadhi state yake katika SQLite file moja chini ya /config; kitu chochote kilicho kwenye database server tofauti kinahitaji database itolewe pia, na huo ndio muundo wa hatua ya backup wakati wa kujiendeshea Chatwoot kwenye VPS pamoja na data yake ya Postgres na files zilizopakiwa.

Njia za kushindwa kufanya kazi, pamoja na ujumbe utakaouona

Container inajianzisha upya kwa mzunguko. docker compose ps inaonyesha Restarting. Tekeleza ls -ln ./config. Sifuri mbili katika safu za mmiliki inamaanisha Docker ilitengeneza saraka hiyo kama root na mtumiaji wa container hawezi kuandika kwenye database yake. Tekeleza sudo chown -R 1000:1000 ./config.

Uingizaji (imports) haukamiliki na faili zinabaki kwenye downloads. Chaptarr inaweza kusoma download lakini haiwezi kuandika kwenye library. Linganisha ls -ln /srv/media/audiobooks na PUID pamoja na PGID yako. Saraka inayomilikiwa na UID tofauti, au inayomilikiwa na kundi lako bila ruhusa ya kuandika kwa kundi, inazuia uhamishaji. UMASK=002 inazuia kisa cha pili kwa faili mpya.

Matumizi ya diski yanaongezeka maradufu baada ya kila uingizaji. Hakuna hardlink iliyoundwa, kwa hivyo faili ilinakiliwa. Tekeleza jaribio la ln kutoka sehemu ya volumes. Hitilafu inayoishia na Invalid cross-device link inathibitisha hili, na mount ya mzazi mmoja (single-parent mount) ndiyo suluhisho.

Mteja wa kupakua (download client) hataki kuunganishwa. Uliingiza localhost kama host. Ndani ya container hiyo ni Chaptarr yenyewe. Tumia jina la container na uhakikishe docker network inspect arr inaorodhesha container zote mbili.

Compose inakataa kuanzisha huduma. Bind for 127.0.0.1:8789 failed: port is already allocated inamaanisha kuna kitu kingine kinachoshikilia port hiyo. Kitafute kwa kutumia sudo ss -lntp | grep 8789.

Kivinjari hakionyeshi chochote. Kwa port iliyofungwa kwenye 127.0.0.1, hakuna kitu cha laptop yako kuunganishwa nacho kupitia mtandao. Hiyo ndiyo hali iliyokusudiwa. Fungua SSH tunnel kwanza.

FAQ

Je, ninaweza kuhamisha maktaba yangu ya Readarr kwenda Chaptarr?

Huwezi kufanya hivyo kama import ya moja kwa moja. Chaptarr haioani na vyanzo vya metadata vya Readarr na inatumia mfumo wake wa watoa huduma, kwa hivyo vitambulisho vilivyohifadhiwa na Readarr havina maana na hakuna njia ya kubadilisha database. Faili zako zilizopo kwenye diski hazitaguswa. Ongeza njia zilezile kama root folders, endesha library import, na uiruhusu Chaptarr yenyewe ilinganishe faili hizo. Quality profiles, muundo wa majina, mipangilio ya indexer, na ulinganifu wowote usio sahihi ni kazi ya kufanya kwa mikono, kwa hivyo anza na folda moja ndogo kabla ya kuingiza kila kitu.

Kwa nini Chaptarr haiwezi kuandika kwenye folda yangu ya vitabu vya sauti (audiobook)?

Mtumiaji wa container hana umiliki wa faili hizo. Chaptarr hutumia PUID=99 na PGID=100 kama default wakati vigezo hivyo havijawekwa, ambavyo ni maadili ya unRAID na si sahihi kwenye Ubuntu VPS ya kawaida. Viweke kwenye id -u na id -g yako mwenyewe, tumia jozi hiyo hiyo kwenye download client, na uweke UMASK=002 ili faili mpya ziweze kuandikwa na kundi. Angalia umiliki kwa kutumia ls -ln kwenye saraka ya maktaba, kwa sababu inaonyesha namba badala ya majina ambayo huwezi kulinganisha.

Kwa nini matumizi ya diski yangu yaliongezeka mara mbili baada ya import?

Chaptarr ilinakili faili kwa sababu haikuweza kuunda hardlink. Kuweka /downloads na /audiobooks kama binds tofauti kunazifanya kuwa mount points tofauti ndani ya container, na kernel hukataa hardlink kuvuka mount points kwa sababu ya Invalid cross-device link. Mount saraka moja kuu kama /srv/media:/data na utumie /data/downloads na /data/audiobooks ndani ya programu. Njia zote mbili lazima pia ziwe kwenye filesystem moja ya host, jambo ambalo df -h linathibitisha.

Je, Chaptarr inacheza vitabu vyangu vya sauti?

Hapana. Inatafuta, inapakua, inabadilisha majina na kupanga faili hizo, na uchezaji ni programu tofauti. Audiobookshelf ndiyo inayotumiwa mara nyingi kwa sababu inakumbuka mahali ulipoishia kwenye vifaa mbalimbali, kwa kutumia image rasmi ya ghcr.io/advplyr/audiobookshelf:latest ikiwa na njia ileile ya audiobook ya host iliyowekwa. Jellyfin pia itacheza faili hizo ukiongeza folda hiyo kama maktaba, ingawa ina tabia dhaifu ya kurejelea uchezaji kwenye vitabu vya sauti vya faili moja ndefu.

Je, ni salama kuendesha Chaptarr kwenye maktaba ninayoijali?

Hii ni programu ya beta kutoka kwa fork changa, na mradi wenyewe unasema hivyo huku ukiripoti kutokuwepo kwa matukio ya kupoteza data kwa takriban miezi sita na watumiaji zaidi ya elfu kumi na moja. Sehemu za kutia moyo ni leseni ya GPL-3.0, inayofanya msimbo uweze kufanyiwa fork, na msingi wa .NET 10, ambao ni runtime ya long term support kuanzia Agosti 2026. Tumia image tag kamili kama 0.9.925 badala ya latest, hifadhi nakala ya /config kabla ya kila upgrade, na uweke nakala hiyo nje ya seva.