Installare Paperless-NGX su Ubuntu 24.04 passo dopo passo

Paperless-NGX su Ubuntu 24.04 conviene installarlo in container: separi dipendenze, riduci attriti con i pacchetti di sistema e ti tieni un percorso di upgrade più pulito. La scelta che conta davvero è questa: usare Docker Compose per applicazione, PostgreSQL e Redis, e mettere davanti un reverse proxy con TLS se il servizio deve stare esposto in rete.

Se l’obiettivo è un archivio documentale stabile, il punto non è “far partire l’immagine”, ma costruire tre cose bene: persistenza dei dati, rete esposta solo dove serve, e un metodo semplice per recovery e backup. Qui trovi un’installazione completa su Ubuntu 24.04, con passi reversibili e controlli finali sensati.

Scelta architetturale: container sì, installazione nativa no

Paperless-NGX dipende da componenti che cambiano nel tempo: database, cache, conversione documenti, OCR, storage. Su Ubuntu 24.04 puoi ovviamente forzare un’installazione più artigianale, ma il rapporto rischio/tempo è peggiore. Con Docker Compose ottieni:

• versioning chiaro del deployment in un file Compose;
• isolamento dei servizi;
• rollback rapido a una versione precedente;
• volumi separati per documenti, media e database.

La controparte è semplice: devi trattare i volumi come dati veri, non come dettagli secondari. Se perdi il volume del database perdi l’indice, se perdi il volume dei documenti perdi il contenuto. Prima di toccare qualsiasi cosa, pensa già a dove farai backup e restore.

Prerequisiti su Ubuntu 24.04

Parto da una macchina aggiornata, con accesso sudo e una directory dedicata al progetto. Se il server è in produzione, considera l’impatto sugli utenti e pianifica una finestra: l’installazione in sé è reversibile, ma le decisioni su storage e rete non vanno improvvisate.

Installa i pacchetti base e Docker Engine con Compose plugin. Se Docker è già presente, verifica la versione invece di reinstallare alla cieca.

sudo apt update && sudo apt -y upgrade

sudo apt -y install ca-certificates curl gnupg lsb-release

Per Docker, la via più pulita è il repository ufficiale. Se vuoi restare allineato agli aggiornamenti, non usare pacchetti vecchi di distro quando hai bisogno del supporto a Compose moderno.

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update

sudo apt -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verifica che il daemon sia attivo e che il plugin Compose sia disponibile.

systemctl status docker --no-pager

docker compose version

Se vuoi evitare di usare sempre sudo, aggiungi il tuo utente al gruppo docker, ma fallo solo se il contesto di sicurezza lo consente. In molti ambienti il gruppo docker equivale a privilegi elevati sul sistema.

sudo usermod -aG docker $USER

Assunzione operativa: qui considero un host Ubuntu 24.04 con Docker installato da repository ufficiale e nessun reverse proxy già esistente.

Struttura directory e volumi persistenti

Prima di scrivere il Compose, definisci una directory chiara. Evita percorsi casuali sotto home o test temporanei che poi diventano produzione per inerzia.

sudo mkdir -p /opt/paperless/{data,media,export,consume,pgdata,redisdata}

La distinzione utile è questa:

• data: configurazione e file applicativi;
• media: documenti elaborati e allegati;
• export: esportazioni manuali o di backup;
• consume: cartella di ingestione documenti;
• pgdata: database PostgreSQL;
• redisdata: persistenza Redis, se la vuoi mantenere.

In ambienti piccoli puoi anche lasciare Redis senza persistenza, ma per un articolo operativo conviene tenere la configurazione completa. Il vero punto è sapere cosa contiene ogni volume e non mischiarli.

File .env: variabili minime e segreti fuori dal testo

Paperless-NGX usa variabili d’ambiente per configurare servizi e credenziali. Non mettere password in chiaro dentro un file condiviso o in una guida interna pubblica. Genera valori forti e conserva il file con permessi stretti.

cd /opt/paperless

sudo nano .env

Contenuto base consigliato:

PAPERLESS_TIME_ZONE=Europe/Rome
PAPERLESS_OCR_LANGUAGE=ita+eng
PAPERLESS_URL=https://paperless.example.it
PAPERLESS_SECRET_KEY=INSERISCI_UN_VALORE_LUNGO_RANDOM
PAPERLESS_DBENGINE=postgres
PAPERLESS_DBHOST=db
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=INSERISCI_PASSWORD_FORTE
PAPERLESS_REDIS=redis://redis:6379
PAPERLESS_DATA_DIR=/usr/src/paperless/data
PAPERLESS_MEDIA_ROOT=/usr/src/paperless/media
PAPERLESS_CONSUMPTION_DIR=/usr/src/paperless/consume

