Chaptarr 설치 및 설정 가이드: Readarr 대체하기

Chaptarr란 무엇이며 왜 Readarr 사용자가 이를 필요로 하는가

Chaptarr는 단일 인스턴스에서 오디오북과 전자책을 관리할 수 있도록 Readarr를 포크(fork)한 프로젝트입니다. 이 소프트웨어는 새로운 릴리스를 감시하고, 다운로드 클라이언트로 전송하며, 결과물을 이름을 변경하여 라이브러리에 정리합니다. 자체적인 재생 기능은 없으므로 Audiobookshelf와 같은 플레이어와 함께 사용해야 합니다.

Readarr는 2025년 6월 27일에 서비스가 종료되었습니다. Servarr 팀의 공지에 따르면, 프로젝트의 메타데이터를 더 이상 사용할 수 없게 되었고 Open Library로 전환하려는 커뮤니티의 노력이 중단되었기 때문입니다. 현재 저장소는 아카이브된 상태입니다. 이로 인해 도서 및 오디오북 컬렉션을 관리할 도구가 사라졌고, Chaptarr가 그 역할을 이어받았습니다. Chaptarr는 Sonarr 및 Radarr에서 이미 익숙한 구성(인덱서, 다운로드 클라이언트, 품질 프로파일, 루트 폴더)을 유지하면서 오디오북 처리를 위한 기능을 추가했습니다. 여기에는 내레이터 인식 정리, 동일 타이틀의 다중 에디션 관리, M4B 및 챕터별 MP3 지원, MP3를 M4B로 변환하는 기능이 포함됩니다.

이 가이드는 2026년 8월 9일 기준 최신 릴리스인 chaptarr/chaptarr:0.9.925 이미지 태그를 사용했습니다. Chaptarr는 스스로를 베타 소프트웨어로 정의합니다. 복구가 불가능한 라이브러리에 적용하기 전에 마지막 부분의 유지보수 섹션을 반드시 읽어보시기 바랍니다.

시작하기 전에 필요한 것

Docker와 Compose 플러그인이 설치된 VPS, 그리고 라이브러리를 저장할 충분한 디스크 공간이 필요합니다. 오디오북은 용량이 크며, 하드링크를 사용할 수 없는 가져오기 작업은 일시적으로 파일 사본을 2개 유지하게 됩니다. 이와 관련해서는 아래의 볼륨 섹션에서 설명합니다. 만약 서버에 Docker가 설치되어 있지 않다면, Docker가 설치되어 실행 중인 VPS를 먼저 확인하고 돌아오십시오.

Chaptarr는 현재 Docker 이미지로만 제공됩니다. 네이티브 Windows 빌드는 개발 중이며, 별도의 배포 패키지는 없습니다. 컨테이너는 기본적으로 데이터베이스를 /config에 SQLite 형태로 저장합니다. 만약 이미 운영 중인 PostgreSQL 서버가 있다면 Chaptarr__Postgres__* 환경 변수를 통해 외부 서버를 사용할 수도 있습니다. 단일 서버에서 한 명의 사용자가 이용하는 경우에는 SQLite가 적합한 선택입니다.

Chaptarr용 Compose 서비스

이 서비스는 기존 스택에 통합됩니다. 특정 릴리스 태그를 고정하고, 웹 UI를 루프백 인터페이스에만 노출하며, 다운로드 클라이언트가 이미 사용 중인 네트워크에 연결합니다.

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와 토렌트 클라이언트가 다른 Compose 프로젝트에 있을 때 사용하십시오. 그렇지 않으면 두 번째 Compose 파일이 자체적인 격리 네트워크를 생성하여 Chaptarr가 qbittorrent를 이름으로 해석할 수 없게 됩니다. 실제 네트워크 이름은 docker network ls에서 확인하십시오. 만약 이미 하나의 파일로 스택을 구성했다면, 해당 파일에 chaptarr: 서비스를 추가하고 networks: 블록 전체를 삭제하십시오. 더 넓은 구성 방식은 Docker Compose 기반의 전체 arr 스택에서, 이름 해석 규칙은 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 명령어로 본인의 UID와 GID를 확인한 뒤 해당 값을 파일에 입력하십시오.

