Як розгорнути Chaptarr для аудіокниг на VPS

Що таке Chaptarr і навіщо він потрібен користувачам Readarr

Chaptarr — це форк Readarr, який керує аудіокнигами та електронними книгами з одного екземпляра. Він відстежує нові релізи, передає їх клієнту завантаження, а потім перейменовує отримані файли та розкладає їх у бібліотеці. Він нічого не відтворює, тому його потрібно поєднати з програвачем, наприклад Audiobookshelf.

Readarr припинив роботу 27 June 2025. У власному повідомленні команда Servarr назвала причину: метадані проєкту стали непридатними для використання, а спроба спільноти перейти на Open Library зупинилася. Репозиторій заархівовано. У результаті колекції книг і аудіокниг залишилися без підтримуваного менеджера, і Chaptarr перебрав це завдання на себе. Він зберігає знайому вам структуру Sonarr і Radarr (індексатори, клієнти завантаження, профілі якості, кореневі каталоги) та додає підтримку аудіокниг: організацію з урахуванням диктора, кілька видань одного твору, підтримку M4B і MP3 з розділами, а також конвертацію MP3 у M4B.

У цьому посібнику використано тег образу chaptarr/chaptarr:0.9.925, який був найновішим релізом 9 August 2026. Станом на 11 October 2026 найновішим є реліз 0.9.965, опублікований 27 September 2026. Наведені нижче кроки перевірено лише на версії 0.9.925, тому у файлах збережено цей тег; перш ніж переходити на новішу версію, прочитайте примітки до релізу. Chaptarr називає себе beta software. Перш ніж підключати його до бібліотеки, яку неможливо відновити, прочитайте розділ про обслуговування наприкінці.

Що потрібно підготувати перед початком

VPS із Docker і Compose plugin, а також достатній обсяг диска для бібліотеки. Аудіокниги займають багато місця. Під час імпорту, який не може використовувати hard links, деякий час зберігаються дві копії файлу. Це пояснюється в розділі про томи нижче. Якщо Docker ще не встановлено на сервері, почніть зі статті Docker встановлено та запущено на VPS, а потім поверніться сюди.

Наразі Chaptarr доступний лише як Docker image. Нативна підтримка ще в розробці. Також заплановано експериментальну збірку для Windows. Пакета для дистрибутива немає. Контейнер зберігає базу даних у /config, використовуючи SQLite за замовчуванням. Якщо у вас уже запущено PostgreSQL server, його можна використовувати через змінні середовища Chaptarr__Postgres__*. Для одного користувача на одному сервері найкраще підходить SQLite.

Сервіс Compose для Chaptarr

Цей сервіс додається до наявного стека. Він фіксує випущений тег, публікує вебінтерфейс лише на loopback і підключається до мережі, яку вже використовує ваш клієнт завантажень.

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

Рядок external: true означає: «ця мережа вже існує, підключіть до неї». Використовуйте його, якщо Prowlarr і ваш torrent-клієнт працюють в іншому проєкті Compose. Інакше другий файл Compose створить власну ізольовану мережу, і Chaptarr не зможе знайти qbittorrent за іменем. Фактичне ім’я можна отримати з docker network ls. Якщо ваш стек уже описаний в одному файлі, додайте сервіс chaptarr: до цього файлу та видаліть увесь блок networks:. Загальну структуру описано в матеріалі повний стек arr у Docker Compose, а правила іменування — у матеріалі як Compose визначає мережі та імена сервісів.

Створіть каталог конфігурації вручну, а потім запустіть сервіс.

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

docker compose ps має показати контейнер у стані Up. Контейнер у стані Restarting не зміг запуститися, і система повторює спроби запуску; перегляньте його журнали, щоб визначити причину. Прокручування журналу припиниться, коли застосунок почне слухати порт 8789.

PUID, PGID і каталог, який Docker створює від імені root

Якщо не задати PUID=99 і PGID=100, Chaptarr використовує значення за замовчуванням PUID=99 і PGID=100. Це значення unRAID. На звичайному Ubuntu VPS вони належать обліковому запису, який не має потрібних прав, тому файли створюються з власником, від імені якого ваш обліковий запис не може виконувати запис. Перевірте власні значення командами id -u і id -g та вкажіть їх у файлі.

