Jak zainstalować Chaptarr na VPS w Docker Compose

Czym jest Chaptarr i dlaczego użytkownicy Readarr go potrzebują

Chaptarr to fork projektu Readarr, który zarządza audiobookami oraz e-bookami z poziomu jednej instancji. Narzędzie monitoruje nowe wydania, przekazuje je do klienta pobierania, a następnie zmienia nazwy plików i porządkuje je w bibliotece. Aplikacja nie służy do odtwarzania plików, dlatego należy ją połączyć z odtwarzaczem, takim jak Audiobookshelf.

Projekt Readarr został zakończony 27 czerwca 2025 roku. Zespół Servarr w oficjalnym komunikacie wskazał przyczynę: metadane projektu stały się bezużyteczne, a społecznościowe prace nad migracją do Open Library zostały wstrzymane. Repozytorium zostało zarchiwizowane. W rezultacie kolekcje książek i audiobooków pozostały bez utrzymywanego menedżera, a Chaptarr przejął to zadanie. Zachowuje on strukturę znaną z Sonarr i Radarr (indeksery, klienci pobierania, profile jakości, foldery główne) i dodaje obsługę audiobooków: organizację uwzględniającą lektora, wiele wydań tego samego tytułu, wsparcie dla formatów M4B i podzielonych na rozdziały plików MP3 oraz konwersję MP3 do M4B.

W tym przewodniku wykorzystano tag obrazu chaptarr/chaptarr:0.9.925, który był najnowszym wydaniem w dniu 9 sierpnia 2026 roku. Chaptarr określa się jako oprogramowanie w fazie beta. Przed wskazaniem ścieżki do biblioteki, której nie można odtworzyć w razie awarii, należy zapoznać się z sekcją dotyczącą utrzymania znajdującą się pod koniec dokumentacji.

Wymagania wstępne

Serwer VPS z zainstalowanym Dockerem oraz wtyczką Compose, a także wystarczająca ilość miejsca na dysku dla biblioteki. Audiobooki zajmują dużo miejsca, a import, który nie może wykorzystać twardych dowiązań (hardlinks), tymczasowo przechowuje dwie kopie pliku, co wyjaśniono w sekcji dotyczącej wolumenów poniżej. Jeśli Docker nie jest jeszcze zainstalowany na serwerze, należy zacząć od instalacji i uruchomienia Dockera na VPS i wrócić do tego miejsca.

Chaptarr jest obecnie udostępniany wyłącznie jako obraz Docker. Wersja natywna dla systemu Windows jest w przygotowaniu, a pakiety dystrybucyjne nie istnieją. Kontener przechowuje bazę danych w /config domyślnie jako SQLite, jednak może korzystać z zewnętrznego serwera PostgreSQL poprzez zmienne środowiskowe Chaptarr__Postgres__*, jeśli taki serwer jest już używany. SQLite jest właściwym wyborem dla jednego użytkownika na pojedynczym serwerze.

Usługa Compose dla Chaptarr

Ta usługa integruje się z istniejącym stosem. Przypina określoną wersję (tag), udostępnia interfejs WWW wyłącznie na adresie pętli zwrotnej (loopback) i dołącza do sieci używanej już przez klienta pobierania.

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

Linia external: true oznacza „ta sieć już istnieje, dołącz do niej”. Użyj tego rozwiązania, gdy Prowlarr i klient torrent pochodzą z innego projektu Compose, ponieważ w przeciwnym razie drugi plik Compose utworzy własną izolowaną sieć, a Chaptarr nie będzie w stanie rozpoznać qbittorrent po nazwie. Uzyskaj rzeczywistą nazwę za pomocą docker network ls. Jeśli cały stos znajduje się już w jednym pliku, dodaj usługę chaptarr: do tego pliku i usuń cały blok networks:. Szerszy układ opisano w pełnym stosie arr w Docker Compose, a zasady nazewnictwa w sposobie rozpoznawania sieci i nazw usług w Compose.

