Come installare Chaptarr su un VPS per audiolibri

Che cos'è Chaptarr e perché serve agli utenti di Readarr

Chaptarr è un fork di Readarr che gestisce audiolibri ed ebook da una singola istanza. Monitora le nuove release, le invia al client di download, quindi rinomina i risultati e li archivia nella libreria. Non riproduce alcun contenuto, quindi va abbinato a un player come Audiobookshelf.

Readarr è stato ritirato il 27 giugno 2025. L'avviso del team Servarr indica il motivo: i metadati del progetto erano diventati inutilizzabili e il lavoro della community per passare a Open Library si era arrestato. Il repository è archiviato. Le raccolte di libri e audiolibri sono quindi rimaste senza un gestore mantenuto, e Chaptarr ha preso il posto di Readarr. Mantiene la struttura già nota da Sonarr e Radarr (indexer, client di download, profili di qualità e cartelle radice) e aggiunge la gestione degli audiolibri: organizzazione basata sul narratore, più edizioni dello stesso titolo, supporto per M4B e MP3 suddivisi in capitoli e conversione da MP3 a M4B.

Questa procedura usa il tag dell'immagine chaptarr/chaptarr:0.9.925, che era la release più recente il 9 agosto 2026. Chaptarr si definisce software beta. Leggi la sezione sulla manutenzione verso la fine prima di usarlo con una libreria che non puoi ricreare.

Cosa serve prima di iniziare

Una VPS con Docker e il plugin Compose, oltre a spazio su disco sufficiente per la libreria. Gli audiolibri occupano molto spazio e, quando un’importazione non può usare gli hardlink, per un certo periodo vengono mantenute due copie dello stesso file, come spiegato nella sezione sui volumi. Se Docker non è ancora installato sul server, iniziare da Installare e avviare Docker su una VPS, quindi tornare qui.

Al momento Chaptarr è disponibile solo come immagine Docker. Una build nativa per Windows è indicata come in sviluppo e non esiste un pacchetto per la distribuzione. Per impostazione predefinita, il container memorizza il database in /config come database SQLite. Se è già disponibile un server PostgreSQL esterno, il container può utilizzarlo tramite le variabili d’ambiente Chaptarr__Postgres__*. SQLite è la scelta appropriata per un singolo utente su un singolo server.

Il servizio Compose per Chaptarr

Questo servizio si integra in uno stack esistente. Usa un tag rilasciato fisso, pubblica l’interfaccia Web solo su loopback e si collega alla rete già utilizzata dal client di download.

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

La riga external: true significa «questa rete esiste già, collegati a essa». Usala quando Prowlarr e il client torrent provengono da un progetto Compose diverso, perché altrimenti il secondo file Compose crea una rete isolata e Chaptarr non può risolvere qbittorrent tramite il nome. Ricava il nome effettivo da docker network ls. Se lo stack è già definito in un unico file, aggiungi il servizio chaptarr: a quel file ed elimina invece l’intero blocco networks:. La struttura complessiva è descritta in uno stack arr completo con Docker Compose, mentre le regole di denominazione sono spiegate in come vengono risolti i nomi delle reti e dei servizi Compose.

Crea manualmente la directory di configurazione, quindi avvia il servizio.

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

docker compose ps dovrebbe mostrare il container nello stato Up. Un container indicato come Restarting non è riuscito ad avviarsi e viene riavviato; la causa è quasi sempre la directory di configurazione. Il log smette di scorrere quando l’applicazione è in ascolto sulla porta 8789.

PUID, PGID e la directory che Docker crea come root

Chaptarr usa per impostazione predefinita PUID=99 e PGID=100 quando non li si valorizza. Questi sono i valori di unRAID. Su una VPS Ubuntu standard corrispondono invece a un account non utilizzabile. Di conseguenza, i file vengono creati con un proprietario con cui l'utente di accesso non può scrivere. Leggere i propri valori con id -u e id -g e inserirli nel file.

Ogni container che accede agli stessi file deve usare la stessa coppia di valori. Il client di download scrive in /srv/media/downloads, Chaptarr sposta il file in /srv/media/audiobooks e il player lo legge da lì. Se il client di download scrive come 1000:1000 e Chaptarr viene eseguito come 99:100, l'importazione fallisce perché Chaptarr non può eliminare o spostare un file di cui non è proprietario. UMASK=002 rende scrivibili dal gruppo i nuovi file. È il comportamento corretto quando più container condividono lo stesso gruppo per i file multimediali. La mappatura completa è disponibile in come PUID e PGID associano l'utente di un container ai file dell'host.