동일한 파일에 접근하는 모든 컨테이너는 동일한 쌍의 값을 사용해야 합니다. 다운로드 클라이언트는 /srv/media/downloads에 파일을 쓰고, Chaptarr는 해당 파일을 /srv/media/audiobooks로 이동하며, 플레이어는 그곳에서 파일을 읽습니다. 다운로드 클라이언트가 1000:1000 권한으로 파일을 쓰고 Chaptarr가 99:100으로 실행되면, Chaptarr가 소유하지 않은 파일을 삭제하거나 이동할 수 없으므로 가져오기 작업이 실패합니다. UMASK=002 설정을 사용하면 새 파일에 그룹 쓰기 권한이 부여되는데, 이는 여러 컨테이너가 하나의 미디어 그룹을 공유할 때 필요한 설정입니다. 전체 매핑 정보는 PUID와 PGID가 컨테이너 사용자를 호스트 파일에 매핑하는 방법에서 확인할 수 있습니다.

README에서는 특정 주의 사항을 경고하고 있으며, 이를 다시 강조할 필요가 있습니다. docker compose up를 실행할 때 ./config 디렉터리가 존재하지 않으면, Docker가 해당 디렉터리를 생성하며 소유자를 root:root으로 지정합니다. 이 경우 컨테이너는 UID 1000으로 실행되지만 자신의 데이터베이스에 쓸 수 없게 되어, 종료와 재시작을 무한히 반복하게 됩니다. ls -ln ./config 명령어로 확인하십시오. 이 명령어는 소유자를 이름 대신 숫자로 출력합니다. 두 값이 0이면 root가 소유하고 있다는 뜻입니다. sudo chown -R 1000:1000 ./config 명령어로 소유권을 수정한 뒤 컨테이너를 다시 시작하십시오.

오디오북과 전자책 볼륨을 분리하면 하드링크를 사용할 수 없는 이유

위의 레이아웃은 프로젝트의 실행 명령과 동일하게 /audiobooks, /ebooks, /downloads를 각각 별도의 바인드 마운트로 설정합니다. 읽기는 쉽지만, 여기에는 한 가지 실질적인 비용이 따릅니다. 바로 하드링크가 작동하지 않는다는 점입니다.

하드링크는 디스크상에서 동일한 데이터에 부여하는 두 번째 이름입니다. 추가 공간을 차지하지 않고 즉시 생성되므로, arr 제품군에서는 파일을 복사하는 대신 하드링크를 선호합니다. 하드링크는 하나의 파일 시스템 내부에서만 작동합니다. 컨테이너 내부에서는 이들이 세 개의 분리된 마운트 지점이므로, 호스트 경로가 동일한 디스크에 있더라도 커널은 링크 생성을 거부합니다. 직접 테스트해 보십시오.

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

이 명령은 Invalid cross-device link으로 끝나는 오류와 함께 실패합니다. 이는 커널이 마운트 지점을 가로질러 링크하는 것을 거부하기 때문이며, 바로 이 이유로 Chaptarr가 파일 복사 방식으로 전환하는 것입니다. 복사본은 정확하지만 속도가 느리며, 토렌트 시딩을 멈추지 않는 한 오디오북 파일이 두 번 존재하게 됩니다. 작업 후에는 /srv/media/downloads/linktest을 삭제하십시오.

하드링크를 유지하려면 대신 하나의 상위 디렉터리를 마운트하십시오.

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

