Cara Self-Host Chaptarr untuk Audiobook di VPS

Apa itu Chaptarr, dan mengapa pengguna Readarr memerlukannya

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

Readarr dihentikan pada 27 June 2025. Pemberitahuan resmi dari tim Servarr 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 tugas tersebut. Chaptarr mempertahankan struktur yang sudah Anda kenal dari Sonarr dan Radarr (indexer, download client, quality profile, root folder) serta menambahkan dukungan untuk audiobook: pengaturan berdasarkan narrator, beberapa edisi untuk satu judul, dukungan M4B dan MP3 dengan chapter, serta konversi MP3 ke M4B.

Panduan ini menggunakan image tag chaptarr/chaptarr:0.9.925, yang merupakan rilis terbaru pada 9 August 2026. Per 11 October 2026, rilis terbaru adalah 0.9.965, yang diterbitkan pada 27 September 2026. Langkah-langkah di bawah ini hanya diuji pada 0.9.925, sehingga file tetap menggunakan tag tersebut; baca release notes sebelum beralih ke versi yang lebih baru. Chaptarr menyebut dirinya sebagai software beta. Baca bagian maintenance di dekat akhir panduan ini sebelum 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. Bagian volume di bawah menjelaskan hal ini. Jika Docker belum tersedia di server, mulai dengan Docker sudah terpasang dan berjalan pada VPS, lalu kembali ke sini.

Saat ini Chaptarr hanya tersedia sebagai Docker image. Dukungan native masih dalam tahap pengembangan, build eksperimental untuk Windows direncanakan, dan belum tersedia package distribusi. Container menyimpan database-nya di /config menggunakan SQLite secara default. Container juga dapat menggunakan server PostgreSQL eksternal melalui environment variable 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 membiarkannya tidak diatur. Nilai tersebut adalah nilai unRAID. Pada VPS Ubuntu biasa, nilai itu tidak merujuk ke pengguna yang berguna. Akibatnya, 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 memerlukan pasangan nilai yang sama. Download client menulis ke /srv/media/downloads, Chaptarr memindahkan file ke /srv/media/audiobooks, lalu player membacanya dari sana. Jika download client menulis sebagai 1000:1000 dan Chaptarr berjalan sebagai 99:100, proses impor gagal. Kepemilikan file bukan penentu utamanya. Untuk membuat, mengganti nama, atau menghapus file, proses memerlukan izin tulis pada direktori tempat file tersebut berada. Direktori yang dibuat oleh user 1000 dengan mode 755 yang umum tidak memberikan 99:100 izin tulis. Akibatnya, Chaptarr tidak dapat memasukkan buku ke library atau menghapusnya dari direktori download. UMASK=002 membuat file baru dapat ditulis oleh group. Ini diperlukan ketika beberapa container menggunakan media group yang sama. Pemetaan lengkapnya dijelaskan dalam cara PUID dan PGID memetakan user container ke file pada host.

README memperingatkan satu masalah khusus, dan hal ini perlu diulang. 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. Akibatnya, container berhenti lalu melakukan restart terus-menerus. Periksa dengan ls -ln ./config, yang menampilkan pemilik dalam bentuk angka, bukan nama. Dua angka nol berarti root adalah pemiliknya. Perbaiki dengan sudo chown -R 1000:1000 ./config, lalu jalankan container kembali.

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 dilisensikan berdasarkan GPL-3.0 dan hak ciptanya dimiliki oleh para kontributor Chaptarr, dengan sebagian kode berasal dari tim Servarr. Karena itu, kodenya tetap terbuka dan siapa pun dapat melakukan fork lagi jika maintainer ini berhenti mengelolanya. Chaptarr dibangun di atas .NET 10, yang per Agustus 2026 merupakan rilis dukungan jangka panjang terbaru untuk runtime tersebut. Artinya, basisnya didukung selama bertahun-tahun, bukan hanya berbulan-bulan. Kedua hal ini penting saat Anda menilai apakah proyek ini masih akan tersedia tahun depan.

