Como instalar o Chaptarr para audiolivros em VPS

O que é o Chaptarr e por que os utilizadores do Readarr precisam dele

O Chaptarr é um fork do Readarr que gere audiolivros e ebooks a partir de uma única instância. Monitoriza novos lançamentos, envia-os para o seu cliente de downloads, depois muda o nome dos resultados e organiza-os na sua biblioteca. Não reproduz conteúdo, por isso deve associá-lo a um leitor como o Audiobookshelf.

O Readarr foi descontinuado em 27 de junho de 2025. O aviso da própria equipa Servarr indica o motivo: os metadados do projeto tinham-se tornado inutilizáveis e o esforço da comunidade para migrar para a Open Library ficou parado. O repositório está arquivado. Isso deixou as coleções de livros e audiolivros sem um gestor mantido, e o Chaptarr assumiu essa função. Mantém a estrutura que já conhece do Sonarr e do Radarr (indexadores, clientes de downloads, perfis de qualidade e pastas raiz) e acrescenta suporte para audiolivros: organização por narrador, várias edições do mesmo título, suporte para M4B e MP3 por capítulos e conversão de MP3 para M4B.

Este guia utilizou a tag de imagem chaptarr/chaptarr:0.9.925, que era a versão mais recente em 9 de agosto de 2026. O Chaptarr apresenta-se como software beta. Leia a secção de manutenção perto do fim antes de o apontar para uma biblioteca que não possa substituir.

O que é necessário antes de começar

Uma VPS com Docker e o plugin Compose em execução, além de espaço em disco suficiente para a biblioteca. Os audiolivros ocupam bastante espaço. Uma importação que não consegue usar hardlinks mantém duas cópias de um ficheiro durante algum tempo, conforme explicado na secção sobre volumes abaixo. Se o Docker ainda não estiver instalado no servidor, comece por Docker instalado e em execução numa VPS e depois volte aqui.

Atualmente, o Chaptarr é disponibilizado apenas como imagem Docker. Está em desenvolvimento uma compilação nativa para Windows, e não existe um pacote de distribuição. Por predefinição, o contentor armazena a base de dados em /config como SQLite. Também pode usar um servidor PostgreSQL externo através das variáveis de ambiente Chaptarr__Postgres__*, se já tiver um em execução. O SQLite é a opção adequada para um utilizador num único servidor.

O serviço Compose do Chaptarr

Este serviço integra-se numa stack existente. Fixa uma tag publicada, expõe a interface web apenas no loopback e liga-se à rede que o cliente de downloads já utiliza.

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

A linha external: true significa “esta rede já existe; associe-se a ela”. Use-a quando o Prowlarr e o cliente torrent pertencem a outro projeto Compose, porque um segundo ficheiro Compose cria, de outra forma, a sua própria rede isolada. Nesse caso, o Chaptarr nunca consegue resolver qbittorrent pelo nome. Obtenha o nome real com docker network ls. Se a sua stack já estiver num único ficheiro, adicione o serviço chaptarr: a esse ficheiro e elimine todo o bloco networks:. A estrutura completa é explicada em uma stack arr completa com Docker Compose, e as regras de nomenclatura em como o Compose resolve redes e nomes de serviços.

Crie manualmente o diretório de configuração e inicie o serviço.

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

docker compose ps deve mostrar o contentor como Up. Um contentor listado como Restarting falhou ao iniciar e está a ser reiniciado. A causa é quase sempre o diretório de configuração. O log deixa de avançar quando a aplicação começa a escutar na porta 8789.

PUID, PGID e o diretório que o Docker cria como root

O Chaptarr usa PUID=99 e PGID=100 por predefinição quando não os define. Esses são os valores do unRAID. Num VPS Ubuntu normal, pertencem a uma conta que não é útil para o seu utilizador. Por isso, os ficheiros ficam com um proprietário que não pode escrever neles. Consulte os seus próprios valores com id -u e id -g e coloque-os no ficheiro.

Todos os contentores que acedem aos mesmos ficheiros precisam do mesmo par. O cliente de transferências escreve em /srv/media/downloads, o Chaptarr move o ficheiro para /srv/media/audiobooks e o leitor acede a esse local. Se o cliente de transferências escrever como 1000:1000 e o Chaptarr executar como 99:100, a importação falha porque o Chaptarr não pode eliminar nem mover um ficheiro que não lhe pertence. UMASK=002 faz com que os ficheiros novos possam ser escritos pelo grupo. É isso que precisa quando vários contentores partilham um grupo de media. O mapeamento completo está em como PUID e PGID associam um utilizador do contentor aos ficheiros do host.