Il README segnala un problema specifico, che è utile ribadire. Se ./config non esiste quando si esegue docker compose up, Docker la crea automaticamente con proprietario root:root. Il container viene quindi eseguito con UID 1000 e non può scrivere il proprio database. Di conseguenza, termina e si riavvia continuamente. Verificare con ls -ln ./config, che visualizza gli ID numerici dei proprietari invece dei nomi. Due zeri indicano che il proprietario è root. Correggere il problema con sudo chown -R 1000:1000 ./config e avviare di nuovo il container.

Perché separare i volumi per audiolibri ed ebook impedisce gli hardlink

La configurazione precedente monta /audiobooks, /ebooks e /downloads come bind separati, in linea con il comando di esecuzione del progetto. È semplice da leggere, ma comporta un costo concreto: gli hardlink smettono di funzionare.

Un hardlink è un secondo nome per gli stessi dati sul disco. Non usa spazio aggiuntivo ed è istantaneo; per questo la famiglia arr lo preferisce alla copia. Un hardlink funziona solo all'interno di un filesystem. Nel container questi sono tre punti di mount distinti, quindi il kernel rifiuta il collegamento anche quando i percorsi sull'host si trovano sullo stesso disco. Esegui il test:

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

Il comando non riesce e termina con un errore che contiene Invalid cross-device link. Il kernel rifiuta il collegamento tra punti di mount diversi. Questo è il motivo esatto per cui Chaptarr passa alla copia del file. La copia è corretta, ma più lenta. Inoltre, l'audiolibro esiste in due copie finché non rimuovi il torrent, cosa che non farai finché continui a eseguirne il seeding. Elimina /srv/media/downloads/linktest al termine.

Per mantenere gli hardlink, monta invece una directory padre:

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

Imposta quindi le cartelle radice in Chaptarr su /data/audiobooks e /data/ebooks e assegna al client di download lo stesso mount /srv/media:/data, in modo che entrambi i container vedano lo stesso percorso. Verifica prima che sul lato host sia presente un unico filesystem: df -h /srv/media/downloads /srv/media/audiobooks deve stampare lo stesso valore nella colonna Filesystem per entrambi i percorsi. Valori diversi indicano dischi diversi e nessuna configurazione dei mount può creare hardlink tra filesystem distinti. Il compromesso tra questa soluzione e lo storage denominato è illustrato in bind mount rispetto ai volumi denominati per i contenuti multimediali.

Accesso all’interfaccia web senza esporla

La riga della porta pubblica su 127.0.0.1 per un motivo preciso. ufw deny 8789 non protegge una porta Docker pubblicata, perché Docker scrive le proprie regole NAT (network address translation) in una catena che il kernel raggiunge prima di quella di ufw. Di conseguenza, il traffico viene inoltrato prima ancora che la regola venga consultata. Questo comportamento causa spesso problemi ed è spiegato in perché una porta Docker pubblicata ignora le regole di ufw. Il binding all’interfaccia di loopback evita completamente il problema.

Accedi all’interfaccia tramite un tunnel SSH dal tuo computer:

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

Lascia il tunnel attivo e apri http://127.0.0.1:8789 nel browser. Configura l’autenticazione al primo avvio. Solo in seguito valuta l’uso di un reverse proxy con TLS (transport layer security) davanti all’applicazione. Quando accedi tramite tunnel a tre o quattro strumenti di questo tipo, ciascuno con una password diversa, la soluzione più ordinata è collocare il proxy dietro un server single sign-on self-hosted come Authentik, così un unico accesso copre tutte le applicazioni e un’unica revoca le disabilita tutte.

Collega gli indexer e il client di download

Chaptarr supporta i protocolli standard degli indexer e dei client di download della famiglia arr. Prowlarr vi trasferisce quindi gli indexer nello stesso modo in cui li trasferisce a Sonarr. I normali client torrent e Usenet si collegano senza configurazioni speciali.

Un'impostazione causa problemi a quasi tutti. Quando Chaptarr richiede l'host del client di download, non inserire localhost o 127.0.0.1. All'interno di un container, quell'indirizzo identifica il container stesso. Chaptarr tenta quindi di collegarsi alla propria porta 8080 e segnala che la connessione non è riuscita. Usa il nome del container, qbittorrent, con la porta 8080. Verifica con docker network inspect arr che entrambi i container siano collegati alla stessa rete. Il comando elenca tutti i container collegati, usando il relativo nome.

Se il client di download viene eseguito tramite un container VPN con network_mode: "service:gluetun", non dispone di un proprio nome nella rete, perché condivide il network namespace di Gluetun. Indirizzalo a gluetun sulla porta esposta da Gluetun. Questa configurazione e il relativo instradamento sono descritti in instradare un client di download tramite Gluetun.

La rottura con Readarr: il costo reale di una migrazione

Chaptarr non è compatibile con le fonti di metadati di Readarr. Risolve titoli, autori ed edizioni tramite una propria pipeline che utilizza diversi provider, quindi gli identificativi salvati da Readarr non hanno alcun significato in questo contesto. Non è disponibile alcuna importazione del database né un percorso di aggiornamento diretto.