Per generare una secret key e una password robusta puoi usare strumenti standard del sistema. Non serve inventarsi stringhe a mano.

openssl rand -base64 48

openssl rand -base64 24

Blocca i permessi del file, soprattutto se il server ha più utenti amministrativi.

chmod 600 /opt/paperless/.env

docker-compose.yml completo e leggibile

Qui l’obiettivo è un compose minimale ma non fragile: database PostgreSQL, Redis, Paperless, e volumi espliciti. Se usi un reverse proxy esterno, non esporre Paperless direttamente su Internet senza TLS.

version: "3.8"

services:
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${PAPERLESS_DBNAME}
      POSTGRES_USER: ${PAPERLESS_DBUSER}
      POSTGRES_PASSWORD: ${PAPERLESS_DBPASS}
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${PAPERLESS_DBUSER} -d ${PAPERLESS_DBNAME}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    restart: unless-stopped
    volumes:
      - ./redisdata:/data
    command: ["redis-server", "--appendonly", "yes"]

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    ports:
      - "8000:8000"
    env_file:
      - .env
    environment:
      PAPERLESS_DBHOST: db
      PAPERLESS_REDIS: redis://redis:6379
      PAPERLESS_CONSUMPTION_DIR: /usr/src/paperless/consume
      PAPERLESS_DATA_DIR: /usr/src/paperless/data
      PAPERLESS_MEDIA_ROOT: /usr/src/paperless/media
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./consume:/usr/src/paperless/consume
      - ./export:/usr/src/paperless/export

Nota pratica: l’immagine “latest” è comoda per il primo avvio, ma in produzione conviene fissare una versione. Senza pinning, un upgrade automatico può cambiare comportamento e complicarti il troubleshooting. Se vuoi controllo, sostituisci latest con un tag preciso.

Avvio iniziale:

docker compose up -d

Controlla che i container siano su e che il database abbia passato il healthcheck.

docker compose ps

docker compose logs -f --tail=100

Creazione utente admin e primo accesso

Paperless crea l’applicazione, ma l’utente amministratore va inizializzato in modo esplicito. Se il container è up ma non riesci a entrare, spesso manca proprio questo passaggio.

docker compose exec webserver document_create_admin

Ti chiederà username, email e password. Se l’ambiente è condiviso o esposto, la password iniziale va ruotata subito dopo il primo login.

Apri il browser su http://IP_DEL_SERVER:8000 solo per validare il servizio in locale o in rete fidata. In produzione, il passo corretto è mettere prima il reverse proxy con HTTPS.

Reverse proxy con Nginx e TLS

Esporre Paperless direttamente sulla porta 8000 non è una scelta che terrei in piedi a lungo. Il proxy ti dà TLS, header corretti, buffering e un punto unico di controllo. Qui uso Nginx sul host, ma va bene anche un proxy già presente nel tuo stack.

Installa Nginx e crea un virtual host dedicato.

sudo apt -y install nginx

sudo nano /etc/nginx/sites-available/paperless.conf

server {
    listen 80;
    server_name paperless.example.it;

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name paperless.example.it;

    ssl_certificate     /etc/letsencrypt/live/paperless.example.it/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/paperless.example.it/privkey.pem;

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 300;
    }
}

Abilita il sito e verifica la sintassi prima di ricaricare Nginx.

sudo ln -s /etc/nginx/sites-available/paperless.conf /etc/nginx/sites-enabled/paperless.conf

sudo nginx -t

sudo systemctl reload nginx

Per il certificato puoi usare Certbot, se il DNS punta già all’host e la porta 80 è raggiungibile.

sudo apt -y install certbot python3-certbot-nginx

sudo certbot --nginx -d paperless.example.it

Se hai già un proxy manager o un CDN, l’idea non cambia: Paperless deve vedere un X-Forwarded-Proto coerente e il client deve arrivare su HTTPS.

Ingest dei documenti: consume, email e OCR

Il flusso più semplice è la cartella consume: butti un PDF dentro, Paperless lo prende, lo indicizza e lo archivia. È il metodo più prevedibile per iniziare, ed è anche quello che semplifica i test.

Se vuoi automatizzare l’ingest da scanner o da processo esterno, monta la cartella di consumo sul client o usa una sincronizzazione controllata. L’importante è evitare copie “creative” con permessi sbagliati che poi fanno fallire l’analisi OCR.

