Paperless-ngx su VPS: installazione e configurazione
Installa Paperless-ngx su un VPS con Docker Compose: stack Postgres ufficiale, PAPERLESS_URL, cartella consume, lingue OCR, HTTPS e backup.
Cosa stai costruendo
Paperless-ngx su un VPS trasforma una cartella di documenti cartacei acquisiti in un archivio consultabile. Inserisci un PDF in una directory monitorata; il server esegue l'OCR (riconoscimento ottico dei caratteri), estrae il testo, prova a identificare una data e un corrispondente, quindi archivia il documento. L'installazione consiste in un unico file Docker Compose con quattro servizi. Da quel momento in poi si tratta di configurazione, e questa guida dedica la maggior parte dello spazio proprio a questo aspetto, perché è qui che le installazioni si interrompono. Non è una libreria fotografica: l'OCR e l'identificazione dei corrispondenti non servono a nulla con una cartella di JPEG delle vacanze, quindi inseriscili in un server fotografico progettato per questo scopo e usa Paperless per i documenti. Lo stesso vale per i video: una raccolta di film rippati appartiene a un media server, dove un'interfaccia come un front end Jellyfin configurato come un videonoleggio degli anni 90 fa della navigazione l'obiettivo principale, invece della ricerca.
Paperless-ngx è il fork della community, mantenuto attivamente, del progetto Paperless originale. È gratuito, self-hosted e memorizza i documenti come file normali sul disco, quindi non perdi mai l'accesso al tuo archivio. Eseguirlo su un VPS invece che su un computer di casa rende le scansioni accessibili da qualsiasi luogo senza aprire una porta sul router domestico, e si abbina bene a un'istanza privata di Nextcloud per i file che non sono documenti cartacei. Lo stesso principio vale per il computer a cui è collegato lo scanner, perché un relay RustDesk gestito da te su quel VPS consente di controllare quel computer da un'altra posizione senza dover aprire porte sul router.
Cosa esegue realmente lo stack
Il file Compose ufficiale avvia quattro container. Sapere a cosa serve ciascuno rende i log più leggibili.
webserver: l’immagine di paperless-ngx. Esegue l’interfaccia web, l’API, il consumer che monitora la cartella di input e i worker Celery che eseguono l’OCR.db: PostgreSQL. Contiene metadati, tag, corrispondenti e le tabelle dell’indice per la ricerca full-text. Non contiene i file PDF.broker: Valkey, un archivio chiave-valore compatibile con Redis. Funge da coda delle attività tra il processo web e i worker.gotenbergetika: opzionali, solo nelle varianti Compose-tika. Convertono i documenti Office (.docx,.xlsx,.odt) in PDF, in modo che paperless possa indicizzarli.
A ottobre 2026, il file Compose per postgres blocca le versioni docker.io/library/postgres:18 e docker.io/valkey/valkey:9-alpine e scarica l’applicazione da ghcr.io/paperless-ngx/paperless-ngx:latest.
Prerequisiti
- Un VPS KVM Ubuntu 24.04 con accesso sudo e Docker con il plugin Compose già installato. Se questa parte è nuova, inizia dalle nozioni fondamentali su Docker Compose per un VPS e poi torna qui.
- Un nome di dominio con un record A che punta al VPS. Paperless non accetta l'accesso tramite HTTPS su un hostname che non è stato configurato, quindi questo requisito è più importante di quanto possa sembrare.
- La memoria è il vincolo principale. PostgreSQL, Valkey, il server web Granian e un worker Tesseract OCR residenti contemporaneamente richiedono 2 GB per un utilizzo leggero. Assegna 4 GB se prevedi di importare un arretrato di centinaia di scansioni, perché l'OCR di un PDF multipagina di grandi dimensioni causa il picco di memoria che può far terminare un worker per intervento dell'oom killer del kernel.
- Disco: l'archivio viene memorizzato due volte, come file originale e come PDF di archivio elaborato con OCR; prevedi quindi uno spazio circa doppio rispetto alle dimensioni delle scansioni.
Recuperare i file Compose ufficiali
È disponibile un programma di installazione interattivo:
bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"Pone alcune domande e scrive i file al posto tuo. Eseguire manualmente la procedura richiede quattro comandi e ti permette di sapere dove si trova ogni elemento. È la scelta corretta per un server che dovrai gestire nel tempo.
mkdir -p ~/paperless && cd ~/paperless
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
curl -fsSL -o docker-compose.env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
curl -fsSL -o .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.envLe varianti si trovano nella stessa directory: docker-compose.sqlite.yml, docker-compose.mariadb.yml e una versione -tika di ciascuna. Per una nuova installazione scegli postgres. SQLite è sufficiente per alcune centinaia di documenti, ma l'indice per la ricerca full-text rallenta molto prima di PostgreSQL.
Il file .env contiene una riga, COMPOSE_PROJECT_NAME=paperless. Questo nome diventa il prefisso di ogni container e volume. Non eliminarlo per poi chiederti perché docker compose down -v non riesce più a trovare i tuoi dati.
Configura docker-compose.env prima del primo avvio
Due impostazioni sono obbligatorie. Genera la chiave segreta con il comando documentato dal progetto:
python3 -c "import secrets; print(secrets.token_urlsafe(64))"Quindi modifica docker-compose.env:
PAPERLESS_SECRET_KEY=<the long string you just generated>
PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu+eng
USERMAP_UID=1000
USERMAP_GID=1000PAPERLESS_SECRET_KEY viene fornito con il valore letterale change-me. Firma i token di sessione e le versioni attuali considerano quel segnaposto come non impostato: paperless rifiuta di avviarsi se la chiave manca, è vuota o contiene ancora change-me. Pertanto lo stack non si avvierà finché non lo sostituisci. Impostalo prima del primo avvio, perché modificarlo in seguito disconnette tutti gli utenti.
PAPERLESS_URL è l’impostazione che evita un’ora di troubleshooting. Paperless è un’applicazione Django e Django verifica sia l’header Host sia, nei moduli di accesso, l’origine indicata dal browser. Imposta PAPERLESS_URL: il sistema aggiungerà il tuo indirizzo a ALLOWED_HOSTS, CORS_ALLOWED_HOSTS e CSRF_TRUSTED_ORIGINS. Se lo lasci vuoto e punti un dominio al server, la pagina di accesso viene comunque caricata, perché PAPERLESS_ALLOWED_HOSTS assume per impostazione predefinita il valore *. Tuttavia, l’invio del modulo tramite HTTPS fallisce con CSRF verification failed. Request aborted. perché il dominio non è un’origine attendibile. Scrivilo senza slash finale e senza percorso.
USERMAP_UID e USERMAP_GID impostano l’utente con cui viene eseguito il container. Impostali in modo che corrispondano al tuo account, verificandoli con id -u e id -g. Se non corrispondono, i file copiati nella cartella consume non sono leggibili dal consumer e il log mostra un errore di autorizzazione invece di eseguire l’importazione.
Avviare lo stack e creare il primo utente
docker compose pull
docker compose up -d
docker compose run --rm webserver createsuperuser
docker compose logs -f webservercreatesuperuser richiede un nome utente, un indirizzo email e una password. Non esiste un accesso predefinito. Se si salta questo passaggio, l'interfaccia web chiede al primo utente che la apre di creare il superutente. Finché la porta 8000 è esposta a Internet, il primo utente potrebbe non essere quello previsto. Per questo motivo, creare subito l'account dalla shell. Attendere la riga di log che indica che il server è in ascolto sulla porta 8000 prima di provare ad aprire il browser. Al primo avvio vengono eseguite anche le migrazioni del database, che richiedono uno o due minuti.
Verificare il funzionamento localmente prima di configurare un dominio:
curl -I http://127.0.0.1:8000Un redirect da 302 a /accounts/login/ indica che lo stack è operativo.
Pubblicare il servizio tramite HTTPS
Il file Compose predefinito pubblica 8000:8000, associandolo a tutte le interfacce. Su un VPS pubblico, questo espone l'intero archivio di documenti tramite HTTP non crittografato a chiunque trovi l'indirizzo. Modifica la riga della porta in modo che l'associazione usi soltanto il loopback:
ports:
- "127.0.0.1:8000:8000"Termina quindi TLS (Transport Layer Security) in un reverse proxy e inoltra le richieste a 127.0.0.1:8000. Se questa è l'unica applicazione sul server, è sufficiente un proxy dotato di client ACME (Automatic Certificate Management Environment). Se esegui più container con una configurazione che usa un unico certificato, segui il modello di reverse proxy Traefik per più applicazioni Docker Compose e collega il servizio webserver alla rete del proxy senza pubblicare alcuna porta.
Indipendentemente dal proxy utilizzato, il controllo dell'origine del modulo di accesso è il punto in cui le configurazioni HTTPS possono non funzionare. Paperless ignora X-Forwarded-Proto se non imposti PAPERLESS_PROXY_SSL_HEADER, disabilitato per impostazione predefinita. Di conseguenza, Django considera ogni richiesta inoltrata dal proxy come HTTP non crittografato e l'origine https:// inviata dal browser viene accettata soltanto se è presente nell'elenco delle origini attendibili. Impostare PAPERLESS_URL sull'indirizzo https:// esatto che digiti nel browser aggiunge quell'origine all'elenco. Senza questa impostazione, viene visualizzato CSRF verification failed. Request aborted. su una pagina che sembra corretta.
Aumenta anche il limite della dimensione degli upload nel proxy. Una scansione da 40 MB inviata attraverso un proxy che limita il corpo delle richieste a 1 MB viene rifiutata prima che paperless possa riceverla e il browser mostra un errore generico di caricamento.
Come funziona la directory consume
Il file Compose monta ./consume come bind mount dalla directory Compose al container. Tutto ciò che inserisci in questa directory viene importato e poi eliminato, perché il file viene ora salvato nel volume dei media gestito da Paperless.
cp ~/scan-2026-07-14.pdf ~/paperless/consume/
docker compose logs -f webserverDovresti vedere il consumer rilevare il nome del file, eseguire l'OCR e terminare con una riga che indica che il documento è stato aggiunto. Per una scansione di una pagina, l'intero ciclo richiede pochi secondi. Per un documento lungo, può richiedere un minuto o più.
Due impostazioni modificano il modo in cui vengono individuati i file. PAPERLESS_CONSUMER_RECURSIVE=true fa cercare a Paperless anche nelle sottodirectory, mentre PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true usa il nome di ogni sottodirectory come tag. Di conseguenza, inserendo un file in consume/invoices/2026/, vengono applicati i tag invoices e 2026. È il sistema di archiviazione più semplice che si possa configurare.
L'altra parte è il rilevamento. Per impostazione predefinita, PAPERLESS_CONSUMER_POLLING_INTERVAL è impostato su 0. Paperless usa quindi le notifiche native del filesystem, che vengono generate immediatamente. Queste notifiche non sono affidabili su un filesystem di rete. Se la directory consume è una condivisione NFS o SMB in cui uno scanner di rete può scrivere, i file possono rimanere non rilevati. Per risolvere il problema, imposta l'intervallo su un numero positivo di secondi, in modo che Paperless esegua la scansione della directory.
Lingue OCR e relativo costo
PAPERLESS_OCR_LANGUAGE accetta un codice Tesseract di tre lettere; per impostazione predefinita usa eng. Combina le lingue con il segno più, ad esempio deu+eng. Tesseract usa quindi tutte le lingue elencate per ogni pagina, perciò ogni lingua aggiuntiva aumenta il tempo CPU di ogni scansione. Su un VPS con vCPU condivisa, la differenza può essere tra una scansione completata in dieci secondi e una completata in un minuto. Elenca soltanto le lingue in cui sono effettivamente scritti i documenti.
L'immagine include inglese, tedesco, italiano, spagnolo e francese. Per qualsiasi altra lingua, aggiungila a PAPERLESS_OCR_LANGUAGES come elenco separato da spazi, ad esempio PAPERLESS_OCR_LANGUAGES=tur ces, quindi riavvia il container. Il container scarica i pacchetti dati di Tesseract all'avvio, quindi il primo avvio dopo questa modifica è più lento.
Backup del database e dei file multimediali
Copiare i volumi Docker mentre PostgreSQL è in esecuzione produce un backup che potrebbe non essere ripristinabile. Paperless include un proprio esportatore, che scrive i documenti e un manifest JSON con tutti i metadati nel bind mount ./export:
docker compose exec -T webserver document_exporter ../export --delete --no-progress-bar--delete rimuove i file esportati che non corrispondono più a un documento corrente, così la directory resta un mirror invece di crescere senza fine. --no-progress-bar mantiene pulito l'output quando l'operazione viene eseguita da cron, mentre -T impedisce a Compose di richiedere un terminale che cron non dispone.
Il ripristino viene eseguito con document_importer sulla stessa directory in uno stack appena creato. Di conseguenza, l'unico elemento da proteggere è la directory di esportazione. Inviala a una posizione esterna secondo una pianificazione, usando backup restic cifrati e deduplicati dal tuo VPS, ed esegui prima l'esportazione, così restic non acquisirà mai un archivio scritto solo parzialmente.
Verifica un backup controllando che esista export/manifest.json e che il numero di file corrisponda al numero di documenti mostrato nell'interfaccia. Un backup che non hai mai elencato non è un backup. Peggio ancora, un'esportazione notturna che inizia a fallire senza segnalazioni. Fai quindi in modo che il job cron invii il proprio stato di uscita al tuo server ntfy: scoprirai il problema nella settimana in cui si verifica, invece che il giorno in cui dovrai ripristinare i dati.
FAQ
Perché ogni pagina restituisce "Bad Request (400)" dopo aver associato il dominio?
Con i file predefiniti non dovrebbe accadere, perché PAPERLESS_ALLOWED_HOSTS usa per impostazione predefinita *. Un 400 con DisallowedHost nei log del container indica che PAPERLESS_ALLOWED_HOSTS è stato impostato su un elenco che non include il dominio. Imposta PAPERLESS_URL=https://paperless.example.com in docker-compose.env, senza slash finale, e paperless aggiungerà quell'hostname all'elenco, oppure rimuovi la riga PAPERLESS_ALLOWED_HOSTS. Poi esegui docker compose up -d per ricreare il container. Modificare soltanto il file env non serve, perché il container in esecuzione mantiene l'ambiente con cui è stato avviato.
Ho inserito un PDF nella cartella consume, ma non è successo nulla. Qual è il problema?
Controlla prima docker compose logs webserver. Un errore di autorizzazione indica che USERMAP_UID e USERMAP_GID non corrispondono all'account proprietario del file; correggili e ricrea il container. L'assenza completa di righe nei log indica che l'evento relativo al file non è mai arrivato. Questo accade sulle condivisioni di rete, perché le notifiche native del filesystem non sono affidabili in questo contesto. Imposta PAPERLESS_CONSUMER_POLLING_INTERVAL su un valore come 30: paperless analizzerà invece la cartella ogni 30 secondi.
Posso eseguire paperless-ngx con SQLite invece di PostgreSQL?
Sì, docker-compose.sqlite.yml è supportato e usa meno memoria, quindi è adatto a un piccolo VPS. Lo svantaggio diventa evidente quando l'archivio cresce: la ricerca full-text e le modifiche massive ai tag rallentano sensibilmente quando i documenti diventano migliaia. Una migrazione successiva richiede un'esportazione e un'importazione. Se prevedi che l'archivio continui a crescere, scegli PostgreSQL fin dall'inizio.
Quanto spazio su disco richiede effettivamente un archivio di scansioni?
All'incirca il doppio delle dimensioni dei file originali. Paperless conserva l'originale senza modificarlo e memorizza un secondo PDF elaborato con OCR e livello di testo ricercabile, oltre a piccole miniature. Una scansione di solo testo da 200 KB resta di dimensioni contenute. Una scansione a colori da 30 MB di un contratto lungo occupa circa 60 MB. Se mantieni la directory di esportazione sullo stesso disco, aggiungila al calcolo: lo stesso archivio occuperà tre volte lo spazio.
Sono necessari i container Tika e Gotenberg?
Solo se vuoi indicizzare file Word, Excel o OpenDocument insieme ai PDF. Convertono questi formati in PDF, così paperless può eseguire l'OCR e indicizzarli per la ricerca. Aggiungono inoltre altri due container in esecuzione e alcune centinaia di megabyte di memoria. Puoi quindi ometterli su un server con poche risorse se tutti i file archiviati sono già PDF o immagini.