Cara Self-Host Chaptarr di VPS untuk Audiobook

Apa itu Chaptarr dan mengapa pengguna Readarr membutuhkannya

Chaptarr adalah fork dari Readarr yang mengelola audiobook dan ebook dari satu instance. Chaptarr memantau rilis baru, mengirimkannya ke download client, lalu mengganti nama hasilnya dan menata berkasnya ke dalam library. Chaptarr tidak memutar media, jadi Anda perlu memasangkannya dengan player seperti Audiobookshelf.

Readarr dihentikan pada 27 June 2025. Pemberitahuan dari tim Servarr sendiri menjelaskan alasannya: metadata proyek tersebut sudah tidak dapat digunakan, dan upaya komunitas untuk beralih ke Open Library terhenti. Repository-nya diarsipkan. Akibatnya, koleksi buku dan audiobook tidak lagi memiliki manager yang dipelihara, lalu Chaptarr mengambil alih fungsi tersebut. Chaptarr mempertahankan struktur yang sudah Anda kenal dari Sonarr dan Radarr (indexer, download client, quality profile, root folder) serta menambahkan dukungan untuk audiobook: penataan berdasarkan narrator, beberapa edisi untuk satu judul, dukungan M4B dan MP3 ber-chapter, serta konversi MP3 ke M4B.

Panduan ini menggunakan image tag chaptarr/chaptarr:0.9.925, yang merupakan rilis terbaru pada 9 August 2026. Chaptarr menyebut dirinya sebagai perangkat lunak beta. Baca bagian pemeliharaan di dekat akhir sebelum Anda mengarahkannya ke library yang tidak dapat Anda ganti.

Hal yang diperlukan sebelum memulai

VPS yang menjalankan Docker dan plugin Compose, serta ruang disk yang cukup untuk pustaka. Buku audio berukuran besar. Proses import yang tidak dapat menggunakan hardlink akan menyimpan dua salinan file untuk sementara waktu. Hal ini dijelaskan pada bagian volume di bawah. Jika Docker belum tersedia di server, mulai dengan Docker terpasang dan berjalan pada VPS, lalu kembali ke sini.

Saat ini, Chaptarr hanya tersedia sebagai image Docker. Build native untuk Windows tercatat masih dalam proses, dan belum tersedia paket distribusi. Secara default, container menyimpan database SQLite di /config. Container juga dapat menggunakan server PostgreSQL eksternal melalui variabel lingkungan Chaptarr__Postgres__* jika Anda sudah menjalankannya. SQLite merupakan pilihan yang tepat untuk satu pengguna pada satu server.

Service Compose untuk Chaptarr

Service ini ditambahkan ke stack yang sudah ada. Konfigurasinya menetapkan tag rilis, mempublikasikan UI web hanya pada loopback, dan bergabung ke network yang sudah digunakan download client Anda.

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

Baris external: true berarti “network ini sudah ada, lampirkan service ke network tersebut”. Gunakan baris ini jika Prowlarr dan torrent client Anda berasal dari project Compose yang berbeda. Tanpa baris ini, file Compose kedua akan membuat network terisolasi sendiri sehingga Chaptarr tidak dapat me-resolve qbittorrent berdasarkan nama. Dapatkan nama sebenarnya dengan docker network ls. Jika stack Anda sudah berada dalam satu file, tambahkan service chaptarr: ke file tersebut dan hapus seluruh blok networks:. Struktur yang lebih lengkap dibahas dalam stack arr lengkap dengan Docker Compose, sedangkan aturan penamaannya dibahas dalam cara Compose me-resolve network dan nama service.

Buat direktori konfigurasi secara manual, lalu jalankan service tersebut.

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

docker compose ps harus menampilkan container sebagai Up. Container yang berstatus Restarting gagal start dan sedang dicoba kembali. Penyebabnya hampir selalu adalah direktori konfigurasi. Log akan berhenti bergulir setelah aplikasi listening pada port 8789.

PUID, PGID, dan direktori yang dibuat Docker sebagai root