O README alerta para um problema específico, que vale a pena repetir. Se ./config não existir quando executar docker compose up, o Docker cria-o automaticamente com root:root como proprietário. O contentor executa depois como UID 1000 e não pode escrever na sua própria base de dados. Por isso, termina e reinicia continuamente. Verifique com ls -ln ./config, que apresenta os proprietários numéricos em vez dos nomes. Dois zeros significam que root é o proprietário. Corrija com sudo chown -R 1000:1000 ./config e inicie novamente o contentor.

Por que volumes separados para audiolivros e ebooks impedem hardlinks

O esquema acima monta /audiobooks, /ebooks e /downloads como binds separados, de acordo com o comando de execução do próprio projeto. É fácil de ler, mas tem um custo real: os hardlinks deixam de funcionar.

Um hardlink é um segundo nome para os mesmos dados no disco. Não usa espaço adicional e é instantâneo, por isso a família arr prefere hardlinks a cópias. Um hardlink só funciona dentro do mesmo sistema de ficheiros. Dentro do contentor, estes são três pontos de montagem separados, por isso o kernel recusa a ligação mesmo quando os caminhos no host estão no mesmo disco. Teste por si próprio.

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

O comando falha com um erro que termina em Invalid cross-device link. É o kernel a recusar a ligação entre pontos de montagem e é exatamente por isso que o Chaptarr recorre à cópia do ficheiro. A cópia está correta, mas é mais lenta, e o audiolivro passa a existir duas vezes até remover o torrent, o que não fará enquanto continuar a disponibilizá-lo. Elimine /srv/media/downloads/linktest depois.

Para manter os hardlinks, monte um diretório-pai:

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

Depois, defina os diretórios raiz dentro do Chaptarr como /data/audiobooks e /data/ebooks e atribua ao cliente de downloads o mesmo ponto de montagem /srv/media:/data, para que ambos os contentores vejam um caminho idêntico. Confirme primeiro que o lado do host usa um único sistema de ficheiros: df -h /srv/media/downloads /srv/media/audiobooks deve apresentar o mesmo valor na coluna Filesystem para ambos. Valores diferentes significam discos diferentes e nenhuma disposição de montagem permite criar hardlinks entre eles. A diferença entre esta opção e o armazenamento nomeado é explicada em bind mounts em comparação com volumes nomeados para multimédia.

Aceder à interface web sem a expor

A linha da porta publica em 127.0.0.1 por uma razão. ufw deny 8789 não protege uma porta Docker publicada, porque o Docker escreve as suas próprias regras NAT (network address translation) numa cadeia que o kernel processa antes das regras do ufw. Por isso, o tráfego é encaminhado antes de a sua regra ser sequer consultada. Este comportamento apanha constantemente os administradores de surpresa e é explicado em por que uma porta Docker publicada ignora as suas regras do ufw. A associação à interface de loopback contorna totalmente o problema.

Aceda à interface através de um túnel SSH a partir da sua própria máquina:

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

Deixe o túnel em execução e abra http://127.0.0.1:8789 no navegador. Configure a autenticação na primeira execução. Só depois deve considerar colocar um reverse proxy com TLS (transport layer security) à frente da aplicação. Quando estiver a criar túneis para três ou quatro destas ferramentas, cada uma com uma palavra-passe diferente, a solução mais organizada é colocar o proxy atrás de um servidor de single sign-on self-hosted, como o Authentik, para que um único início de sessão cubra todas as aplicações e uma única revogação as feche a todas.

Conecte os indexadores e o cliente de downloads

O Chaptarr utiliza os protocolos padrão de indexadores e clientes de downloads do ecossistema arr. Por isso, o Prowlarr envia-lhe os indexadores da mesma forma que faz com o Sonarr. Os clientes habituais de torrent e Usenet ligam-se sem tratamento especial.

Uma definição causa problemas a quase toda a gente. Quando o Chaptarr pedir o host do cliente de downloads, não introduza localhost nem 127.0.0.1. Dentro de um contentor, esse endereço aponta para o próprio contentor. Assim, o Chaptarr tenta ligar-se à sua própria porta 8080 e indica que não consegue estabelecer a ligação. Utilize o nome do contentor, qbittorrent, com a porta 8080. Confirme que ambos os contentores estão na mesma rede com docker network inspect arr. Este comando lista todos os contentores ligados pelo nome.

Se o cliente de downloads for executado através de um contentor VPN com network_mode: "service:gluetun", não terá um nome próprio na rede. Isto acontece porque partilha o namespace de rede do Gluetun. Nesse caso, utilize gluetun na porta exposta pelo Gluetun. Essa configuração e o encaminhamento associado são explicados em encaminhar um cliente de downloads através do Gluetun.

A rutura do Readarr: o custo real de uma migração

O Chaptarr não é compatível com as fontes de metadados do Readarr. Resolve títulos, autores e edições através do seu próprio pipeline, recorrendo a vários fornecedores. Por isso, os identificadores armazenados pelo Readarr não têm qualquer significado aqui. Não existe importação da base de dados nem um caminho de atualização direta.