그런 다음 Chaptarr 내부의 루트 폴더를 /data/audiobooks 및 /data/ebooks로 설정하고, 다운로드 클라이언트에도 동일한 /srv/media:/data 마운트를 제공하여 두 컨테이너가 하나의 동일한 경로를 보도록 하십시오. 먼저 호스트 측이 단일 파일 시스템인지 확인하십시오. df -h /srv/media/downloads /srv/media/audiobooks 명령을 실행했을 때 두 경로 모두 Filesystem 열에 동일한 값이 출력되어야 합니다. 값이 다르면 서로 다른 디스크를 의미하며, 어떤 마운트 레이아웃으로도 그 사이에서 하드링크를 생성할 수 없습니다. 이 방식과 네임드 볼륨 간의 장단점은 미디어용 바인드 마운트와 네임드 볼륨 비교에서 다룹니다.

웹 UI를 노출하지 않고 접속하기

포트 라인에서 127.0.0.1로 게시하는 데에는 이유가 있습니다. ufw deny 8789은 게시된 Docker 포트를 보호하지 못합니다. Docker는 커널이 ufw 규칙을 확인하기 전에 도달하는 체인에 자체 NAT(네트워크 주소 변환) 규칙을 작성하기 때문에, 사용자의 규칙이 적용되기 전에 트래픽이 전달됩니다. 이러한 동작은 사용자들을 자주 당황하게 만들며, 이에 대한 설명은 게시된 Docker 포트가 ufw 규칙을 무시하는 이유에서 확인할 수 있습니다. 루프백(loopback)에 바인딩하면 이 문제를 완전히 우회할 수 있습니다.

사용자의 로컬 머신에서 SSH 터널을 통해 UI에 접속하십시오:

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

해당 명령을 실행 상태로 두고 브라우저에서 http://127.0.0.1:8789를 엽니다. 첫 실행 시 인증을 설정하십시오. 그 이후에야 비로소 TLS(전송 계층 보안)를 적용한 리버스 프록시를 앞단에 배치하는 것을 고려해야 합니다. 이러한 도구 3~4개를 각각 별도의 비밀번호로 터널링하여 사용하게 되면, Authentik과 같은 자체 호스팅 싱글 사인온 서버 뒤에 프록시를 배치하는 것이 더 깔끔한 해결책입니다. 이를 통해 하나의 로그인으로 모든 앱을 관리하고, 권한을 회수하면 모든 앱에 대한 접근을 한 번에 차단할 수 있습니다.

인덱서와 다운로드 클라이언트 연결

Chaptarr는 표준 arr 인덱서 및 다운로드 클라이언트 프로토콜을 사용합니다. 따라서 Prowlarr는 Sonarr와 동일한 방식으로 인덱서를 Chaptarr에 푸시하며, 일반적인 토렌트 및 유즈넷 클라이언트는 별도의 특수 처리 없이 연결됩니다.

거의 모든 사용자가 한 가지 설정에서 실수를 범합니다. Chaptarr가 다운로드 클라이언트 호스트를 물어볼 때 localhost나 127.0.0.1을 입력하지 마십시오. 컨테이너 내부에서 해당 주소는 자기 자신을 가리키므로, Chaptarr는 자신의 8080 포트에 연결을 시도하다가 연결 실패 오류를 보고하게 됩니다. 컨테이너 이름인 qbittorrent과 포트 8080을 사용하십시오. docker network inspect arr 명령을 실행하여 두 컨테이너가 동일한 네트워크에 있는지 확인하십시오. 이 명령은 연결된 모든 컨테이너를 이름별로 나열합니다.

다운로드 클라이언트가 network_mode: "service:gluetun"을 사용하는 VPN 컨테이너를 통해 실행되는 경우, Gluetun의 네트워크 네임스페이스를 공유하므로 네트워크상에 고유한 이름이 없습니다. 이 경우 Gluetun이 노출하는 포트에서 gluetun로 주소를 지정하십시오. 해당 구성과 그에 따른 라우팅 설정은 Gluetun을 통한 다운로드 클라이언트 라우팅에서 확인할 수 있습니다.

Readarr 전환: 마이그레이션의 실제 비용