Utwórz samodzielnie katalog konfiguracyjny, a następnie uruchom usługę.

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

docker compose ps powinno wskazywać, że kontener ma status Up. Kontener oznaczony jako Restarting nie uruchomił się i jest restartowany; przyczyną jest niemal zawsze katalog konfiguracyjny. Dziennik przestaje przewijać się w momencie, gdy aplikacja zaczyna nasłuchiwać na porcie 8789.

PUID, PGID oraz katalog tworzony przez Docker jako root

Jeśli zmienne PUID=99 oraz PGID=100 pozostaną nieustawione, Chaptarr przyjmuje wartości domyślne. Są to wartości stosowane w unRAID, które na standardowym serwerze VPS z systemem Ubuntu nie przypisują plików do żadnego użytecznego użytkownika, przez co pliki trafiają do systemu z właścicielem, którego nie można edytować z poziomu konta użytkownika. Własne identyfikatory należy sprawdzić za pomocą poleceń id -u oraz id -g i umieścić je w pliku konfiguracyjnym.

Każdy kontener operujący na tych samych plikach musi korzystać z tej samej pary identyfikatorów. Klient pobierający zapisuje dane w /srv/media/downloads, Chaptarr przenosi plik do /srv/media/audiobooks, a odtwarzacz odczytuje go z tej lokalizacji. Jeśli klient pobierający działa jako 1000:1000, a Chaptarr jako 99:100, import zakończy się niepowodzeniem, ponieważ Chaptarr nie będzie mógł usunąć ani przenieść pliku, którego nie jest właścicielem. Parametr UMASK=002 nadaje nowym plikom uprawnienia do zapisu dla grupy, co jest pożądane, gdy kilka kontenerów współdzieli jedną grupę plików multimedialnych. Pełne mapowanie opisano w jak PUID i PGID mapują użytkownika kontenera na pliki hosta.

Plik README ostrzega przed jedną konkretną pułapką, którą warto przypomnieć. Jeśli katalog ./config nie istnieje w momencie uruchomienia docker compose up, Docker utworzy go automatycznie z właścicielem root:root. Kontener uruchomi się wówczas z UID 1000 i nie będzie mógł zapisać własnej bazy danych, co spowoduje jego ciągłe wyłączanie i restartowanie. Należy to zweryfikować za pomocą ls -ln ./config, które wyświetla numeryczne identyfikatory właścicieli zamiast nazw. Dwa zera oznaczają, że właścicielem jest root. Problem należy naprawić za pomocą sudo chown -R 1000:1000 ./config, a następnie ponownie uruchomić kontener.

Dlaczego rozdzielenie wolumenów audiobooków i ebooków uniemożliwia użycie hardlinków

Powyższy układ montuje /audiobooks, /ebooks oraz /downloads jako osobne dowiązania (binds), zgodnie z poleceniem uruchomieniowym projektu. Jest to czytelne, ale wiąże się z jednym istotnym kosztem: przestają działać hardlinki.

Hardlink to druga nazwa dla tych samych danych na dysku. Nie zajmuje dodatkowego miejsca i tworzy się natychmiastowo, dlatego rodzina aplikacji arr preferuje to rozwiązanie zamiast kopiowania. Hardlink działa tylko w obrębie jednego systemu plików. Wewnątrz kontenera są to trzy oddzielne punkty montowania, więc jądro systemu odmawia utworzenia dowiązania, nawet jeśli ścieżki na hoście znajdują się na tym samym dysku. Można to sprawdzić samodzielnie.

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

Polecenie kończy się błędem z komunikatem Invalid cross-device link. Jest to odmowa jądra systemu na utworzenie dowiązania między punktami montowania i jest to bezpośredni powód, dla którego Chaptarr przełącza się na kopiowanie pliku. Kopia jest poprawna, ale wolniejsza, a audiobook zajmuje miejsce dwukrotnie, dopóki nie usuniesz torrenta, czego nie zrobisz, dopóki trwa seeding. Po zakończeniu usuń /srv/media/downloads/linktest.