La lingua OCR qui è già impostata su italiano e inglese. Se lavori solo in italiano, puoi usare ita; se ricevi documenti bilingui, ita+eng è una scelta pragmatica.

Per validare il flusso, copia un PDF di test nella cartella consume e osserva i log.

cp test.pdf /opt/paperless/consume/

docker compose logs -f webserver

Se il documento entra ma resta senza testo o senza anteprima, il problema di solito sta nel layer OCR o in dipendenze mancanti. Non partire subito da una reinstallazione: prima guarda log e permessi.

Backup: cosa salvare davvero

Per un sistema documentale il backup serio non è “fare una copia della directory”. Devi salvare almeno database e volumi documentali. Se salvi solo il database, perdi i file; se salvi solo i file, perdi metadati e relazioni.

1. Dump PostgreSQL del database Paperless.
2. Backup di `media`, `data`, `consume` e, se usato, `export`.
3. Verifica di restore in ambiente separato prima di fidarti del backup.

Esempio di dump consistente:

docker compose exec -T db pg_dump -U paperless paperless > /opt/paperless/export/paperless.sql

Per una copia dei volumi puoi usare rsync verso un target di backup. Non farlo a caldo senza capire il carico e la coerenza dei dati, soprattutto sul database. Per PostgreSQL meglio il dump logico che una copia “grezza” del volume.

Se il server è piccolo, la strategia minima accettabile è dump giornaliero del DB più snapshot del filesystem per i documenti. Se il volume cresce, sposta il backup su storage dedicato o object storage con retention definita.

Tuning minimo e punti di attenzione

Paperless non è pesante come un ERP, ma l’OCR può assorbire CPU e RAM durante importazioni massicce. Se noti lentezza, misura prima di toccare parametri: tempi di risposta web, coda documenti, saturazione CPU, memoria dei container.

Le metriche utili sono poche e concrete:

• latenza del frontend sotto carico normale;
• tempo di elaborazione di un PDF medio;
• uso CPU durante OCR;
• spazio disponibile su disco per media e database.

Se il disco si avvicina alla saturazione, il problema non è “Paperless lento”: è un rischio di fermo servizio. Il database e i documenti crescono in modo diverso, quindi monitora entrambi. Su un host singolo, il disco pieno è una delle cause più banali e più distruttive.

Troubleshooting rapido quando qualcosa non parte

Se il servizio non risponde, il primo taglio è sempre il layer: DNS, proxy, container, database, storage. In questa installazione le cause più comuni sono tre: variabili sbagliate nel file .env, database non inizializzato, permessi errati sui volumi.

1. Controlla lo stato dei container: docker compose ps.
2. Guarda i log del webserver e del database: docker compose logs --tail=200 webserver db.
3. Verifica che la porta 8000 sia in ascolto: ss -ltnp | grep 8000.
4. Controlla spazio disco: df -h.

Se vedi errori di connessione al database, non cambiare subito immagine o versione. Falsifica prima l’ipotesi più semplice: password errata, database non raggiungibile, volume PostgreSQL corrotto o permessi incoerenti.

Se la pagina web risponde ma resta bianca o incompleta, controlla il reverse proxy e gli header. Un X-Forwarded-Proto sbagliato o un proxy_pass verso l’host errato può simulare problemi applicativi che in realtà non lo sono.

Aggiornamento controllato e rollback

Quando vuoi aggiornare Paperless, non farlo con una pull cieca e basta. Prima salva lo stato attuale: tag immagine, file Compose, file .env e dump del database. Il rollback vero è tornare a una combinazione nota e funzionante.

docker compose pull

docker compose up -d

Se hai fissato un tag preciso, puoi tornare indietro sostituendo il tag dell’immagine e rilanciando il compose. Se invece hai lasciato latest, il rollback è meno prevedibile: è proprio il motivo per cui in produzione conviene pinning esplicito.

Prima di considerare l’aggiornamento chiuso, fai sempre due verifiche: login funzionante e import di un documento di test. Se una di queste fallisce, non chiamarlo upgrade riuscito.

Schema finale consigliato

Se vuoi una versione pulita da mantenere nel tempo, questa è la direzione giusta: Ubuntu 24.04 aggiornato, Docker ufficiale, Paperless in Compose, PostgreSQL e Redis separati, reverse proxy con TLS, backup regolari del database e dei volumi documentali. È una base semplice da capire e abbastanza solida da non diventare un debito tecnico dopo due mesi.

La vera differenza non la fa l’installazione iniziale, ma la disciplina operativa: sapere dove sono i dati, come si verifica il servizio, come si aggiorna senza sorprese e come si torna indietro se qualcosa rompe il flusso documentale.