Per una libreria esistente, questo significa che i file sono al sicuro, mentre le impostazioni non lo sono. Questa procedura non modifica nulla di ciò che è già presente sul disco. Devi aggiungere una cartella radice, eseguire un'importazione della libreria e lasciare che Chaptarr associ i file trovati ai propri metadati. Dovrai ricreare manualmente i profili di qualità, il formato dei nomi, le impostazioni di indexer e client, oltre a correggere ogni associazione errata effettuata da Chaptarr. Una libreria grande richiederà una verifica manuale, quindi considera un'intera serata, non dieci minuti.

Procedi in questo ordine. Arresta il container di Readarr, ma conserva il relativo volume di configurazione, così potrai ancora leggere le vecchie impostazioni mentre le reinserisci. Configura prima Chaptarr su una cartella piccola e controlla le associazioni prima di importare tutto. Rimuovi il vecchio container solo quando il risultato è corretto.

Prima di analizzare un'intera libreria, considera un aspetto della privacy: le richieste dei metadati vengono inviate a api2.chaptarr.com. Il README specifica che queste richieste possono contenere gli ID dei provider, il testo della ricerca, il tipo di contenuto, i tag e i nomi dei file, ma escludono i percorsi completi, l'identità dell'utente e le credenziali. I nomi dei file lasciano il tuo server. È un comportamento normale per un servizio di metadati, ma devi decidere consapevolmente se accettarlo.

Consegna gli audiolibri a un lettore

Chaptarr organizza i file. La riproduzione spetta a un altro programma. Audiobookshelf è il partner più usato perché tiene traccia della posizione di ascolto tra dispositivi diversi e offre app per smartphone. La sua immagine ufficiale è ghcr.io/advplyr/audiobookshelf:latest e l'esempio Compose documentato pubblica la porta 13378 dell'host sulla porta 80 del container.

  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

Monta lo stesso percorso dell'host in cui Chaptarr scrive i file, quindi aggiungi /audiobooks come libreria nell'interfaccia web. Il nuovo import viene visualizzato dopo la scansione successiva.

Se usi già Jellyfin, puoi aggiungere la directory come libreria e riprodurre i file anche da lì. Tuttavia, la ripresa della riproduzione di un singolo file contenente un audiolibro lungo è meno affidabile rispetto a un server progettato specificamente per gli audiolibri. La configurazione di questo componente è descritta in eseguire Jellyfin come server multimediale su un VPS. Per la parte relativa agli ebook, consegna /srv/media/ebooks a un'applicazione di lettura. Il compito di Chaptarr termina quando il file ha il nome corretto ed è stato archiviato nella directory appropriata.

Rischio di manutenzione: licenza, runtime e un tag soggetto a rapidi cambiamenti

Chaptarr è distribuito con licenza GPL-3.0. Il copyright appartiene ai contributori di Chaptarr, con parti provenienti dal team Servarr. Il codice resta quindi aperto e chiunque può creare un nuovo fork se questo maintainer interrompe il progetto. Chaptarr si basa su .NET 10, l'attuale release Long Term Support del runtime ad agosto 2026. La base software è quindi supportata per anni, non per mesi. Entrambi gli aspetti sono importanti per valutare se il progetto esisterà ancora il prossimo anno.

I numeri di versione cambiano rapidamente. Le release vengono pubblicate come pre-release e la versione 0.9.925 è stata pubblicata lo stesso giorno di questa guida. Blocca una versione precisa tramite un tag esatto. Usare latest significa che un docker compose pull non presidiato può portarti avanti di diverse versioni in una settimana. Inoltre, un fork così recente può modificare la propria API tra una release e l'altra. Questo può rendere inutilizzabile qualsiasi script o dashboard sviluppato per quella API.

Esegui un backup prima di ogni upgrade, quindi procedi con l'upgrade in modo intenzionale.

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

Il progetto non segnala eventi di perdita di dati da circa sei mesi e con oltre undicimila utenti, ma raccomanda comunque di mantenere i backup e di non configurarlo su una libreria di cui non si può accettare la perdita. È necessario considerare seriamente entrambe le indicazioni. Copiate l'archivio di configurazione fuori dal server: un backup memorizzato sullo stesso disco dei dati che protegge non è un backup. Quel singolo archivio tar è sufficiente solo perché Chaptarr conserva il proprio stato in un unico file SQLite sotto /config; qualsiasi dato che risiede su un server database separato richiede anche un dump del database. È questo il modello adottato dal passaggio di backup per eseguire Chatwoot in self-hosting su un VPS insieme ai relativi dati Postgres e ai file caricati.

Modalità di errore e messaggi visualizzati

