L’installazione originale di Paperless-ngx dal catalogo app di ZimaOS è fallita nelle fasi finali del processo: inizialmente con un errore di autorizzazione durante il recupero di un’immagine Tika dal GitHub Container Registry e successivamente con un errore DNS relativo a un mirror del registro. Questa combinazione rende la discussione più complessa del semplice “Paperless non funziona”: il componente che falliva era un servizio/percorso immagine Tika opzionale e l’endpoint del registro è cambiato tra i tentativi.
La discussione pubblica non è mai arrivata a una soluzione confermata per il catalogo app di ZimaOS. Un utente ha sostituito l’immagine Tika con quella di Apache e ha portato l’installazione al 100%, ma lo stack continuava a non funzionare. L’attuale documentazione di Paperless-ngx offre un percorso più chiaro: usare i modelli Docker Compose mantenuti e abilitare la variante Tika/Gotenberg solo quando questi formati di documenti sono necessari.
Il primo errore era un problema di autorizzazione GHCR
L’errore originale si è verificato intorno all’80%:
Head "https://ghcr.io/v2/paperless-ngx/tika/manifests/2.9.1-minimal": unauthorizedL’eliminazione delle immagini Docker locali e la reinstallazione non hanno modificato il risultato, il che esclude un semplice problema dovuto a un’immagine locale obsoleta.
Il tentativo successivo è fallito durante la risoluzione DNS
Due giorni dopo, l’errore è cambiato in una ricerca DNS non riuscita per il nome host di un mirror del registro. Un membro della comunità ha quindi suggerito di verificare la risoluzione dei nomi, la connettività HTTPS di base, il filtraggio DNS, il comportamento di VPN/proxy e il recupero manuale dell’immagine.
Si trattava di verifiche suggerite dalla comunità, non di una causa principale confermata da IceWhale.
Nelle versioni attuali di Paperless-ngx Tika è facoltativo
L’attuale documentazione di Paperless-ngx indica che Tika e Gotenberg sono servizi facoltativi, utilizzati per documenti Office come DOC/XLSX/ODT e per l’analisi delle email. Se questi formati non sono necessari, non occorre abilitare Tika.
Se invece sono necessari, usa la variante Compose mantenuta che include Tika e Gotenberg, anziché un vecchio riferimento a un’immagine del catalogo app.
L’attuale Docker Compose upstream è il punto di riferimento migliore
L’attuale guida alla configurazione di Paperless-ngx consiglia Docker per la maggior parte degli utenti e fornisce file Compose mantenuti. Per le nuove installazioni si consiglia PostgreSQL, mentre i modelli con Tika sono forniti separatamente.
Usa l’attuale modello di installazione Docker Compose di Paperless-ngx se il pacchetto del catalogo app di ZimaOS è obsoleto o fa riferimento a un’immagine ausiliaria non disponibile.
Cambiare solo l’immagine Tika potrebbe non bastare
Un partecipante ha sostituito l’immagine Tika con apache/tika:latest. L’installazione ha raggiunto il 100%, ma l’applicazione ha continuato a non funzionare dopo l’avvio.
Questo risultato negativo è significativo perché Paperless richiede che l’endpoint del servizio, il flag della funzionalità e l’integrazione con Gotenberg siano coerenti con la configurazione Compose. La sostituzione dell’immagine di un container non equivale necessariamente alla migrazione completa dello stack.
Archivia i dati persistenti di Paperless nello spazio di archiviazione principale
Paperless può crescere a causa dei documenti acquisiti, delle miniature, dei dati OCR, degli indici di ricerca e del database. L’attuale documentazione di ZimaOS consiglia di spostare i dati delle app fuori dall’unità di sistema prima di installare applicazioni che richiedono molto spazio.
Il modello attuale dei percorsi di archiviazione delle app di ZimaOS è particolarmente rilevante per Paperless, perché l’ingombro dei suoi dati può crescere molto oltre le dimensioni dell’immagine Docker.
I permessi sono importanti per la cartella di acquisizione
L’attuale documentazione di Paperless-ngx espone USERMAP_UID e USERMAP_GID, così il container può scrivere nelle cartelle montate dal sistema host. Se lo stack viene installato ma non riesce ad acquisire i documenti, verifica questi valori e i permessi delle cartelle host invece di tornare a occuparsi dei problemi del registro.
Non considerare il nome host di un mirror del registro come se fosse l’applicazione Paperless
Il secondo errore originale faceva riferimento a un nome host simile a quello di un mirror, anziché all’endpoint principale ghcr.io. La distinzione è importante: un pacchetto applicativo può essere perfettamente valido mentre il mirror configurato dell’immagine, il server DNS o il percorso regionale del registro non sono disponibili.
Se il recupero manuale dal registro upstream riesce ma il catalogo app continua a usare un mirror non funzionante, il problema riguarda il pacchetto o il livello di instradamento del registro, non Paperless in sé.
Distingui il fallimento del recupero dell’immagine dal fallimento dell’avvio del container
Il primo tentativo originale non ha mai completato il recupero di tutte le immagini necessarie. Il successivo esperimento con Apache Tika ha raggiunto il 100% dell’installazione, ma poi è fallito durante l’avvio. Si tratta di due fasi di errore diverse, che richiedono prove differenti.
- Fase di recupero: autenticazione al registro, DNS, disponibilità del mirror, tag dell’immagine.
- Fase di avvio: variabili d’ambiente, connettività al database, endpoint Tika/Gotenberg, volumi, permessi e controlli di integrità.
Esegui il backup di un’istanza funzionante di Paperless prima di sostituire lo stack del catalogo app
Se Paperless è già in uso, non cambiare i modelli Compose solo per risolvere un servizio ausiliario senza prima proteggere i documenti e il database. L’attuale Paperless upstream include un esportatore specifico per il backup e la migrazione.
Per una nuova installazione, partire dal file Compose upstream mantenuto è più semplice; per un’installazione esistente, conserva i percorsi attuali del database e dei file multimediali prima di riscrivere lo stack.
Domande frequenti sull’installazione di Paperless-ngx
Il problema del 2025 era definitivamente dovuto al DNS?
No. La discussione mostrava sia errori di autorizzazione sia errori DNS e non è stata pubblicata alcuna diagnosi finale ufficiale.
Tika è necessaria per ogni installazione di Paperless-ngx?
No. È facoltativa ed è necessaria soprattutto per i documenti Office e l’analisi delle email.
Il passaggio ad apache/tika ha risolto completamente il caso originale?
No. Un utente ha raggiunto il 100% dell’installazione, ma l’applicazione continuava a non funzionare.