Chaptarr menggunakan PUID=99 dan PGID=100 secara default jika Anda tidak menetapkan nilainya. Nilai tersebut adalah nilai unRAID. Pada VPS Ubuntu biasa, nilai tersebut merujuk ke akun yang tidak berguna, sehingga file dibuat dengan pemilik yang tidak dapat ditulis oleh akun login Anda. Baca nilai Anda sendiri dengan id -u dan id -g, lalu masukkan nilai tersebut ke dalam file.

Setiap container yang mengakses file yang sama harus menggunakan pasangan nilai yang sama. Klien download menulis ke /srv/media/downloads, Chaptarr memindahkan file ke /srv/media/audiobooks, lalu pemutar membacanya dari sana. Jika klien download menulis sebagai 1000:1000 dan Chaptarr berjalan sebagai 99:100, proses import gagal karena Chaptarr tidak dapat menghapus atau memindahkan file yang bukan miliknya. UMASK=002 membuat file baru dapat ditulis oleh group, sesuai untuk beberapa container yang menggunakan group media yang sama. Pemetaan lengkapnya tersedia di cara PUID dan PGID memetakan pengguna container ke file pada host.

README memperingatkan satu masalah khusus yang perlu diingat. Jika ./config belum ada saat Anda menjalankan docker compose up, Docker akan membuatnya untuk Anda dengan pemilik root:root. Container kemudian berjalan sebagai UID 1000 dan tidak dapat menulis database-nya sendiri, sehingga terus keluar lalu melakukan restart. Periksa dengan ls -ln ./config, yang menampilkan pemilik dalam bentuk angka, bukan nama. Dua angka nol berarti direktori tersebut dimiliki oleh root. Perbaiki dengan sudo chown -R 1000:1000 ./config, lalu jalankan kembali container.

Mengapa volume audiobook dan ebook yang terpisah membuat hardlink tidak dapat digunakan

Tata letak di atas memasang /audiobooks, /ebooks, dan /downloads sebagai bind terpisah sesuai dengan perintah run milik proyek. Tata letak ini mudah dibaca, tetapi memiliki satu konsekuensi nyata: hardlink tidak dapat digunakan.

Hardlink adalah nama kedua untuk data yang sama pada disk. Hardlink tidak menggunakan ruang tambahan dan dibuat secara instan. Karena itu, keluarga arr lebih memilihnya daripada menyalin file. Hardlink hanya berfungsi di dalam satu filesystem. Di dalam container, ketiganya merupakan mount point terpisah. Karena itu, kernel menolak pembuatan link meskipun path pada host berada di disk yang sama. Uji sendiri.

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

Perintah tersebut gagal dengan error yang diakhiri Invalid cross-device link. Kernel menolak pembuatan link lintas mount point. Inilah alasan Chaptarr beralih menyalin file. Salinan tersebut benar, tetapi lebih lambat. Audiobook juga akan ada dua kali sampai Anda menghapus torrent. Anda tidak akan menghapusnya selama masih melakukan seeding. Hapus /srv/media/downloads/linktest setelah itu.

Agar hardlink tetap dapat digunakan, pasang satu direktori induk:

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

Kemudian, tetapkan root folder di dalam Chaptarr ke /data/audiobooks dan /data/ebooks. Berikan download client mount /srv/media:/data yang sama agar kedua container melihat path yang identik. Pastikan terlebih dahulu bahwa sisi host berada di satu filesystem: df -h /srv/media/downloads /srv/media/audiobooks harus menampilkan nilai yang sama pada kolom Filesystem untuk keduanya. Nilai yang berbeda berarti disk yang berbeda. Tidak ada tata letak mount yang dapat membuat hardlink lintas disk. Perbandingan antara pendekatan ini dan named storage dibahas dalam bind mount dibanding named volume untuk media.

Mengakses UI web tanpa mengeksposnya

Baris port menggunakan 127.0.0.1 karena suatu alasan. ufw deny 8789 tidak melindungi port Docker yang dipublikasikan, karena Docker menulis aturan NAT (network address translation) sendiri ke dalam chain yang dijangkau kernel sebelum chain milik ufw. Akibatnya, trafik diteruskan sebelum aturan Anda diperiksa. Perilaku ini sering mengecoh pengguna, dan penjelasannya tersedia di alasan port Docker yang dipublikasikan mengabaikan aturan ufw. Binding ke loopback menghindari masalah ini sepenuhnya.

