Come installare Chaptarr su un VPS per audiolibri
Readarr è stato ritirato il 27 giugno 2025: scopri come avviare Chaptarr con Docker Compose, configurare PUID e PGID e correggere il problema dei metadati.
Cos’è Chaptarr e perché gli utenti di Readarr ne hanno bisogno
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 bloccato. Il repository è archiviato. Le raccolte di libri e audiolibri sono quindi rimaste senza un gestore mantenuto, e Chaptarr ha assunto questo ruolo. Mantiene la struttura che già conoscete da Sonarr e Radarr (indexer, client di download, profili di qualità, cartelle root) 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 utilizza il tag dell’immagine chaptarr/chaptarr:0.9.925, che il 9 agosto 2026 era la release più recente. All’11 ottobre 2026 la release più recente è 0.9.965, pubblicata il 27 settembre 2026. I passaggi riportati di seguito sono stati testati solo sulla versione 0.9.925, quindi i file mantengono quel tag; prima di passare a una versione più recente, consultate le note di rilascio. Chaptarr si definisce software beta. Prima di configurarlo su una libreria che non potete sostituire, leggete la sezione sulla manutenzione verso la fine della guida.
Prerequisiti
Una VPS con Docker e il plugin Compose, oltre a spazio su disco sufficiente per la libreria. Gli audiolibri occupano molto spazio. Durante un'importazione che non può usare gli hard link, per un certo periodo vengono mantenute due copie dello stesso file, come spiegato nella sezione sui volumi. Se Docker non è ancora installato sul server, inizia da Docker installato e in esecuzione su una VPS e poi torna qui.
Per ora Chaptarr viene distribuito soltanto come immagine Docker. Il supporto nativo è ancora in fase di sviluppo, è prevista una build sperimentale per Windows e non esiste un pacchetto per le distribuzioni. Per impostazione predefinita, il container salva il database in /config come SQLite. Se ne hai già uno in esecuzione, può usare anche un server PostgreSQL esterno tramite le variabili d'ambiente Chaptarr__Postgres__*. SQLite è la scelta corretta per un singolo utente su un singolo server.
Il servizio Compose per Chaptarr
Questo servizio si inserisce in uno stack esistente. Utilizza un tag rilasciato, 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: trueLa 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 propria e Chaptarr non riesce più a risolvere qbittorrent per nome. Recupera 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 illustrate 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 chaptarrdocker compose ps dovrebbe mostrare il container come Up. Un container indicato come Restarting non è riuscito ad avviarsi e viene riavviato; leggi i log per individuare la causa. 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 PUID=99 e PGID=100 per impostazione predefinita quando non li si valorizza. Questi sono i valori di unRAID e, su una VPS Ubuntu standard, corrispondono a un account senza utilità pratica; di conseguenza, i file vengono creati con un proprietario con cui il proprio account 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. 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 non riesce. Il proprietario del file non è l'elemento determinante: per creare, rinominare o eliminare un file è necessario disporre dell'autorizzazione di scrittura sulla directory che lo contiene. Le directory create dall'utente 1000 con la modalità comune 755 non concedono a 99:100 l'accesso in scrittura; Chaptarr non può quindi inserire il libro nella libreria né rimuoverlo dai download. UMASK=002 abilita la scrittura per il gruppo quando l'applicazione che crea il file la richiede. È l'impostazione necessaria quando più container condividono lo stesso gruppo multimediale. Non aggiunge autorizzazioni: un file richiesto con la modalità 0644 mantiene 0644 e l'ACL predefinita della directory padre ha precedenza rispetto a umask. La mappatura completa è disponibile in come PUID e PGID associano un utente del container ai file dell'host.
Il README consiglia di creare prima la directory di configurazione e di evitare un override Compose user:. Se ./config non esiste quando si esegue docker compose up, Docker la crea automaticamente con proprietario root:root. Nell'immagine 0.9.925 fissata, l'entrypoint viene avviato come root e corregge il proprietario di /config e dei relativi file di database prima di passare all'UID e al GID configurati. Una directory appena creata con proprietario root non causa quindi normalmente un ciclo di riavvio. Un override user: aggira questa procedura. Anche un mount in sola lettura o un filesystem che rifiuta la modifica dei proprietari può impedire la scrittura nel database. Verificare con ls -ln ./config, che mostra i proprietari numerici invece dei nomi. Due zeri indicano che il proprietario è root. Se i log confermano un errore di autorizzazioni su una directory locale scrivibile, correggerlo con sudo chown -R 1000:1000 ./config e avviare di nuovo il container.
Perché separare i volumi degli audiolibri e degli ebook impedisce gli hardlink
Il layout precedente monta /audiobooks, /ebooks e /downloads come bind separati, in linea con il comando di esecuzione del progetto per la release bloccata 0.9.925. È 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 soltanto 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. Verificalo direttamente.
docker exec chaptarr sh -c 'touch /downloads/linktest && ln /downloads/linktest /audiobooks/linktest'Il comando restituisce un errore che termina con Invalid cross-device link. Il kernel rifiuta di creare 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 mentre continui a condividerlo. Dopo il test, elimina /srv/media/downloads/linktest.
Per mantenere gli hardlink, monta invece una directory padre:
volumes:
- ./config:/config
- /srv/media:/dataImposta quindi le cartelle radice in Chaptarr su /data/audiobooks e /data/ebooks. Assegna al client di download lo stesso mount /srv/media:/data, in modo che entrambi i container vedano lo stesso percorso identico. Prima verifica che il lato host appartenga a un unico filesystem: df -h /srv/media/downloads /srv/media/audiobooks deve riportare lo stesso valore nella colonna Filesystem per entrambi i percorsi. Valori diversi indicano dischi diversi. Nessun layout 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-serverLascia 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.
Il problema della migrazione da Readarr: qual è il costo reale
Chaptarr non è compatibile con le sorgenti di metadati di Readarr. Risolve titoli, autori ed edizioni tramite una propria pipeline che usa diversi provider, quindi gli identificativi salvati da Readarr non hanno alcun significato in questo contesto.
Per una libreria esistente, questo significa che i file sono al sicuro, mentre le impostazioni non lo sono. La procedura non modifica nulla di ciò che è già presente sul disco. È sufficiente aggiungere una cartella radice, avviare l'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 degli indexer e dei client, oltre a correggere ogni associazione errata effettuata da Chaptarr. Una libreria di grandi dimensioni richiederà una verifica manuale, quindi considera una serata di lavoro, non dieci minuti.
Procedi in questo ordine. Arresta il container Readarr, ma conserva il relativo volume di configurazione, così potrai ancora consultare le vecchie impostazioni mentre le reinserisci. Configura inizialmente Chaptarr su una sola cartella di piccole dimensioni e verifica le associazioni prima di importare tutto. Rimuovi il vecchio container solo quando il risultato sarà corretto.
Prima di analizzare un'intera libreria, considera un dettaglio relativo alla privacy: le richieste di metadati vengono inviate a api2.chaptarr.com. Il README indica che queste richieste possono contenere gli ID dei provider, il testo della ricerca, il tipo di contenuto, i tag e i nomi dei file, mentre non includono i percorsi completi, l'identità dell'utente né le credenziali. I nomi dei file lasciano il tuo server. È un comportamento normale per un servizio di metadati, ma la decisione deve essere consapevole.
Consegnare gli audiolibri a un player
Chaptarr organizza i file. La riproduzione è compito di un altro programma. Audiobookshelf è il partner più comune perché tiene traccia della posizione di ascolto tra dispositivi diversi e offre app per il telefono. La sua immagine ufficiale è ghcr.io/advplyr/audiobookshelf:latest. 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-stoppedMonta lo stesso percorso dell'host in cui Chaptarr scrive i file, quindi aggiungi /audiobooks come libreria nell'interfaccia web. Il nuovo import compare dopo la scansione successiva.
Se esegui già Jellyfin, puoi aggiungere la cartella come libreria e riprodurre i file. La configurazione di questa parte è descritta in eseguire Jellyfin come media server su un VPS. Per la parte relativa agli ebook, passa /srv/media/ebooks a un'applicazione di lettura. Il compito di Chaptarr termina quando il file ha ricevuto il nome corretto ed è stato archiviato.
Rischio di manutenzione: licenza, runtime e un tag soggetto a rapidi cambiamenti
Chaptarr è distribuito con licenza GPL-3.0 ed è protetto da copyright dei collaboratori di Chaptarr, con alcune parti del team Servarr. Il codice rimane quindi aperto e chiunque può creare un nuovo fork se questo maintainer interrompe lo sviluppo. Il progetto si basa su .NET 10, l'attuale release con supporto a lungo termine del runtime ad agosto 2026. La base rimane 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. La versione 0.9.925 è stata pubblicata il 9 agosto 2026 e prima della release completa successiva sono state pubblicate altre quattro pre-release. Tutte le release fino alla 0.9.958 sono state pubblicate come pre-release; la 0.9.965, del 27 settembre 2026, è la prima contrassegnata come release completa. Fissa un tag esatto. L'uso di latest consente a un docker compose pull non supervisionato di aggiornarti di diverse versioni in una settimana. Inoltre, un fork così giovane può modificare la propria API tra una release e l'altra, invalidando qualsiasi script o dashboard che hai scritto per utilizzarla. Fissare la versione è una buona abitudine da applicare a ogni progetto giovane che ospiti autonomamente. Per questo la procedura per eseguire openGym come tracker di allenamento self-hosted esegue il deployment da un tag Git fisso, esattamente per lo stesso motivo.
Esegui un backup prima di ogni aggiornamento, quindi aggiorna intenzionalmente.
docker compose stop chaptarr
sudo tar czf chaptarr-config-backup.tgz ./config
docker compose start chaptarrdocker compose pull chaptarr
docker compose up -d chaptarrIl README della versione 0.9.925, pubblicata il 9 agosto 2026, indicava l'assenza di eventi di perdita dei dati in circa sei mesi e con più di undicimila utenti. Il README attuale consiglia ancora di conservare i backup e di non collegare il servizio a una libreria la cui perdita sarebbe inaccettabile. Prendi sul serio entrambi gli aspetti. Copia l'archivio di configurazione fuori dal server, perché un backup che si trova sullo stesso disco dei dati che protegge non è un backup. Questo singolo archivio tar contiene lo stato locale dell'applicazione, perché include i database SQLite e la configurazione sotto /config. Qualsiasi dato che si trova su un server database separato deve essere incluso anche in un dump del database. È questo il modello adottato dal passaggio di backup quando esegui il self-hosting di Chatwoot su un VPS insieme ai relativi dati Postgres e ai file caricati.
Modalità di errore e stringhe visualizzate
Il container si riavvia continuamente. docker compose ps mostra Restarting. Consultare prima docker compose logs chaptarr. Un ./config di proprietà di root, da solo, non spiega il riavvio continuo: normalmente l’entrypoint corregge la proprietà prima di avviare l’applicazione. Se i log indicano che la directory dei dati non è scrivibile, verificare la presenza di un override Compose user:, di un mount in sola lettura o di un filesystem che rifiuta le modifiche alla proprietà. Rimuovere l’override per consentire all’entrypoint di completare la configurazione; se una directory locale scrivibile ha una proprietà errata, eseguire sudo chown -R 1000:1000 ./config.
Le importazioni non terminano mai e i file restano nella directory dei download. Chaptarr riesce a leggere il download, ma non può scrivere nella libreria. Confrontare ls -ln /srv/media/audiobooks con PUID e PGID. Una directory appartenente a un UID diverso, oppure appartenente al gruppo dell’utente ma senza permesso di scrittura per il gruppo, impedisce lo spostamento. UMASK=002 abilita la scrittura per il gruppo sui nuovi file e sulle nuove directory quando l’applicazione che li crea lo richiede; non la garantisce e non corregge i permessi esistenti. Controllare il permesso di scrittura per il gruppo e il permesso di attraversamento della directory, oltre a eventuali ACL predefinite.
Lo spazio su 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 principale.
Il client di download non riesce a connettersi. È stato inserito localhost come host. All’interno del container, questo indirizzo 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 già 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 endpoint a cui connettersi attraverso Internet. È il comportamento previsto. Aprire prima il tunnel SSH.
FAQ
Posso migrare la mia libreria Readarr a Chaptarr?
Importa i file come libreria. Chaptarr non è compatibile con le fonti di metadati di Readarr e usa una propria pipeline di provider, quindi gli identificativi salvati da Readarr non hanno alcun significato. 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 identificare i file. I profili di qualità, il formato dei nomi, le impostazioni degli indexer e le eventuali corrispondenze errate richiedono interventi manuali. Inizia quindi con una cartella piccola prima di importare tutto.
Perché Chaptarr non riesce a scrivere nella cartella degli audiolibri?
L'utente del container non dispone dei permessi di scrittura su quella directory, in genere perché il container viene eseguito con un UID diverso da quello del proprietario. 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 VPS Ubuntu standard. Impostale sui tuoi valori id -u e id -g, usa la stessa coppia nel client di download e imposta UMASK=002 per consentire la scrittura al gruppo quando l'applicazione che crea il file la richiede. Controlla la proprietà con ls -ln sulla directory della libreria: stampa i numeri invece dei nomi, permettendoti di confrontarli.
Perché l'utilizzo del disco è raddoppiato dopo un'importazione?
Chaptarr ha copiato il file perché non è riuscito a creare un hard link. Montare /downloads e /audiobooks come bind separati li trasforma in punti di mount distinti all'interno del container. Il kernel rifiuta quindi un hard link tra punti di mount con 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, come conferma df -h.
Chaptarr riproduce i miei audiolibri?
No. Chaptarr individua, scarica, rinomina e archivia i file, mentre la riproduzione è affidata a un programma separato. Audiobookshelf è l'abbinamento più comune perché conserva la posizione di riproduzione tra i dispositivi. Usa l'immagine ufficiale ghcr.io/advplyr/audiobookshelf:latest e monta lo stesso percorso degli audiolibri dell'host. Anche Jellyfin riproduce i file se aggiungi la cartella come libreria.
È sicuro eseguire Chaptarr su una libreria importante?
È un software beta derivato da un fork recente, come dichiara lo stesso progetto. Il README 0.9.925, rilasciato il 9 agosto 2026, riportava nessun evento di perdita di dati in circa sei mesi e oltre undicimila utenti. Gli elementi 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. Blocca una versione esatta dell'immagine, ad esempio 0.9.925, invece di latest, esegui il backup di /config prima di ogni aggiornamento e conserva quell'archivio fuori dal server.