Aby zachować możliwość używania hardlinków, zamontuj jeden katalog nadrzędny:

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

Następnie ustaw foldery główne wewnątrz Chaptarr na /data/audiobooks oraz /data/ebooks i nadaj klientowi pobierania ten sam punkt montowania /srv/media:/data, aby oba kontenery widziały identyczną ścieżkę. Najpierw upewnij się, że po stronie hosta jest to jeden system plików: df -h /srv/media/downloads /srv/media/audiobooks musi wyświetlić tę samą wartość w kolumnie Filesystem dla obu lokalizacji. Różne wartości oznaczają różne dyski, a żaden układ montowania nie pozwoli na utworzenie hardlinków między nimi. Kompromis między tym rozwiązaniem a wolumenami nazwanymi opisano w bind mounts against named volumes for media.

Dostęp do interfejsu webowego bez jego wystawiania

Linia portu publikuje usługę na 127.0.0.1 nie bez powodu. ufw deny 8789 nie chroni opublikowanego portu Docker, ponieważ Docker zapisuje własne reguły NAT (network address translation) w łańcuchu, do którego jądro dociera przed regułami ufw. W rezultacie ruch jest przekazywany, zanim jakakolwiek reguła zostanie sprawdzona. To zachowanie jest częstym źródłem problemów i zostało wyjaśnione w dlaczego opublikowany port Docker ignoruje reguły ufw. Powiązanie z interfejsem loopback całkowicie omija ten problem.

Uzyskaj dostęp do interfejsu przez tunel SSH z własnej maszyny:

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

Pozostaw to połączenie aktywne i otwórz http://127.0.0.1:8789 w przeglądarce. Skonfiguruj uwierzytelnianie przy pierwszym uruchomieniu. Dopiero wtedy rozważ umieszczenie przed usługą reverse proxy z obsługą TLS (transport layer security). Gdy zaczniesz korzystać z tuneli dla trzech lub czterech takich narzędzi, z osobnym hasłem dla każdego z nich, lepszym rozwiązaniem będzie umieszczenie proxy za samodzielnie hostowanym serwerem single sign-on, takim jak Authentik. Dzięki temu jedno logowanie obsłuży wszystkie aplikacje, a jedno cofnięcie uprawnień zamknie do nich dostęp.

Podłączanie indeksatorów i klienta pobierania

Chaptarr obsługuje standardowe protokoły indeksatorów i klientów pobierania typu arr, więc Prowlarr przekazuje do niego indeksatory w taki sam sposób, jak w przypadku Sonarr, a typowe klienty torrent i usenet łączą się bez konieczności stosowania specjalnych procedur.

Jedno ustawienie sprawia trudności niemal każdemu użytkownikowi. Gdy Chaptarr prosi o podanie hosta klienta pobierania, nie należy wpisywać localhost ani 127.0.0.1. Wewnątrz kontenera ten adres wskazuje na sam kontener, więc Chaptarr próbuje połączyć się z własnym portem 8080 i zgłasza błąd połączenia. Należy użyć nazwy kontenera, qbittorrent, wraz z portem 8080. Należy potwierdzić, że oba kontenery znajdują się w tej samej sieci za pomocą polecenia docker network inspect arr, które wyświetla listę wszystkich podłączonych kontenerów według nazw.

Jeśli klient pobierania działa poprzez kontener VPN z network_mode: "service:gluetun", nie posiada on własnej nazwy w sieci, ponieważ współdzieli przestrzeń nazw sieciowych Gluetun. Należy odwoływać się do niego jako gluetun na porcie udostępnionym przez Gluetun. Taka konfiguracja oraz powiązane z nią routowanie zostały opisane w routing a download client through Gluetun.