Akses UI melalui tunnel SSH dari komputer Anda sendiri:

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

Biarkan proses tersebut tetap berjalan, lalu buka http://127.0.0.1:8789 di browser Anda. Konfigurasikan autentikasi saat pertama kali dijalankan. Setelah itu, barulah pertimbangkan penggunaan reverse proxy dengan TLS (transport layer security) di depannya. Jika Anda harus membuat tunnel ke tiga atau empat tool tersebut dengan password terpisah untuk masing-masing tool, solusi yang lebih rapi adalah menempatkan proxy di belakang server single sign-on yang di-host sendiri seperti Authentik, sehingga satu login mencakup semua aplikasi dan satu pencabutan akses menutup semuanya.

Hubungkan indexer dan klien unduhan

Chaptarr mendukung protokol indexer dan klien unduhan arr standar. Karena itu, Prowlarr memasukkan indexer ke Chaptarr dengan cara yang sama seperti pada Sonarr. Klien torrent dan usenet umum dapat dihubungkan tanpa penanganan khusus.

Satu pengaturan sering membingungkan hampir semua orang. Saat Chaptarr meminta host klien unduhan, jangan masukkan localhost atau 127.0.0.1. Di dalam container, alamat tersebut merujuk ke container itu sendiri. Akibatnya, Chaptarr mencoba terhubung ke port 8080 miliknya sendiri dan melaporkan bahwa koneksi gagal. Gunakan nama container, qbittorrent, dengan port 8080. Pastikan kedua container berada pada satu network dengan docker network inspect arr. Perintah ini menampilkan setiap container yang terhubung berdasarkan namanya.

Jika klien unduhan berjalan melalui container VPN dengan network_mode: "service:gluetun", klien tersebut tidak memiliki nama sendiri pada network karena berbagi network namespace dengan Gluetun. Akses klien tersebut sebagai gluetun melalui port yang diekspos Gluetun. Pengaturan ini, beserta routing yang menyertainya, dijelaskan dalam merutekan klien unduhan melalui Gluetun.

Peralihan dari Readarr: biaya migrasi yang sebenarnya

Chaptarr tidak kompatibel dengan sumber metadata Readarr. Chaptarr memproses judul, penulis, dan edisi melalui pipeline-nya sendiri pada beberapa penyedia, sehingga pengenal yang disimpan Readarr tidak bermakna di sini. Tidak ada impor database dan tidak ada jalur pemutakhiran langsung.

Untuk library yang sudah ada, ini berarti file tetap aman, tetapi pengaturan tidak ikut dipertahankan. Tidak ada bagian dari proses ini yang menyentuh file yang sudah ada di disk. Anda menambahkan root folder, menjalankan impor library, lalu Chaptarr mencocokkan file yang ditemukan dengan metadatanya sendiri. Hal-hal yang harus Anda bangun ulang secara manual: profil kualitas, format penamaan, pengaturan indexer dan client, serta setiap hasil pencocokan yang keliru dari Chaptarr. Library besar memerlukan pemeriksaan dan koreksi manual, jadi luangkan waktu satu malam, bukan sepuluh menit.

Lakukan dalam urutan berikut. Hentikan container Readarr, tetapi pertahankan volume konfigurasinya agar Anda masih dapat membaca pengaturan lama saat memasukkannya kembali. Arahkan Chaptarr ke satu folder kecil terlebih dahulu dan periksa hasil pencocokannya sebelum mengimpor semuanya. Hapus container lama hanya setelah Anda yakin.

Ada satu detail privasi yang perlu diketahui sebelum memindai seluruh library: pencarian metadata dikirim ke api2.chaptarr.com. README menyatakan bahwa permintaan tersebut dapat membawa ID penyedia, teks pencarian, jenis media, tag, dan nama file, serta tidak menyertakan path lengkap, identitas pengguna, dan kredensial. Nama file keluar dari server Anda. Hal ini normal untuk layanan metadata, tetapi Anda tetap harus memutuskannya secara sadar.

Serahkan audiobook kepada pemutar