Il container si riavvia continuamente. docker compose ps mostra Restarting. Eseguire ls -ln ./config. Due zeri nelle colonne relative al proprietario indicano che Docker ha creato la directory come root e che l'utente del container non può scrivere nel database. Eseguire sudo chown -R 1000:1000 ./config.

Le importazioni non terminano mai e i file restano nella directory dei download. Chaptarr può leggere i file scaricati, ma non può scrivere nella libreria. Confrontare ls -ln /srv/media/audiobooks con PUID e PGID. Una directory appartenente a un UID diverso, oppure al proprio gruppo senza permesso di scrittura per il gruppo, impedisce lo spostamento. UMASK=002 evita il secondo caso per i nuovi file.

L'utilizzo del disco raddoppia dopo ogni importazione. Non è stato creato alcun hardlink, quindi il file è stato copiato. Eseguire il test ln dalla sezione sui volumi. Un errore che termina con Invalid cross-device link lo conferma; la soluzione consiste nell'usare un unico mount padre.

Il client di download non si connette. È stato inserito localhost come host. All'interno del container corrisponde a Chaptarr stesso. Usare il nome del container e verificare che docker network inspect arr elenchi entrambi i container.

Compose rifiuta di avviare il servizio. Bind for 127.0.0.1:8789 failed: port is already allocated indica che un altro processo sta usando la porta. Individuarlo con sudo ss -lntp | grep 8789.

Il browser non mostra nulla. Se la porta è associata a 127.0.0.1, il laptop non ha alcun servizio a cui connettersi tramite Internet. Questo comportamento è previsto. Aprire prima il tunnel SSH.

FAQ

Posso migrare la mia libreria Readarr a Chaptarr?

Non come importazione. Chaptarr non è compatibile con le origini dei metadati di Readarr e usa una propria pipeline di provider. Gli identificativi salvati da Readarr non hanno quindi alcun significato e non esiste una conversione del database. I file sul disco non vengono modificati. Aggiungi gli stessi percorsi come cartelle radice, esegui un'importazione della libreria e lascia che sia Chaptarr a trovare autonomamente le corrispondenze. I profili di qualità, il formato dei nomi, le impostazioni degli indexer e le eventuali corrispondenze errate richiedono interventi manuali. Prima di importare tutto, inizia quindi con una cartella di piccole dimensioni.

Perché Chaptarr non riesce a scrivere nella cartella degli audiolibri?

L'utente del container non è il proprietario dei file. Quando queste variabili non sono impostate, Chaptarr usa PUID=99 e PGID=100 come valori predefiniti. Sono i valori di unRAID e non sono corretti su un normale VPS Ubuntu. Impostale sui tuoi valori id -u e id -g, usa la stessa coppia anche nel client di download e imposta UMASK=002, in modo che i nuovi file restino scrivibili dal gruppo. Controlla il proprietario con ls -ln sulla directory della libreria. Il comando stampa i numeri invece dei nomi, quindi non puoi confrontarli direttamente.

Perché lo spazio utilizzato sul disco è raddoppiato dopo un'importazione?

Chaptarr ha copiato il file perché non ha potuto creare un hard link. Il montaggio di /downloads e /audiobooks come bind separati li rende punti di montaggio distinti all'interno del container. Il kernel rifiuta quindi un hard link tra punti di montaggio e restituisce Invalid cross-device link. Monta una directory padre, ad esempio /srv/media:/data, e usa /data/downloads e /data/audiobooks all'interno dell'applicazione. Entrambi i percorsi devono inoltre trovarsi sullo stesso filesystem dell'host. df -h lo conferma.

Chaptarr riproduce i miei audiolibri?

No. Chaptarr li individua, scarica, rinomina e organizza. La riproduzione è affidata a un programma separato. Audiobookshelf è l'abbinamento più comune perché conserva la posizione di ascolto tra dispositivi. Usa l'immagine ufficiale ghcr.io/advplyr/audiobookshelf:latest e monta lo stesso percorso degli audiolibri dell'host. Anche Jellyfin può riprodurre i file se aggiungi la cartella come libreria, ma la ripresa della riproduzione è meno affidabile per gli audiolibri lunghi costituiti da un singolo file.

È sicuro eseguire Chaptarr su una libreria importante?

È un software beta derivato da un progetto giovane. Il progetto lo dichiara esplicitamente e segnala di non aver registrato perdite di dati in circa sei mesi, con oltre undicimila utenti. Gli aspetti più rassicuranti sono la licenza GPL-3.0, che consente di creare fork del codice, e la base .NET 10, un runtime con supporto a lungo termine ad agosto 2026. Specifica un tag esatto dell'immagine, ad esempio 0.9.925, invece di latest. Esegui il backup di /config prima di ogni aggiornamento e conserva l'archivio fuori dal server.