Chaptarr는 Readarr의 메타데이터 소스와 호환되지 않습니다. Chaptarr는 여러 공급자를 거치는 자체 파이프라인을 통해 제목, 저자, 판본을 확인하므로 Readarr가 저장한 식별자는 여기에서 아무런 의미가 없습니다. 데이터베이스 가져오기 기능은 없으며, 기존 설정을 그대로 유지하며 업그레이드할 방법도 없습니다.

기존 라이브러리의 경우, 파일은 안전하지만 설정은 그렇지 않습니다. 이 과정에서 디스크에 있는 기존 파일은 전혀 건드리지 않습니다. 루트 폴더를 추가하고 라이브러리 가져오기를 실행하면, Chaptarr가 발견한 파일들을 자체 메타데이터와 대조합니다. 사용자가 직접 다시 설정해야 할 항목은 품질 프로필, 명명 형식, 인덱서 및 클라이언트 설정, 그리고 Chaptarr가 잘못 매칭한 모든 항목입니다. 라이브러리가 크다면 수동 수정 작업이 필요하므로 10분 내외가 아닌 저녁 시간 전체를 할애할 계획을 세워야 합니다.

다음 순서대로 진행하십시오. Readarr 컨테이너를 중지하되 설정 볼륨은 유지하십시오. 그래야 설정을 다시 입력하는 동안 이전 설정을 참조할 수 있습니다. 먼저 작은 폴더 하나를 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가 파일을 저장하는 호스트 경로를 동일하게 마운트한 뒤, 웹 UI 내에서 /audiobooks를 라이브러리로 추가하십시오. 다음 스캔 이후 새로운 항목이 나타납니다.

이미 Jellyfin을 운영 중이라면 해당 폴더를 라이브러리로 추가하여 파일을 재생할 수 있습니다. 다만, 긴 오디오북 파일 하나를 재생할 때의 이어 듣기 기능은 전용 오디오북 서버보다 부족할 수 있습니다. 해당 설정은 VPS에서 미디어 서버로 Jellyfin 운영하기에서 다룹니다. 전자책의 경우, /srv/media/ebooks를 리더 애플리케이션으로 전달하십시오. 파일 이름 지정과 정리가 완료되면 Chaptarr의 역할은 끝납니다.

유지보수 위험: 라이선스, 런타임, 그리고 빠르게 변하는 태그

Chaptarr는 GPL-3.0 라이선스를 따르며, 저작권은 Chaptarr 기여자들에게 있고 일부는 Servarr 팀의 코드를 포함합니다. 따라서 코드는 오픈 소스로 유지되며, 현재 관리자가 중단하더라도 누구나 다시 포크할 수 있습니다. 이 프로젝트는 2026년 8월 기준 .NET 10 장기 지원(LTS) 런타임 버전을 기반으로 빌드되므로, 기반 환경이 수개월이 아닌 수년간 지원됩니다. 이 두 가지 사실은 내년에도 이 프로젝트가 존재할지 판단할 때 중요한 요소입니다.

버전 번호는 빠르게 바뀝니다. 릴리스는 프리릴리스 형태로 게시되며, 이 가이드를 작성하는 당일에 0.9.925 버전이 출시되었습니다. 정확한 태그를 고정하십시오. latest을 사용하면 자동화된 docker compose pull로 인해 일주일 사이에도 여러 버전이 올라갈 수 있습니다. 이처럼 초기 단계의 포크는 릴리스마다 API가 변경될 수 있으며, 이는 작성해 둔 스크립트나 대시보드를 손상시킬 수 있습니다.

업그레이드 전에는 항상 백업을 수행하고, 의도적으로 업그레이드를 진행하십시오.

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

프로젝트 보고에 따르면 약 6개월 동안 11,000명이 넘는 사용자 환경에서 데이터 손실 사례가 발생하지 않았다. 그래도 백업을 유지하고, 손실을 감당할 수 없는 라이브러리를 대상으로 지정하지 말 것을 권장한다. 이 두 가지 내용을 모두 중요하게 받아들여야 한다. 설정 아카이브를 서버 외부로 복사해야 한다. 보호 대상과 같은 디스크에 저장된 백업은 백업이 아니기 때문이다. Chaptarr는 /config 아래의 단일 SQLite 파일에 상태를 저장하므로 해당 tarball 하나만으로 충분하다. 별도의 database server에 있는 데이터는 database도 dump해야 한다. Postgres 데이터와 업로드된 파일을 함께 사용하는 VPS에서 Chatwoot 자체 호스팅 환경에서는 백업 단계가 이런 형태가 된다.

