Jak zainstalować Chaptarr na VPS w Docker Compose

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

Chaptarr to fork Readarr, który zarządza audiobookami i ebookami z jednej instancji. Monitoruje nowe wydania, przekazuje je do klienta pobierania, a następnie zmienia nazwy wynikowych plików i umieszcza je w bibliotece. Nie odtwarza żadnych treści, dlatego należy połączyć go z odtwarzaczem, takim jak Audiobookshelf.

Readarr został wycofany 27 June 2025. Własny komunikat zespołu Servarr podaje przyczynę: metadane projektu stały się bezużyteczne, a działania społeczności mające na celu przejście na Open Library utknęły. Repozytorium zostało zarchiwizowane. Kolekcje książek i audiobooków pozostały bez utrzymywanego menedżera, dlatego Chaptarr przejął to zadanie. Zachowuje układ znany już z Sonarr i Radarr (indeksery, klienci pobierania, profile jakości, foldery główne) i dodaje obsługę audiobooków: organizowanie uwzględniające narratora, wiele wydań jednego tytułu, obsługę M4B i MP3 z rozdziałami oraz konwersję MP3 do M4B.

W tym przewodniku użyto znacznika obrazu chaptarr/chaptarr:0.9.925, który 9 August 2026 był najnowszym wydaniem. Na dzień 11 October 2026 najnowsze wydanie to 0.9.965, opublikowane 27 September 2026. Poniższe kroki przetestowano wyłącznie na wersji 0.9.925, dlatego pliki zachowują ten znacznik; przed przejściem na nowszą wersję należy przeczytać informacje o wydaniu. Chaptarr określa się jako oprogramowanie beta. Przed wskazaniem biblioteki, której nie można odtworzyć, należy zapoznać się z sekcją dotyczącą konserwacji znajdującą się pod koniec przewodnika.

Co należy przygotować przed rozpoczęciem

Potrzebny jest VPS z uruchomionym Dockerem i wtyczką Compose oraz wystarczającą ilością miejsca na bibliotekę. Audiobooki zajmują dużo miejsca, a import, który nie może używać hardlinków, przez pewien czas przechowuje dwie kopie pliku. Wyjaśniono to w poniższej sekcji dotyczącej wolumenu. Jeśli Docker nie jest jeszcze zainstalowany na serwerze, należy rozpocząć od Instalacja i uruchomienie Dockera na VPS i następnie wrócić do tego miejsca.

Obecnie Chaptarr jest dostępny wyłącznie jako obraz Docker. Obsługa natywna jest oznaczona jako będąca w toku. Planowana jest eksperymentalna kompilacja dla Windows, ale nie ma pakietu dla żadnej dystrybucji. Kontener domyślnie przechowuje bazę danych w /config jako SQLite. Może też korzystać z zewnętrznego serwera PostgreSQL za pośrednictwem zmiennych środowiskowych Chaptarr__Postgres__*, jeśli taki serwer jest już uruchomiony. SQLite jest właściwym wyborem dla jednego użytkownika na jednym 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

Chaptarr używa wartości PUID=99 i PGID=100, jeśli nie zostaną ustawione. Są to wartości używane przez unRAID. Na zwykłym VPS z Ubuntu należą do nieużywanego konta, dlatego pliki otrzymują właściciela, który nie może ich zapisywać. Odczytaj własne wartości za pomocą id -u i id -g, a następnie wpisz je do pliku.

Każdy kontener korzystający z tych samych plików musi używać tej samej pary wartości. Klient pobierania zapisuje dane w /srv/media/downloads, Chaptarr przenosi plik do /srv/media/audiobooks, a odtwarzacz odczytuje go z tego katalogu. Jeśli klient pobierania zapisuje jako 1000:1000, a Chaptarr działa jako 99:100, import kończy się niepowodzeniem. O tym, czy operacja jest możliwa, nie decyduje właściciel pliku. Tworzenie, zmiana nazwy i usuwanie pliku wymaga uprawnień zapisu do katalogu, który go zawiera. Katalogi utworzone przez użytkownika 1000 ze standardowym trybem 755 nie zapewniają 99:100 uprawnień zapisu. W rezultacie Chaptarr nie może dodać książki do biblioteki ani usunąć jej z katalogu pobierania. UMASK=002 nadaje nowym plikom uprawnienia zapisu dla grupy. Jest to wymagane, gdy kilka kontenerów korzysta ze wspólnej grupy multimediów. Pełne mapowanie opisano w sposobie mapowania PUID i PGID kontenera na pliki hosta.

README ostrzega przed jednym konkretnym problemem. Warto go powtórzyć. Jeśli ./config nie istnieje podczas uruchamiania docker compose up, Docker tworzy go automatycznie z właścicielem root:root. Kontener działa wtedy jako UID 1000 i nie może zapisywać własnej bazy danych, dlatego kończy działanie i uruchamia się ponownie w nieskończonej pętli. Sprawdź to za pomocą ls -ln ./config, które wyświetla numeryczne identyfikatory właścicieli zamiast nazw. Dwie wartości zero oznaczają, że właścicielem jest root. Napraw problem za pomocą sudo chown -R 1000:1000 ./config, a następnie ponownie uruchom 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

Chaptarr jest objęty licencją GPL-3.0. Prawa autorskie należą do współtwórców Chaptarr, a część kodu pochodzi od zespołu Servarr. Kod pozostaje więc otwarty i można utworzyć jego fork, jeśli obecny opiekun przestanie go rozwijać. Projekt korzysta z .NET 10, czyli aktualnego wydania środowiska uruchomieniowego z długoterminowym wsparciem na dzień sierpnia 2026. Oznacza to, że baza projektu będzie wspierana przez lata, a nie przez miesiące. Oba fakty mają znaczenie przy ocenie, czy projekt będzie nadal istnieć w przyszłym roku.