Кожен контейнер, який працює з тими самими файлами, має використовувати цю саму пару значень. Клієнт завантажень записує файл у /srv/media/downloads, Chaptarr переміщує його до /srv/media/audiobooks, а програвач читає його звідти. Якщо клієнт завантажень записує файли від імені 1000:1000, а Chaptarr працює від імені 99:100, імпорт не виконується. Вирішальним є не власник файла: для створення, перейменування або видалення файла потрібні права на запис до каталогу, у якому він зберігається. Каталоги, створені користувачем 1000 зі стандартним режимом 755, не дають 99:100 права на запис. Тому Chaptarr не може ані додати книгу до медіатеки, ані видалити її із каталогу завантажень. UMASK=002 робить нові файли доступними для запису групі. Саме це потрібно, коли кілька контейнерів використовують одну медіагрупу. Повний опис відповідності наведено в матеріалі як PUID і PGID визначають користувача контейнера для файлів на хості.

README рекомендує спочатку створити каталог конфігурації та не перевизначати параметр Compose user:. Якщо ./config не існує під час виконання docker compose up, Docker створює його автоматично від імені root:root. В образі з фіксованою версією 0.9.925 entrypoint запускається від імені root і виправляє власника /config та файлів бази даних, перш ніж перейти на налаштовані UID і GID. Тому щойно створений каталог із власником root зазвичай не спричиняє цикл перезапусків. Перевизначення user: обходить цю підготовку. Монтування лише для читання або файлова система, яка не дозволяє змінювати власника, також можуть блокувати запис до бази даних. Перевірте стан командою ls -ln ./config. Вона виводить числові ідентифікатори власників, а не їхні імена. Два нулі означають, що власником є root. Якщо журнали підтверджують помилку прав доступу до локального каталогу, доступного для запису, виправте її командою sudo chown -R 1000:1000 ./config і знову запустіть контейнер.

Окремі томи для аудіокниг і електронних книжок позбавляють вас hardlink

У наведеній вище схемі /audiobooks, /ebooks і /downloads змонтовано як окремі bind mount, відповідно до власної команди запуску проєкту. Таку схему легко читати, але вона має один реальний недолік: hardlink перестають працювати.

Hardlink — це друге ім’я для тих самих даних на диску. Він не використовує додаткового місця й створюється миттєво, тому сімейство arr надає йому перевагу перед копіюванням. Hardlink працює лише в межах однієї файлової системи. Усередині контейнера це три окремі точки монтування, тому ядро відхиляє створення посилання, навіть якщо шляхи на хості розташовані на одному диску. Перевірте це самостійно.

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

Команда завершується помилкою, яка закінчується на Invalid cross-device link. Так ядро забороняє створювати посилання між точками монтування. Саме тому Chaptarr переходить до копіювання файлу. Копія буде коректною, але процес повільніший. Після цього аудіокнига існуватиме у двох примірниках, доки ви не видалите torrent. Поки ви продовжуєте роздавати його, ви цього не зробите. Після цього видаліть /srv/media/downloads/linktest.

Щоб зберегти hardlink, змонтуйте один батьківський каталог:

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

Потім задайте кореневі каталоги в Chaptarr як /data/audiobooks і /data/ebooks, а для клієнта завантажень використайте той самий mount /srv/media:/data, щоб обидва контейнери бачили ідентичний шлях. Спочатку переконайтеся, що відповідні шляхи на хості належать до однієї файлової системи: df -h /srv/media/downloads /srv/media/audiobooks має вивести однакове значення в стовпці Filesystem для обох шляхів. Різні значення означають різні диски, і жодна схема монтування не дасть змоги створювати hardlink між ними. Компроміс між цим підходом і named storage розглянуто в розділі bind mount проти named volume для медіафайлів.

Доступ до вебінтерфейсу без його публікації