Chaptarr mengatur file. Pemutaran menjadi tugas program lain, dan Audiobookshelf biasanya menjadi pasangan yang digunakan karena dapat melacak posisi pemutaran di berbagai perangkat serta menyediakan aplikasi untuk ponsel. Image resminya adalah ghcr.io/advplyr/audiobookshelf:latest, dan contoh Compose yang didokumentasikan memetakan port host 13378 ke port 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 path host yang sama dengan yang digunakan Chaptarr untuk menulis file, lalu tambahkan /audiobooks sebagai library melalui web UI. Import baru akan muncul setelah pemindaian berikutnya.

Jika Anda sudah menjalankan Jellyfin, Anda dapat menambahkan folder tersebut sebagai library di sana dan Jellyfin akan memutar file itu. Namun, perilaku resume untuk satu file audiobook yang panjang lebih terbatas dibandingkan server audiobook khusus. Penyiapan bagian tersebut dibahas dalam menjalankan Jellyfin sebagai server media di VPS. Untuk bagian ebook, serahkan /srv/media/ebooks kepada aplikasi pembaca. Tugas Chaptarr selesai setelah file diberi nama dan ditempatkan.

Risiko pemeliharaan: lisensi, runtime, dan tag yang bergerak cepat

Chaptarr menggunakan lisensi GPL-3.0 dan hak cipta kontributor Chaptarr, dengan sebagian kode berasal dari tim Servarr. Karena itu, kodenya tetap terbuka dan siapa pun dapat melakukan fork lagi jika pemelihara ini berhenti. Chaptarr dibangun di atas .NET 10, yaitu rilis dukungan jangka panjang terbaru untuk runtime tersebut per Agustus 2026. Artinya, basisnya didukung selama bertahun-tahun, bukan hanya berbulan-bulan. Kedua hal ini penting saat Anda menilai apakah proyek ini masih akan ada tahun depan.

Nomor versinya berubah cepat. Rilis diterbitkan sebagai pra-rilis, dan 0.9.925 dirilis pada hari yang sama dengan panduan ini. Tetapkan tag yang persis. Menggunakan latest dapat membuat docker compose pull yang berjalan tanpa pengawasan memperbarui Anda melewati beberapa versi dalam satu minggu. Fork yang masih sangat muda juga dapat mengubah API-nya antar-rilis. Hal ini dapat merusak skrip atau dasbor yang Anda buat untuk API tersebut.

Buat cadangan sebelum setiap upgrade, lalu lakukan upgrade secara sengaja.

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

Proyek tersebut melaporkan tidak adanya kejadian kehilangan data selama sekitar enam bulan dan pada lebih dari sebelas ribu pengguna. Namun, proyek itu tetap menyarankan agar Anda menyimpan backup dan tidak mengarahkannya ke library yang tidak boleh hilang. Tanggapi kedua hal tersebut dengan serius. Salin arsip konfigurasi ke luar server, karena backup yang berada pada disk yang sama dengan data yang dilindunginya bukanlah backup. Satu tarball tersebut hanya cukup karena Chaptarr menyimpan statusnya dalam satu file SQLite di bawah /config. Data apa pun yang berada pada server database terpisah juga harus diekspor, termasuk database, seperti pada langkah backup ketika melakukan self-hosting Chatwoot pada VPS bersama data Postgres dan file yang diunggah.

Mode kegagalan dan string yang akan Anda lihat

Container terus-menerus restart. docker compose ps menampilkan Restarting. Jalankan ls -ln ./config. Dua angka nol pada kolom owner berarti Docker membuat direktori tersebut sebagai root, sehingga user container tidak dapat menulis database-nya. Jalankan sudo chown -R 1000:1000 ./config.

Import tidak pernah selesai dan file tetap berada di direktori download. Chaptarr dapat membaca file yang diunduh, tetapi tidak dapat menulis ke library. Bandingkan ls -ln /srv/media/audiobooks dengan PUID dan PGID Anda. Direktori yang dimiliki UID berbeda, atau dimiliki group tanpa izin tulis untuk group, akan menghentikan proses pemindahan. UMASK=002 mencegah kasus kedua untuk file baru.

Penggunaan disk berlipat ganda setelah setiap import. Hardlink tidak dibuat, sehingga file disalin. Jalankan pengujian ln dari bagian volume. Error yang diakhiri dengan Invalid cross-device link mengonfirmasi hal tersebut, dan satu mount parent merupakan solusinya.

