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

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

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

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

У цьому посібнику використовувався тег образу chaptarr/chaptarr:0.9.925, який був найновішим релізом станом на 9 August 2026 року. Chaptarr називає себе бета-версією. Перш ніж підключати його до бібліотеки, яку неможливо відновити, прочитайте розділ про обслуговування наприкінці посібника.

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

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

Наразі Chaptarr доступний лише як Docker image. Нативна збірка для Windows позначена як така, що перебуває в розробці. Пакета для дистрибутива немає. Контейнер зберігає базу даних у /config, використовуючи SQLite за замовчуванням. Якщо ви вже використовуєте PostgreSQL, контейнер може підключатися до зовнішнього 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

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

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

У README описано одну конкретну проблему, яку варто повторити. Якщо ./config не існує під час запуску docker compose up, Docker створює його автоматично. Власником каталогу стає root:root. Після цього контейнер запускається з UID 1000 і не може записати власну базу даних, тому він завершує роботу та безперервно перезапускається. Перевірте це за допомогою 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 відтворюватиме файли, але відновлення відтворення для одного довгого файлу аудіокниги працює гірше, ніж у спеціалізованого сервера аудіокниг. Налаштування цього варіанта описано в розділі запуск Jellyfin як медіасервера на VPS. Для електронних книг передайте /srv/media/ebooks програмі для читання. Робота Chaptarr завершується після того, як файл отримав правильну назву та був переміщений у потрібну папку.

Ризики обслуговування: ліцензія, runtime і швидка зміна тегів

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

Номери версій змінюються швидко. Релізи публікуються як pre-release, а 0.9.925 було випущено в той самий день, коли створювався цей огляд. Зафіксуйте точний тег. Використання latest означає, що автоматизований docker compose pull може перемістити вас на кілька версій уперед за тиждень. Такий молодий fork може змінювати API між релізами, через що перестануть працювати скрипти або dashboard, написані для нього.

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

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 достатньо лише тому, що Chaptarr зберігає свій стан в одному файлі SQLite у /config; для даних на окремому сервері бази даних потрібно також створити дамп бази. Саме так виглядає крок резервного копіювання під час self-hosting Chatwoot на VPS разом із його даними Postgres і завантаженими файлами.

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

Контейнер постійно перезапускається. docker compose ps показує Restarting. Виконайте ls -ln ./config. Два нулі у стовпцях власника означають, що Docker створив каталог від імені root, а користувач контейнера не може записувати до своєї бази даних. Виконайте sudo chown -R 1000:1000 ./config.

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

Після кожного імпорту використання дискового простору подвоюється. Жорстке посилання не створено, тому файл скопійовано. Виконайте тест ln з розділу про томи. Помилка, що закінчується на 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 і використовує власний конвеєр провайдерів, тому збережені в Readarr ідентифікатори не мають значення, а конвертації бази даних немає. Ваші файли на диску не змінюються. Додайте ті самі шляхи як кореневі папки, запустіть імпорт бібліотеки та дозвольте Chaptarr самостійно зіставити файли. Профілі якості, формат іменування, параметри індексаторів і виправлення неправильних зіставлень потрібно налаштовувати вручну, тому перед імпортом усієї бібліотеки почніть з однієї невеликої папки.

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

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

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

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

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

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

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

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