Numery wersji zmieniają się szybko. Wersję 0.9.925 opublikowano 9 sierpnia 2026, a w ciągu kolejnych siedmiu tygodni wydano jeszcze pięć wersji. Wszystkie wersje do 0.9.958 włącznie opublikowano jako wersje wstępne. Wersja 0.9.965 z 27 września 2026 jest pierwszą oznaczoną jako pełne wydanie. Należy przypiąć konkretny tag. Użycie latest oznacza, że nienadzorowane docker compose pull może w ciągu tygodnia przenieść instalację o kilka wersji. Tak młody fork może też zmieniać API między wydaniami, co powoduje awarie skryptów i pulpitów nawigacyjnych napisanych dla wcześniejszej wersji. Przypinanie wersji warto stosować w każdym młodym projekcie hostowanym samodzielnie. Z tego samego powodu instrukcja uruchamiania openGym jako samodzielnie hostowanego rejestru treningów wdraża projekt ze stałego tagu git.

Przed każdą aktualizacją wykonaj kopię zapasową. Następnie przeprowadź aktualizację świadomie.

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 w okresie około sześciu miesięcy i przy ponad jedenastu tysiącach użytkowników. Mimo to nadal zaleca przechowywanie kopii zapasowych i niekierowanie aplikacji do biblioteki, której utraty nie można zaakceptować. Obie części tego zalecenia należy traktować poważnie. Skopiuj archiwum konfiguracji poza serwer. Kopia zapasowa przechowywana na tym samym dysku co chronione dane nie jest kopią zapasową. Pojedynczy plik tar wystarcza wyłącznie dlatego, że Chaptarr przechowuje stan w jednym pliku SQLite pod ścieżką /config. Dane znajdujące się na osobnym serwerze baz danych wymagają również wykonania zrzutu bazy. Tak wygląda etap tworzenia kopii zapasowej podczas samodzielnego hostowania Chatwoot na VPS razem 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 można przenieść bibliotekę Readarr do Chaptarr?

Nie jako import. Chaptarr nie jest zgodny ze źródłami metadanych Readarr i używa własnego potoku dostawców, dlatego zapisane przez Readarr identyfikatory nie mają znaczenia i nie istnieje konwersja bazy danych. Pliki na dysku pozostają nienaruszone. Należy dodać te same ścieżki jako foldery główne, uruchomić import biblioteki i pozwolić Chaptarr samodzielnie dopasować pliki. Profile jakości, format nazewnictwa, ustawienia indeksatorów i ewentualne błędne dopasowania wymagają konfiguracji ręcznej, dlatego przed zaimportowaniem całości należy rozpocząć od jednego małego folderu.

Dlaczego Chaptarr nie może zapisywać w moim folderze audiobooków?

Użytkownik kontenera nie ma uprawnień do zapisu w tym katalogu, zwykle dlatego, że kontener działa z innym UID niż użytkownik będący właścicielem katalogu. Gdy zmienne te nie są ustawione, Chaptarr używa wartości PUID=99 i PGID=100, które są wartościami unRAID i nie są poprawne na zwykłym VPS z Ubuntu. Należy ustawić własne wartości id -u i id -g, użyć tej samej pary w kliencie pobierania oraz ustawić UMASK=002, aby nowe pliki zachowywały możliwość zapisu dla grupy. Własność należy sprawdzić za pomocą ls -ln w katalogu biblioteki, ponieważ polecenie wyświetla numery zamiast nazw, których nie można bezpośrednio porównać.

Dlaczego po imporcie zajętość dysku się podwoiła?

Chaptarr skopiował plik, ponieważ nie mógł utworzyć do niego dowiązania twardego. Zamontowanie /downloads i /audiobooks jako oddzielnych bind mountów powoduje, że wewnątrz kontenera są one oddzielnymi punktami montowania, a kernel odmawia utworzenia dowiązania twardego między punktami montowania, zwracając Invalid cross-device link. Należy zamontować jeden katalog nadrzędny, taki jak /srv/media:/data, a w aplikacji użyć ścieżek /data/downloads i /data/audiobooks. Obie ścieżki muszą również znajdować się w jednym systemie plików hosta, co potwierdza df -h.

Czy Chaptarr odtwarza audiobooki?

Nie. Chaptarr wyszukuje, pobiera, zmienia nazwy i porządkuje pliki, a odtwarzanie jest obsługiwane przez osobny program. Audiobookshelf jest często używany razem z Chaptarr, ponieważ zapamiętuje pozycję odtwarzania na różnych urządzeniach. Wykorzystuje oficjalny obraz ghcr.io/advplyr/audiobookshelf:latest z zamontowaną tą samą ścieżką audiobooków hosta. Jellyfin również odtworzy te pliki po dodaniu folderu jako biblioteki, ale obsługa wznawiania odtwarzania długich audiobooków zapisanych w pojedynczych plikach jest słabsza.

Czy uruchamianie Chaptarr na ważnej bibliotece jest bezpieczne?

Jest to oprogramowanie beta pochodzące z młodego forka. Sam projekt informuje o tym, jednocześnie podając, że przez około sześć miesięcy i przy ponad jedenastu tysiącach użytkowników nie odnotowano utraty danych. Pozytywnymi czynnikami są licencja GPL-3.0, która pozwala tworzyć forki kodu, oraz baza .NET 10, będąca środowiskiem uruchomieniowym z długoterminowym wsparciem w sierpniu 2026. Należy przypiąć dokładny tag obrazu, taki jak 0.9.925, zamiast latest, wykonać kopię zapasową /config przed każdą aktualizacją oraz przechowywać to archiwum poza serwerem.