Przerwa z Readarr: rzeczywisty koszt migracji

Chaptarr nie jest kompatybilny ze źródłami metadanych Readarr. Rozwiązuje on tytuły, autorów i wydania za pomocą własnego potoku przetwarzania obejmującego kilku dostawców, więc identyfikatory przechowywane przez Readarr są tutaj bezużyteczne. Nie istnieje możliwość importu bazy danych ani bezpośredniej ścieżki aktualizacji.

W przypadku istniejącej biblioteki oznacza to, że pliki są bezpieczne, ale ustawienia nie. Proces ten nie ingeruje w dane znajdujące się na dysku. Należy dodać folder główny, uruchomić import biblioteki, a Chaptarr dopasuje znalezione pliki do własnych metadanych. Ręcznej konfiguracji wymagają: profile jakości, format nazewnictwa, ustawienia indeksatorów i klientów oraz wszystkie błędne dopasowania wykonane przez Chaptarr. Duża biblioteka będzie wymagała ręcznej weryfikacji, więc należy zaplanować na to wieczór, a nie dziesięć minut.

Należy zachować następującą kolejność. Zatrzymaj kontener Readarr, ale zachowaj jego wolumen z konfiguracją, aby móc odczytać stare ustawienia podczas przepisywania ich do nowego systemu. Skieruj Chaptarr najpierw na jeden mały folder i sprawdź dopasowania przed zaimportowaniem całości. Usuń stary kontener dopiero po upewnieniu się, że wszystko działa poprawnie.

Przed przeskanowaniem całej biblioteki warto znać jeden szczegół dotyczący prywatności: wyszukiwanie metadanych odbywa się w api2.chaptarr.com. Dokumentacja README wskazuje, że zapytania te mogą zawierać identyfikatory dostawców, tekst wyszukiwania, typ mediów, tagi oraz nazwy plików, natomiast wykluczają pełne ścieżki, tożsamość użytkownika i dane uwierzytelniające. Nazwy plików opuszczają serwer. Jest to standardowe zachowanie dla usług metadanych, jednak decyzję o korzystaniu z nich należy podjąć świadomie.

Przekazywanie audiobooków do odtwarzacza

Chaptarr służy do porządkowania plików. Ich odtwarzanie jest zadaniem innego programu, a Audiobookshelf jest najczęstszym wyborem, ponieważ śledzi postęp słuchania na różnych urządzeniach i posiada aplikacje mobilne. Oficjalny obraz to ghcr.io/advplyr/audiobookshelf:latest, a udokumentowany przykład Compose publikuje port hosta 13378 na port kontenera 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

Należy zamontować tę samą ścieżkę hosta, do której zapisuje Chaptarr, a następnie dodać /audiobooks jako bibliotekę w interfejsie WWW. Nowy import pojawi się po kolejnym skanowaniu.

Jeśli użytkownik korzysta już z Jellyfin, można dodać folder jako bibliotekę w tej usłudze, która obsłuży odtwarzanie plików, choć wznawianie odtwarzania w przypadku pojedynczego długiego pliku audiobooka działa słabiej niż w dedykowanym serwerze audiobooków. Konfiguracja tego rozwiązania została opisana w uruchamianie Jellyfin jako serwera mediów na VPS. W przypadku e-booków należy przekazać /srv/media/ebooks do aplikacji czytnika; zadanie Chaptarr kończy się w momencie nadania plikowi nazwy i umieszczenia go w odpowiednim folderze.

Ryzyko utrzymania: licencja, środowisko uruchomieniowe i szybko zmieniające się tagi