Nomor versinya berubah cepat. Versi 0.9.925 diterbitkan pada 9 August 2026, dan lima rilis lainnya menyusul dalam tujuh minggu berikutnya. Semua rilis hingga 0.9.958 diterbitkan sebagai pre-release. Versi 0.9.965, pada 27 September 2026, adalah versi pertama yang ditandai sebagai full release. Tetapkan tag yang spesifik. Menggunakan latest memungkinkan docker compose pull tanpa pengawasan memperbarui aplikasi beberapa versi dalam satu minggu. Fork yang masih sangat baru juga dapat mengubah API antarrilis. Perubahan ini dapat merusak skrip atau dashboard yang Anda buat berdasarkan API tersebut. Menetapkan versi adalah kebiasaan yang layak diterapkan pada setiap proyek baru yang Anda host sendiri. Karena alasan yang sama, panduan menjalankan openGym sebagai pelacak latihan yang di-host sendiri melakukan deployment dari tag git yang tetap.

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 ini melaporkan tidak ada kejadian kehilangan data selama sekitar enam bulan dan pada lebih dari sebelas ribu pengguna. Namun, proyek tersebut tetap menyarankan agar Anda menyimpan cadangan dan tidak mengarahkannya ke library yang datanya tidak boleh hilang. Tanggapi kedua hal tersebut dengan serius. Salin arsip konfigurasi ke luar server. Cadangan yang berada pada disk yang sama dengan data yang dilindunginya bukanlah cadangan. Satu tarball tersebut sudah cukup hanya karena Chaptarr menyimpan statusnya dalam satu file SQLite di bawah /config. Apa pun yang berada pada server database terpisah juga harus di-dump dari database tersebut. Itulah bentuk langkah pencadangan ketika meng-host Chatwoot sendiri 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 sendiri. Karena itu, pengenal yang disimpan Readarr tidak memiliki arti bagi Chaptarr dan tidak ada konversi database. File di disk Anda tidak akan diubah. 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 salah 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 tidak memiliki izin tulis ke direktori tersebut. Biasanya, penyebabnya adalah container berjalan dengan UID yang berbeda dari UID pemilik direktori. Chaptarr menggunakan nilai bawaan PUID=99 dan PGID=100 jika variabel tersebut tidak ditetapkan. Nilai itu adalah nilai milik unRAID dan salah jika digunakan pada 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 ownership 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 hardlink. Jika /downloads dan /audiobooks dipasang sebagai bind terpisah, keduanya menjadi mount point terpisah di dalam container. Kernel menolak hardlink yang melintasi mount point dan menghasilkan Invalid cross-device link. Pasang satu direktori induk seperti /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 mengatur file audiobook. Pemutaran dilakukan oleh program terpisah. Audiobookshelf adalah pasangan yang umum digunakan karena dapat mengingat posisi pemutaran di berbagai perangkat. Gunakan image resmi ghcr.io/advplyr/audiobookshelf:latest dan pasang path audiobook host yang sama. Jellyfin juga dapat memutar file tersebut jika folder ditambahkan sebagai pustaka, tetapi perilaku resume-nya lebih terbatas untuk audiobook panjang dalam satu file.

Apakah Chaptarr aman dijalankan pada pustaka yang penting bagi saya?

Chaptarr adalah software beta dari fork yang masih baru. Proyek tersebut menyatakan hal ini secara terbuka, sekaligus melaporkan tidak ada kejadian kehilangan data selama sekitar enam bulan dengan lebih dari sebelas ribu pengguna. Aspek yang cukup meyakinkan adalah lisensi GPL-3.0, yang memungkinkan kode tersebut di-fork, serta basis .NET 10, yaitu runtime long term support per August 2026. Gunakan tag image yang persis, seperti 0.9.925, bukan latest. Cadangkan /config sebelum setiap upgrade dan simpan arsip tersebut di luar server.