Рядок із портом публікує сервіс на 127.0.0.1 не випадково. ufw deny 8789 не захищає опублікований порт Docker, оскільки Docker додає власні правила NAT (перетворення мережевих адрес) до ланцюжка, до якого ядро звертається раніше за ланцюжки ufw. Тому трафік перенаправляється ще до перевірки вашого правила. Така поведінка часто вводить в оману. Її описано в матеріалі чому опублікований порт Docker ігнорує правила ufw. Прив’язка до loopback повністю усуває цю проблему.

Отримуйте доступ до вебінтерфейсу через SSH-тунель із власного комп’ютера:

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

Залиште тунель запущеним і відкрийте http://127.0.0.1:8789 у браузері. Під час першого запуску налаштуйте автентифікацію. Лише після цього варто розглянути reverse proxy з TLS (захистом транспортного рівня) перед сервісом. Якщо ви підключаєтеся через тунель до трьох або чотирьох таких інструментів і використовуєте окремий пароль для кожного, зручніше розмістити proxy за self-hosted сервером єдиного входу, наприклад Authentik, щоб один вхід надавав доступ до всіх застосунків, а одне відкликання доступу закривало його для всіх.

Підключення indexer-ів і клієнта завантаження

Chaptarr підтримує стандартні протоколи arr для indexer-ів і клієнтів завантаження, тому Prowlarr передає indexer-и до нього так само, як до Sonarr. Звичайні torrent- і usenet-клієнти підключаються без спеціального налаштування.

Одне налаштування вводить в оману майже всіх. Коли Chaptarr запитує адресу хоста клієнта завантаження, не вказуйте localhost або 127.0.0.1. Усередині контейнера ця адреса вказує на сам контейнер. Тому Chaptarr намагається підключитися до власного порту 8080 і повідомляє, що з’єднання неможливе. Використовуйте ім’я контейнера qbittorrent і порт 8080. Переконайтеся, що обидва контейнери підключені до однієї мережі, за допомогою docker network inspect arr. Ця команда виводить імена всіх підключених контейнерів.

Якщо клієнт завантаження працює через VPN-контейнер із network_mode: "service:gluetun", він не має власного імені в мережі, оскільки використовує мережевий простір імен Gluetun. Звертайтеся до нього як до gluetun через порт, який відкриває Gluetun. Цю схему та пов’язану з нею маршрутизацію описано в матеріалі маршрутизація клієнта завантаження через Gluetun.

Перехід із Readarr: якою є реальна ціна міграції

Chaptarr несумісний із джерелами метаданих Readarr. Він отримує назви, авторів і видання через власний конвеєр із використанням кількох провайдерів, тому ідентифікатори, збережені Readarr, тут нічого не означають. Імпорту бази даних немає, як і прямого шляху оновлення.

Для наявної бібліотеки це означає, що файли залишаються без змін, а налаштування — ні. Цей процес не змінює нічого з того, що вже збережено на диску. Додайте кореневу папку, запустіть імпорт бібліотеки, і Chaptarr зіставить знайдені файли з власними метаданими. Вручну доведеться відновити профілі якості, формат іменування, налаштування indexer і клієнта, а також виправити кожне зіставлення, яке Chaptarr визначить неправильно. Для великої бібліотеки знадобиться ручна перевірка, тому плануйте на це вечір, а не десять хвилин.

Виконуйте міграцію в такому порядку. Зупиніть контейнер Readarr, але збережіть його config volume, щоб і надалі мати доступ до старих налаштувань під час їх повторного введення. Спочатку вкажіть Chaptarr одну невелику папку та перевірте зіставлення перед імпортом усієї бібліотеки. Видаляйте старий контейнер лише після того, як переконаєтеся, що все працює правильно.

Перед скануванням усієї бібліотеки варто врахувати один аспект конфіденційності: запити метаданих надсилаються до api2.chaptarr.com. У README зазначено, що такі запити можуть містити ID провайдера, текст пошуку, тип медіа, теги та імена файлів, але не містять повних шляхів, ідентифікаційних даних користувача й облікових даних. Імена файлів залишають ваш сервер. Для сервісу метаданих це нормальна поведінка, але рішення про її прийнятність слід ухвалити свідомо.

Передайте аудіокниги програвачу