Projekt Chaptarr jest objęty licencją GPL-3.0, a prawa autorskie należą do współtwórców Chaptarr, przy czym fragmenty kodu pochodzą od zespołu Servarr. Dzięki temu kod pozostaje otwarty i w przypadku zaprzestania prac przez obecnego opiekuna, każdy może ponownie utworzyć fork projektu. Oprogramowanie bazuje na .NET 10, czyli bieżącym wydaniu środowiska uruchomieniowego o długoterminowym wsparciu (LTS) na sierpień 2026 roku, co oznacza, że fundament projektu będzie wspierany przez lata, a nie miesiące. Oba te fakty mają znaczenie przy ocenie, czy projekt będzie istniał w przyszłym roku.

Numery wersji zmieniają się szybko. Wydania publikowane są jako wersje przedpremierowe, a wersja 0.9.925 pojawiła się tego samego dnia, w którym powstał ten poradnik. Należy przypiąć konkretny tag. Używanie latest oznacza, że niekontrolowany proces docker compose pull może w ciągu tygodnia przenieść użytkownika o kilka wersji do przodu. Tak młody fork może zmieniać swoje API pomiędzy wydaniami, co powoduje awarię każdego skryptu lub panelu sterowania przygotowanego pod daną wersję.

Przed każdą aktualizacją należy wykonać kopię zapasową, a samą aktualizację przeprowadzać w sposób świadomy.

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

Projekt nie odnotował przypadków utraty danych przez około sześć miesięcy i przy ponad jedenastu tysiącach użytkowników nadal zaleca wykonywanie kopii zapasowych oraz niewskazywanie biblioteki, której utraty nie można zaakceptować. Należy potraktować poważnie obie części tego zalecenia. Archiwum konfiguracji trzeba skopiować poza serwer, ponieważ kopia zapasowa przechowywana na tym samym dysku co chronione dane nie jest kopią zapasową. Pojedynczy archiwum tar wystarcza wyłącznie dlatego, że Chaptarr przechowuje stan w jednym pliku SQLite w lokalizacji /config. Dane znajdujące się na oddzielnym serwerze baz danych trzeba również zrzucić do kopii. Tak wygląda etap tworzenia kopii w przypadku samodzielnego hostowania Chatwoot na VPS wraz z danymi Postgres i przesłanymi plikami.

Tryby awaryjne i towarzyszące im komunikaty

Kontener restartuje się w pętli. docker compose ps wyświetla Restarting. Uruchom ls -ln ./config. Dwa zera w kolumnach właściciela oznaczają, że Docker utworzył katalog jako root, a użytkownik kontenera nie ma uprawnień do zapisu w bazie danych. Uruchom sudo chown -R 1000:1000 ./config.

Importy nigdy się nie kończą, a pliki pozostają w folderze pobierania. Chaptarr może odczytać pobrany plik, ale nie może zapisać go w bibliotece. Porównaj ls -ln /srv/media/audiobooks ze swoimi PUID oraz PGID. Katalog należący do innego UID lub należący do grupy bez uprawnień do zapisu uniemożliwia przeniesienie pliku. UMASK=002 zapobiega drugiemu przypadkowi dla nowych plików.

Zużycie miejsca na dysku podwaja się po każdym imporcie. Nie utworzono twardego dowiązania (hardlink), więc plik został skopiowany. Uruchom test ln z sekcji wolumenów. Błąd kończący się Invalid cross-device link potwierdza ten stan, a rozwiązaniem jest montowanie z jednym punktem nadrzędnym (single-parent mount).

Klient pobierania nie może nawiązać połączenia. Wprowadzono localhost jako hosta. Wewnątrz kontenera jest to sam Chaptarr. Użyj nazwy kontenera i sprawdź, czy docker network inspect arr wyświetla oba kontenery.

Compose odmawia uruchomienia usługi. Bind for 127.0.0.1:8789 failed: port is already allocated oznacza, że port jest zajęty przez inny proces. Znajdź go za pomocą sudo ss -lntp | grep 8789.

Przeglądarka nie wyświetla żadnej zawartości. Przy porcie powiązanym z 127.0.0.1, laptop nie ma możliwości połączenia się przez Internet. Jest to zamierzone zachowanie. Najpierw otwórz tunel SSH.