Numa biblioteca existente, isto significa que os ficheiros estão seguros, mas as definições não. Este processo não altera nada do que já está no disco. Adicione uma pasta raiz, execute uma importação da biblioteca e o Chaptarr associará os ficheiros encontrados aos seus próprios metadados. Terá de recriar manualmente os perfis de qualidade, o formato dos nomes, as definições dos indexadores e dos clientes, além de todas as correspondências que o Chaptarr identificar incorretamente. Uma biblioteca grande exigirá uma revisão manual, por isso reserve uma noite, não dez minutos.

Faça isto pela seguinte ordem. Pare o contentor do Readarr, mas mantenha o volume de configuração para poder consultar as definições antigas enquanto as introduz novamente. Aponte primeiro o Chaptarr para uma pasta pequena e verifique as correspondências antes de importar tudo. Só remova o contentor antigo quando estiver satisfeito.

Antes de analisar uma biblioteca inteira, tenha em conta um detalhe de privacidade: as consultas de metadados são enviadas para api2.chaptarr.com. O README indica que esses pedidos podem incluir IDs de fornecedores, texto de pesquisa, tipo de conteúdo, etiquetas e nomes de ficheiros, mas não incluem caminhos completos, identidade do utilizador nem credenciais. Os nomes de ficheiros saem do seu servidor. Isto é normal num serviço de metadados, mas deve ser uma decisão consciente.

Entregue os audiolivros a um reprodutor

O Chaptarr organiza os ficheiros. A reprodução fica a cargo de outro programa. O Audiobookshelf é o parceiro habitual porque acompanha a posição de reprodução entre dispositivos e tem aplicações para telemóvel. A imagem oficial é ghcr.io/advplyr/audiobookshelf:latest, e o exemplo documentado de Compose publica a porta 13378 do host na porta 80 do contentor.

  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

Monte o mesmo caminho do host onde o Chaptarr grava os ficheiros e, em seguida, adicione /audiobooks como biblioteca na interface Web. A nova importação aparece depois da próxima análise.

Se já utiliza o Jellyfin, pode adicionar a pasta como biblioteca e reproduzir os ficheiros nesse serviço. No entanto, o comportamento de retoma para um único ficheiro de audiolivro longo é menos eficaz do que num servidor dedicado a audiolivros. A configuração dessa opção é explicada em executar o Jellyfin como servidor multimédia numa VPS. Para a parte dos ebooks, entregue /srv/media/ebooks a uma aplicação de leitura. O trabalho do Chaptarr termina quando o ficheiro recebe o nome correto e é colocado na pasta adequada.

Risco de manutenção: licença, runtime e uma tag que muda rapidamente

O Chaptarr é licenciado sob GPL-3.0 e tem os direitos de autor atribuídos aos contribuidores do Chaptarr, com partes provenientes da equipa Servarr. Por isso, o código continua aberto e qualquer pessoa pode criar um fork se este responsável deixar de manter o projeto. O projeto baseia-se no .NET 10, a versão atual de suporte de longo prazo do runtime em agosto de 2026. Isto significa que a base tem suporte durante anos, e não apenas meses. Ambos os factos são relevantes para avaliar se este projeto continuará disponível no próximo ano.

Os números de versão avançam rapidamente. As releases são publicadas como pré-releases, e a 0.9.925 foi publicada no mesmo dia deste guia. Fixe uma tag exata. Usar latest significa que um docker compose pull não supervisionado pode atualizar o sistema várias versões numa semana. Um fork tão recente também pode alterar a API entre releases, quebrando qualquer script ou dashboard criado para a versão anterior. Fixar versões é um hábito que vale a pena aplicar a todos os projetos recentes que aloja por conta própria. É por isso que o guia sobre executar o openGym como rastreador de treinos alojado por conta própria implementa uma tag git fixa exatamente pelo mesmo motivo.

Faça uma cópia de segurança antes de cada atualização. Depois, atualize de forma intencional.

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

O projeto não relata eventos de perda de dados ao longo de aproximadamente seis meses e com mais de onze mil utilizadores. Ainda assim, recomenda manter cópias de segurança e não apontar a aplicação para uma biblioteca cuja perda seja inaceitável. Leve ambas as recomendações a sério. Copie o arquivo de configuração para fora do servidor, porque uma cópia de segurança armazenada no mesmo disco que os dados protegidos não é uma cópia de segurança. Esse único tarball é suficiente apenas porque Chaptarr mantém o seu estado num único ficheiro SQLite em /config. Qualquer conteúdo armazenado num servidor de base de dados separado também precisa de ser exportado. É essa a estrutura da etapa de cópia de segurança ao alojar o Chatwoot no próprio servidor VPS juntamente com os dados do Postgres e os ficheiros carregados.