Chaptarr упорядковує файли. Відтворенням займається інша програма. Зазвичай для цього використовують Audiobookshelf, оскільки він зберігає позицію прослуховування на різних пристроях і має мобільні застосунки. Офіційний образ має назву ghcr.io/advplyr/audiobookshelf:latest, а в документованому прикладі Compose порт хоста 13378 зіставляється з портом контейнера 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

Підключіть той самий шлях хоста, у який Chaptarr записує файли, а потім додайте /audiobooks як бібліотеку у вебінтерфейсі. Новий імпорт з’явиться після наступного сканування.

Якщо ви вже використовуєте Jellyfin, додайте цю папку як бібліотеку в ньому, і він відтворюватиме файли. Налаштування цього компонента описано в запуску Jellyfin як медіасервера на VPS. Для частини з електронними книгами передайте /srv/media/ebooks програмі для читання. Завдання Chaptarr завершується після того, як файл отримує назву й переміщується до потрібної папки.

Ризики обслуговування: ліцензія, середовище виконання та тег, що швидко змінюється

Chaptarr ліцензовано за GPL-3.0. Авторські права належать учасникам розробки Chaptarr, а частина коду походить від команди Servarr. Тому код залишається відкритим, і будь-хто може створити його fork, якщо цей мейнтейнер припинить роботу. Проєкт працює на .NET 10 — поточному LTS-релізі середовища виконання станом на серпень 2026 року. Це означає, що базова платформа підтримуватиметься роками, а не місяцями. Обидва факти важливі, коли ви оцінюєте, чи існуватиме цей проєкт наступного року.

Номери версій змінюються швидко. Версію 0.9.925 опубліковано 9 серпня 2026 року, а протягом наступних семи тижнів вийшло ще п’ять релізів. Усі релізи до 0.9.958 включно публікувалися як pre-release. Версія 0.9.965, опублікована 27 вересня 2026 року, є першою, позначеною як повний реліз. Зафіксуйте точний тег. Використання latest означає, що unattended docker compose pull може оновити програму на кілька версій протягом тижня. Такий молодий fork може змінити свій API між релізами, через що перестане працювати будь-який скрипт або dashboard, створений для нього. Фіксація версії — корисна звичка для кожного молодого проєкту, який ви розміщуєте самостійно. Саме тому інструкція з розгортання openGym як self-hosted трекера тренувань використовує фіксований git-тег.

Створюйте резервну копію перед кожним оновленням, а потім оновлюйте систему свідомо.

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

Проєкт не повідомляє про випадки втрати даних приблизно за шість місяців і за понад одинадцять тисяч користувачів. Водночас він і далі рекомендує зберігати резервні копії та не підключати бібліотеку, втрату якої ви не можете собі дозволити. Сприймайте обидві рекомендації серйозно. Скопіюйте архів конфігурації за межі сервера, оскільки резервна копія на тому самому диску, що й дані, які вона захищає, не є резервною копією. Цей tarball містить локальний стан застосунку, оскільки включає бази даних SQLite і конфігурацію в /config. Для даних на окремому database server потрібно також створити дамп бази даних. Саме так виглядає крок резервного копіювання під час самостійного розгортання Chatwoot на VPS разом із даними Postgres та завантаженими файлами.

Типові помилки та повідомлення, які ви побачите

Контейнер постійно перезапускається. docker compose ps показує Restarting. Спочатку прочитайте docker compose logs chaptarr. Сам по собі ./config, що належить root, не пояснює цикл перезапусків: перед запуском застосунку entrypoint зазвичай виправляє власника. Якщо в журналі зазначено, що каталог даних недоступний для запису, перевірте перевизначення Compose user:, монтування лише для читання або файлову систему, яка не дозволяє змінювати власника. Приберіть перевизначення, щоб entrypoint міг виконати налаштування; якщо власник локального каталогу, доступного для запису, неправильний, виконайте sudo chown -R 1000:1000 ./config.

Імпорт ніколи не завершується, а файли залишаються в каталозі завантажень. Chaptarr може прочитати завантажений файл, але не може записати його до бібліотеки. Порівняйте ls -ln /srv/media/audiobooks зі своїми PUID і PGID. Якщо каталог належить іншому UID або вашій групі, але група не має права запису, переміщення не виконується. UMASK=002 запобігає другому випадку для нових файлів.