실패 유형 및 확인 가능한 메시지

컨테이너가 반복적으로 재시작됩니다. docker compose ps에 Restarting가 표시됩니다. ls -ln ./config을 실행하십시오. 소유자 열에 0이 두 개 있다면 Docker가 해당 디렉터리를 root 권한으로 생성했음을 의미하며, 컨테이너 사용자가 데이터베이스에 쓰기 작업을 할 수 없습니다. sudo chown -R 1000:1000 ./config을 실행하십시오.

가져오기 작업이 완료되지 않고 파일이 다운로드 폴더에 남아 있습니다. Chaptarr가 다운로드 폴더를 읽을 수는 있지만 라이브러리 폴더에 쓸 수 없는 상태입니다. ls -ln /srv/media/audiobooks와 사용자의 PUID 및 PGID를 비교하십시오. 다른 UID가 소유하고 있거나, 그룹 소유이지만 그룹 쓰기 권한이 없는 디렉터리는 파일 이동을 차단합니다. UMASK=002는 새로 생성되는 파일에 대해 후자의 문제를 방지합니다.

가져오기를 할 때마다 디스크 사용량이 두 배로 늘어납니다. 하드링크가 생성되지 않아 파일이 복사된 것입니다. 볼륨 섹션의 ln 테스트를 실행하십시오. Invalid cross-device link로 끝나는 오류가 발생한다면 하드링크가 실패한 것이며, 단일 상위 마운트(single-parent mount)를 설정하여 해결할 수 있습니다.

다운로드 클라이언트가 연결되지 않습니다. 호스트로 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

Can I migrate my Readarr library to Chaptarr?

Not as an import. Chaptarr is not compatible with Readarr's metadata sources and uses its own provider pipeline, so Readarr's stored identifiers carry no meaning and there is no database conversion. Your files on disk are untouched. You add the same paths as root folders, run a library import, and let Chaptarr match the files itself. Quality profiles, naming format, indexer settings and any wrong matches are manual work, so start with one small folder before importing everything.

Why can Chaptarr not write to my audiobook folder?

The container's user does not own the files. Chaptarr falls back to PUID=99 and PGID=100 when those variables are unset, which are unRAID's values and wrong on a normal Ubuntu VPS. Set them to your own id -u and id -g, use the same pair on the download client, and set UMASK=002 so new files stay group-writable. Check ownership with ls -ln on the library directory, since it prints the numbers rather than names you cannot compare.

Why did my disk usage double after an import?

Chaptarr copied the file because it could not hardlink it. Mounting /downloads and /audiobooks as separate binds makes them separate mount points inside the container, and the kernel refuses a hardlink across mount points with Invalid cross-device link. Mount one parent directory such as /srv/media:/data and use /data/downloads and /data/audiobooks inside the app. Both paths must also sit on one host filesystem, which df -h confirms.

Does Chaptarr play my audiobooks?

No. It finds, downloads, renames and files them, and playback is a separate program. Audiobookshelf is the common pairing because it remembers your position across devices, using the official image ghcr.io/advplyr/audiobookshelf:latest with the same host audiobook path mounted. Jellyfin will also play the files if you add the folder as a library, with weaker resume behaviour on long single-file audiobooks.

Is Chaptarr safe to run on a library I care about?

It is beta software from a young fork, and the project says so itself while reporting no data loss events over about six months and more than eleven thousand users. The reassuring parts are the GPL-3.0 licence, which keeps the code forkable, and the .NET 10 base, a long term support runtime as of August 2026. Pin an exact image tag such as 0.9.925 rather than latest, back up /config before each upgrade, and keep that archive off the server.