Modos de falha e as mensagens apresentadas

O contentor reinicia continuamente. docker compose ps mostra Restarting. Execute ls -ln ./config. Dois zeros nas colunas do proprietário significam que o Docker criou o diretório como root e que o utilizador do contentor não consegue escrever na base de dados. Execute sudo chown -R 1000:1000 ./config.

As importações nunca terminam e os ficheiros permanecem nos downloads. O Chaptarr consegue ler o download, mas não consegue escrever na biblioteca. Compare ls -ln /srv/media/audiobooks com PUID e PGID. Um diretório pertencente a um UID diferente, ou pertencente ao seu grupo sem permissão de escrita para o grupo, impede a transferência. UMASK=002 evita o segundo caso nos ficheiros novos.

A utilização do disco duplica após cada importação. Não foi criada nenhuma hardlink, por isso o ficheiro foi copiado. Execute o teste ln da secção de volumes. Um erro terminado em Invalid cross-device link confirma o problema, e a montagem com um único diretório-pai é a solução.

O cliente de downloads não consegue estabelecer ligação. Introduziu localhost como anfitrião. Dentro do contentor, esse endereço corresponde ao próprio Chaptarr. Use o nome do contentor e confirme que docker network inspect arr apresenta os dois contentores.

O Compose recusa iniciar o serviço. Bind for 127.0.0.1:8789 failed: port is already allocated significa que outro processo está a utilizar a porta. Encontre-o com sudo ss -lntp | grep 8789.

O navegador não mostra nada. Com a porta associada a 127.0.0.1, não há nada a que o portátil possa ligar-se através da Internet. Esse é o comportamento esperado. Abra primeiro o túnel SSH.

FAQ

Posso migrar a minha biblioteca do Readarr para o Chaptarr?

Não como uma importação. O Chaptarr não é compatível com as fontes de metadados do Readarr e usa o seu próprio pipeline de fornecedores. Por isso, os identificadores guardados pelo Readarr não têm significado e não existe conversão da base de dados. Os seus ficheiros no disco não são alterados. Adicione os mesmos caminhos como pastas raiz, execute uma importação da biblioteca e deixe o Chaptarr fazer a correspondência dos ficheiros. Os perfis de qualidade, o formato dos nomes, as definições dos indexadores e quaisquer correspondências incorretas exigem trabalho manual. Por isso, comece por uma pasta pequena antes de importar tudo.

Por que motivo o Chaptarr não consegue escrever na minha pasta de audiolivros?

O utilizador do contentor não é proprietário dos ficheiros. Quando essas variáveis não estão definidas, o Chaptarr usa PUID=99 e PGID=100 por defeito. Esses são os valores do unRAID e estão incorretos num VPS Ubuntu normal. Defina-as para os seus próprios valores id -u e id -g, use o mesmo par no cliente de transferências e defina UMASK=002 para que os ficheiros novos continuem a permitir escrita pelo grupo. Verifique a propriedade com ls -ln no diretório da biblioteca. Esse comando apresenta os números em vez dos nomes, que não pode comparar.

Por que motivo o uso do disco duplicou depois de uma importação?

O Chaptarr copiou o ficheiro porque não conseguiu criar uma hard link. Montar /downloads e /audiobooks como binds separados cria pontos de montagem distintos dentro do contentor. O kernel recusa uma hard link entre pontos de montagem com Invalid cross-device link. Monte um diretório-pai, como /srv/media:/data, e use /data/downloads e /data/audiobooks dentro da aplicação. Ambos os caminhos também têm de estar no mesmo sistema de ficheiros do host. df -h confirma isso.

O Chaptarr reproduz os meus audiolivros?

Não. O Chaptarr localiza, transfere, renomeia e organiza os ficheiros. A reprodução é feita por outro programa. O Audiobookshelf é a combinação mais comum porque guarda a posição entre dispositivos. Para isso, use a imagem oficial ghcr.io/advplyr/audiobookshelf:latest e monte o mesmo caminho dos audiolivros do host. O Jellyfin também reproduz os ficheiros se adicionar a pasta como uma biblioteca, mas oferece uma recuperação de posição menos consistente em audiolivros longos num único ficheiro.

É seguro executar o Chaptarr numa biblioteca que considero importante?

É software beta de uma fork recente, e o próprio projeto afirma isso. Ao mesmo tempo, comunica não ter registado eventos de perda de dados durante cerca de seis meses, com mais de onze mil utilizadores. Os aspetos positivos incluem a licença GPL-3.0, que permite continuar a criar forks do código, e a base .NET 10, um runtime com suporte de longo prazo em agosto de 2026. Fixe uma tag exata da imagem, como 0.9.925, em vez de latest. Faça uma cópia de segurança de /config antes de cada atualização e mantenha esse arquivo fora do servidor.