Використання диска подвоюється після кожного імпорту. Hardlink не створено, тому файл було скопійовано. Виконайте перевірку ln з розділу про volumes. Помилка, що завершується на Invalid cross-device link, підтверджує це. Виправленням є монтування з одним спільним батьківським каталогом.

Клієнт завантажень не підключається. Як адресу хоста ви вказали localhost. Усередині контейнера це сам Chaptarr. Використайте ім’я контейнера та перевірте, що docker network inspect arr містить обидва контейнери.

Compose відмовляється запускати сервіс. Bind for 127.0.0.1:8789 failed: port is already allocated означає, що інший процес уже використовує цей порт. Знайдіть його за допомогою sudo ss -lntp | grep 8789.

У браузері взагалі нічого не відображається. Якщо порт прив’язано до 127.0.0.1, вашому ноутбуку немає до чого підключатися через інтернет. Це очікувана поведінка. Спочатку відкрийте SSH-тунель.

FAQ

Чи можна перенести мою бібліотеку Readarr у Chaptarr?

Не як імпорт. Chaptarr несумісний із джерелами метаданих Readarr і використовує власний pipeline провайдерів, тому збережені Readarr ідентифікатори не мають значення, а перетворення бази даних не передбачене. Файли на диску не змінюються. Додайте ті самі шляхи як root folders, запустіть імпорт бібліотеки й дозвольте Chaptarr самостійно зіставити файли. Профілі якості, формат назв, налаштування indexer і виправлення неправильних зіставлень потрібно виконати вручну, тому перед імпортом усієї бібліотеки почніть з однієї невеликої папки.

Чому Chaptarr не може записувати до моєї папки аудіокниг?

Користувач контейнера не має дозволу на запис до цього каталогу, зазвичай тому, що контейнер працює з іншим UID, ніж власник каталогу. Якщо ці змінні не задано, Chaptarr використовує PUID=99 і PGID=100. Це значення unRAID, і вони неправильні для звичайного Ubuntu VPS. Задайте власні id -u і id -g, використовуйте цю саму пару в download client і задайте UMASK=002, щоб нові файли залишалися доступними для запису групою. Перевірте власника за допомогою ls -ln у каталозі бібліотеки, оскільки ця команда виводить числові ідентифікатори, а не імена, які неможливо порівняти.

Чому після імпорту використання диска подвоїлося?

Chaptarr скопіював файл, оскільки не зміг створити для нього hard link. Монтування /downloads і /audiobooks як окремих bind mount створює в контейнері окремі точки монтування, а kernel забороняє створювати hard link між точками монтування та повертає Invalid cross-device link. Змонтуйте один батьківський каталог, наприклад /srv/media:/data, і використовуйте в застосунку /data/downloads та /data/audiobooks. Обидва шляхи також мають розташовуватися в одній файловій системі хоста; це підтверджує df -h.

Чи відтворює Chaptarr мої аудіокниги?

Ні. Він знаходить, завантажує, перейменовує та впорядковує файли, а відтворення виконує окрема програма. Поширеною парою є Audiobookshelf, оскільки він запам’ятовує позицію відтворення на різних пристроях. Для цього використовуйте офіційний image ghcr.io/advplyr/audiobookshelf:latest і змонтуйте той самий шлях до аудіокниг на хості. Jellyfin також відтворюватиме файли, якщо додати папку як бібліотеку.

Чи безпечно запускати Chaptarr для важливої бібліотеки?

Це beta-версія відносно молодого fork-проєкту. Сам проєкт зазначає це й повідомляє про відсутність випадків втрати даних приблизно за шість місяців і за наявності понад одинадцяти тисяч користувачів. Позитивними ознаками є ліцензія GPL-3.0, яка дає змогу створювати fork коду, і база .NET 10 — runtime із довгостроковою підтримкою станом на August 2026. Фіксуйте точний image tag, наприклад 0.9.925, замість latest, створюйте резервну копію /config перед кожним оновленням і зберігайте цей архів не на сервері.