FAQ

Czy mogę przenieść bibliotekę Readarr do Chaptarr?

Nie poprzez import. Chaptarr nie jest kompatybilny ze źródłami metadanych Readarr i korzysta z własnego potoku dostawców, dlatego identyfikatory zapisane przez Readarr nie mają znaczenia i nie istnieje narzędzie do konwersji bazy danych. Pliki na dysku pozostają nienaruszone. Należy dodać te same ścieżki jako foldery główne, uruchomić import biblioteki i pozwolić Chaptarr na samodzielne dopasowanie plików. Profile jakości, format nazewnictwa, ustawienia indeksatorów oraz poprawa błędnych dopasowań wymagają pracy ręcznej, dlatego warto zacząć od jednego małego folderu przed zaimportowaniem całości.

Dlaczego Chaptarr nie może zapisywać danych w folderze z audiobookami?

Użytkownik kontenera nie jest właścicielem plików. Chaptarr przyjmuje wartości domyślne PUID=99 oraz PGID=100, gdy zmienne te nie są ustawione; są to wartości specyficzne dla unRAID, niepoprawne na standardowym serwerze VPS z Ubuntu. Należy ustawić je na własne id -u oraz id -g, użyć tej samej pary w kliencie pobierania oraz ustawić UMASK=002, aby nowe pliki zachowywały uprawnienia do zapisu dla grupy. Należy sprawdzić właściciela za pomocą ls -ln w katalogu biblioteki, ponieważ polecenie to wyświetla numery zamiast nazw, co umożliwia bezpośrednie porównanie.

Dlaczego po imporcie zużycie miejsca na dysku wzrosło dwukrotnie?

Chaptarr skopiował plik, ponieważ nie mógł utworzyć twardego dowiązania (hardlink). Montowanie /downloads oraz /audiobooks jako osobnych dowiązań (binds) tworzy odrębne punkty montowania wewnątrz kontenera, a jądro systemu odmawia utworzenia twardego dowiązania między różnymi punktami montowania z błędem Invalid cross-device link. Należy zamontować jeden katalog nadrzędny, taki jak /srv/media:/data, i użyć /data/downloads oraz /data/audiobooks wewnątrz aplikacji. Obie ścieżki muszą również znajdować się na tym samym systemie plików hosta, co można zweryfikować za pomocą df -h.

Czy Chaptarr odtwarza moje audiobooki?

Nie. Aplikacja wyszukuje, pobiera, zmienia nazwy i porządkuje pliki, natomiast odtwarzanie jest zadaniem oddzielnego programu. Audiobookshelf jest najczęściej wybieranym rozwiązaniem, ponieważ zapamiętuje pozycję odtwarzania na różnych urządzeniach; należy użyć oficjalnego obrazu ghcr.io/advplyr/audiobookshelf:latest z zamontowaną tą samą ścieżką do audiobooków na hoście. Jellyfin również odtworzy pliki po dodaniu folderu jako biblioteki, jednak oferuje słabszą obsługę wznawiania odtwarzania w przypadku długich audiobooków zapisanych w jednym pliku.

Czy uruchamianie Chaptarr na ważnej dla mnie bibliotece jest bezpieczne?

Jest to oprogramowanie w fazie beta, pochodzące z młodego forka, co sam projekt podkreśla, jednocześnie nie odnotowując przypadków utraty danych w ciągu około sześciu miesięcy przy ponad jedenastu tysiącach użytkowników. Czynnikami budzącymi zaufanie są licencja GPL-3.0, która umożliwia dalsze rozwijanie kodu, oraz baza .NET 10, czyli środowisko uruchomieniowe z długoterminowym wsparciem (LTS) od sierpnia 2026. Należy przypiąć konkretną wersję obrazu, taką jak 0.9.925, zamiast używać latest, wykonywać kopię zapasową /config przed każdą aktualizacją i przechowywać to archiwum poza serwerem.