Download client tidak dapat terhubung. Anda memasukkan localhost sebagai host. Di dalam container, alamat tersebut merujuk ke Chaptarr itu sendiri. Gunakan nama container dan periksa bahwa docker network inspect arr mencantumkan kedua container.

Compose menolak untuk menjalankan service. Bind for 127.0.0.1:8789 failed: port is already allocated berarti ada proses lain yang menggunakan port tersebut. Cari prosesnya dengan sudo ss -lntp | grep 8789.

Browser sama sekali tidak menampilkan apa pun. Jika port di-bind ke 127.0.0.1, tidak ada layanan yang dapat dihubungi laptop Anda melalui Internet. Itulah perilaku yang diharapkan. Buka tunnel SSH terlebih dahulu.

FAQ

Dapatkah saya memigrasikan pustaka Readarr ke Chaptarr?

Bukan sebagai proses impor. Chaptarr tidak kompatibel dengan sumber metadata Readarr dan menggunakan pipeline penyedia miliknya sendiri. Karena itu, identifier yang disimpan Readarr tidak memiliki arti, dan tidak ada konversi database. File di disk tidak berubah. Tambahkan path yang sama sebagai root folder, jalankan impor pustaka, lalu biarkan Chaptarr mencocokkan file tersebut sendiri. Profil kualitas, format penamaan, pengaturan indexer, dan pencocokan yang keliru harus ditangani secara manual. Karena itu, mulai dengan satu folder kecil sebelum mengimpor semuanya.

Mengapa Chaptarr tidak dapat menulis ke folder audiobook saya?

User di dalam container bukan pemilik file tersebut. Chaptarr menggunakan PUID=99 dan PGID=100 jika variabel tersebut tidak ditetapkan. Nilai itu adalah nilai milik unRAID dan tidak tepat untuk Ubuntu VPS biasa. Tetapkan variabel tersebut ke id -u dan id -g milik Anda. Gunakan pasangan yang sama pada download client, lalu tetapkan UMASK=002 agar file baru tetap dapat ditulis oleh group. Periksa kepemilikan dengan ls -ln pada direktori pustaka. Perintah tersebut menampilkan angka, bukan nama, sehingga nilainya dapat dibandingkan.

Mengapa penggunaan disk saya menjadi dua kali lipat setelah impor?

Chaptarr menyalin file karena tidak dapat membuat hard link. Memasang /downloads dan /audiobooks sebagai bind terpisah membuat keduanya menjadi mount point terpisah di dalam container. Kernel menolak hard link antar-mount point dengan Invalid cross-device link. Mount satu direktori induk, misalnya /srv/media:/data, lalu gunakan /data/downloads dan /data/audiobooks di dalam aplikasi. Kedua path tersebut juga harus berada pada satu filesystem host. Hal ini dapat dikonfirmasi dengan df -h.

Apakah Chaptarr dapat memutar audiobook saya?

Tidak. Chaptarr mencari, mengunduh, mengganti nama, dan menata file tersebut. Pemutaran dilakukan oleh program terpisah. Audiobookshelf sering digunakan bersama Chaptarr karena dapat mengingat posisi pemutaran di berbagai perangkat. Gunakan image resmi ghcr.io/advplyr/audiobookshelf:latest dan mount path audiobook host yang sama. Jellyfin juga dapat memutar file tersebut jika Anda menambahkan foldernya sebagai pustaka, tetapi perilaku resume-nya lebih terbatas untuk audiobook panjang yang terdiri dari satu file.

Apakah Chaptarr aman dijalankan pada pustaka yang penting bagi saya?

Chaptarr adalah perangkat lunak beta dari fork yang masih baru. Proyek tersebut menyatakan hal ini secara terbuka, sekaligus melaporkan tidak ada insiden kehilangan data selama sekitar enam bulan dengan lebih dari sebelas ribu pengguna. Faktor yang mendukung kepercayaan adalah lisensi GPL-3.0, yang memungkinkan kode terus dibuat sebagai fork, serta basis .NET 10, yaitu runtime dukungan jangka panjang per Agustus 2026. Gunakan tag image yang persis, seperti 0.9.925, bukan latest. Cadangkan /config sebelum setiap upgrade, lalu simpan arsip tersebut di luar server.