Questo tutorial di dicembre 2025 è una delle guide della community più dettagliate per Paperless-ngx su ZimaOS, ma è legato a uno specifico pacchetto BigBear e a ZimaOS 1.5.3 Plus. Gli aspetti più duraturi sono i concetti di archiviazione e configurazione: assegna alla cartella di acquisizione una posizione persistente chiara, imposta correttamente l'URL dell'applicazione, configura le lingue OCR e comprendi i servizi opzionali Tika/Gotenberg.
Alcuni dettagli dell'origine richiedono un aggiornamento. La configurazione Docker upstream di Paperless-ngx si è evoluta, PostgreSQL è ora consigliato per le nuove installazioni, i file Compose attuali richiedono la configurazione di un superutente durante la prima configurazione e Tika/Gotenberg restano opzionali anziché obbligatori per ogni flusso di lavoro documentale.
Il tutorial originale è stato testato su uno ZimaBoard 2 dalle risorse moderate
L'autore ha documentato un sistema basato su N150 con 16 GB di RAM e ZimaOS 1.5.3 Plus. L'obiettivo era l'accesso dalla rete locale o tramite Tailscale per uso domestico, non l'esposizione diretta su Internet.
Questo ambito è importante perché una distribuzione su Internet pubblico richiede un piano diverso per HTTPS, proxy inverso, autenticazione e sicurezza.
La guida ha utilizzato l'installazione personalizzata di BigBear Paperless-ngx
Il flusso di lavoro di origine ha cercato il pacchetto BigBear Paperless-ngx nell'App Store, ha aperto il menu a discesa dell'installazione e ha scelto Installazione personalizzata per poter modificare volumi e valori dell'ambiente prima del primo avvio.
Si tratta di un flusso di lavoro specifico del pacchetto. Una definizione dell'app attuale può aggiungere, rimuovere o rinominare servizi e variabili.
Assegna alla directory di acquisizione un percorso host persistente e chiaro
/usr/src/paperless/consume come cartella con cui è più probabile che gli utenti interagiscano quando vi inseriscono i documenti.La documentazione upstream attuale di Paperless utilizza ancora /usr/src/paperless/consume come destinazione standard del container e supporta esplicitamente la modifica del lato host di questo bind mount.
Il tutorial ha configurato le variabili di amministratore, acquisizione, OCR e URL
Le principali scelte relative all'origine includevano:
- nome utente/password amministratore personalizzati;
- acquisizione ricorsiva dei documenti;
- eliminazione degli originali dalla cartella di acquisizione dopo l'importazione riuscita;
- Pulizia OCR e impostazioni della lingua;
- Origine attendibile per CSRF e URL dell'applicazione;
- Endpoint Tika/Gotenberg.
PAPERLESS_URL e le origini CSRF devono corrispondere al modo in cui accedi effettivamente a Paperless
Il tutorial avvertiva che una configurazione errata dell'URL/origine poteva causare un errore di verifica CSRF 403. Questo rimane concettualmente corretto.
La documentazione attuale di Paperless indica PAPERLESS_URL deve essere impostato quando l'applicazione si trova dietro un reverse proxy e deve rappresentare il dominio/l'URL utilizzato esternamente. Non inserire direttamente l'indirizzo LAN dell'autore della fonte in un'altra installazione.
Anche le impostazioni OCR sono state modificate all'interno di Paperless
Le lingue OCR devono corrispondere ai pacchetti linguistici disponibili nel container. L'aggiunta di lingue può aumentare le dimensioni dell'immagine o modificare i requisiti dei container rootless, a seconda del pacchetto attuale.
Riavviare dopo ogni grande batch nella directory Consume è un consiglio della fonte, non un requisito upstream
L'attuale Paperless-ngx è progettato per monitorare continuamente la directory Consume. La documentazione upstream non afferma che i grandi batch richiedano normalmente un riavvio. Se l'elaborazione dei documenti si interrompe, controlla invece i permessi, i log del consumer, il supporto alle notifiche del filesystem e lo stato del broker/worker, anziché rendere il riavvio una procedura obbligatoria.
La configurazione upstream attuale consiglia PostgreSQL per le nuove installazioni
La configurazione Docker attuale di Paperless-ngx consiglia PostgreSQL per le nuove installazioni, sebbene SQLite e MariaDB rimangano disponibili nelle configurazioni supportate.
Per un archivio documentale a lungo termine, questo rende la topologia Compose upstream attuale un riferimento migliore rispetto all'ipotesi che l'esatto servizio database di BigBear 2025 sia rimasto invariato.
Tika e Gotenberg sono opzionali
La documentazione attuale di Paperless indica che Tika e Gotenberg sono necessari per analizzare documenti Office come DOC/XLSX/ODT e file email. Se acquisisci solo formati gestiti dallo stack Paperless di base, questa funzionalità può rimanere disabilitata.
Usa la configurazione Docker attuale di Paperless-ngx prima di ricreare manualmente lo stack storico di BigBear.
I permessi della cartella Consume sono più importanti dei riavvii ripetuti
La configurazione upstream attuale espone USERMAP_UID e USERMAP_GID in modo che il container possa scrivere nei bind mount dell'host. Se Paperless rileva una cartella consume ma non riesce a elaborare o eliminare i file, verifica la proprietà della directory mappata e l'identità del container.
Su ZimaOS, verifica anche che il percorso consume dell'host si trovi nello spazio di archiviazione gestito previsto e non in una mappatura di volume in sola lettura.
Eliminare gli originali da /consume non equivale a eliminare i documenti archiviati
La fonte ha abilitato PAPERLESS_CONSUMER_DELETE_ORIGINALS=true. Questo controlla cosa accade al file di input nella directory consume dopo l'acquisizione riuscita. Il documento archiviato gestito da Paperless rimane nel relativo spazio di archiviazione multimediale.
Testa questo comportamento con documenti usa e getta prima di collegare uno scanner automatizzato o un servizio di sincronizzazione a una cartella di produzione.
Le risposte su Paperless-AI appartengono a un'integrazione separata
Le risposte successive hanno discusso di Paperless-AI che legge i documenti tramite l'API di Paperless, ma non riesce ad analizzare o scrivere i tag usando la configurazione OpenAI integrata. Gli utenti hanno riferito che Mistral funzionava e che la configurazione manuale di OpenAI consentiva di aggirare il problema.
Queste risposte non dimostrano che l'installazione principale di Paperless-ngx sia guasta. Paperless-AI è un'integrazione separata di terze parti, con una propria configurazione del provider e dell'API.
Gli errori 500 successivi e le domande sulle password non sono stati risolti nella conversazione
Un utente ha segnalato un errore HTTP 500 durante il caricamento nel febbraio 2026, mentre un altro utente non è riuscito a far funzionare le password previste nel maggio 2026. La conversazione pubblica non contiene diagnosi definitive per questi casi.
Non trasformare le credenziali di esempio del tutorial originale in una procedura universale di accesso per le versioni successive di BigBear.
Esporta i dati di Paperless prima di apportare modifiche importanti ai pacchetti
L'attuale versione di Paperless fornisce un esportatore di documenti che include documenti, miniature, metadati e informazioni derivate dal database per i flussi di migrazione e backup. Prima di sostituire il database o lo stack Compose, usa l'esportazione compatibile con l'applicazione insieme ai normali backup dello spazio di archiviazione.
FAQ su Paperless-ngx in ZimaOS
Tika è obbligatorio per ogni installazione di Paperless-ngx?
No. È facoltativo e serve principalmente per i documenti Office e l'analisi delle email.
I grandi batch di elaborazione richiedono normalmente un riavvio?
L'autore della fonte lo ha consigliato in base alla propria esperienza, ma la documentazione upstream attuale non indica il riavvio come requisito normale.
Quale database consiglia attualmente Paperless per le nuove installazioni?
PostgreSQL è il backend consigliato per le nuove distribuzioni Docker.
Paperless-AI fa parte di Paperless-ngx?
No. È un'integrazione separata di terze parti discussa più avanti nella conversazione.
