Installazione software · 5 min read · Sep 25, 2025

Come installare Paperless con Nginx su Debian

Paperless è un’applicazione Python che acquisisce documenti scansionati, li indicizza e li presenta in un’interfaccia web user-friendly. In questo tutorial, installeremo Paperless con un proxy inverso HTTPS Nginx su Debian 10.

  • Un sistema Debian 10 su cui hai accesso root.
  • Un nome di dominio registrato che punta al tuo server.

Tutti i comandi mostrati in questo documento devono essere eseguiti come root, a meno che non sia indicato diversamente.

Imposta la variabile d’ambiente $VISUAL su un editor di testo a tua scelta. Ad esempio, per usare nano:

echo "export VISUAL=nano" >> ~/.bashrc
. ~/.bashrc

Paperless richiede diversi componenti software per la sua installazione e funzionamento. Installali come segue:

apt update
apt install -y gnupg2 python3 python3-dev python3-pip python3-virtualenv tesseract-ocr tesseract-ocr-eng unpaper imagemagick libpoppler-cpp-dev optipng git gcc g++

Se intendi lavorare con documenti in lingue diverse dall’inglese, installa i file di lingua Tesseract corrispondenti. Ad esempio, per francese e spagnolo:

apt install -y tesseract-ocr-fra tesseract-ocr-spa

Puoi elencare tutti i pacchetti tesseract disponibili usando:

apt list tesseract-ocr-*

Se non sei sicuro di quale codice di 3 lettere corrisponda alla lingua desiderata, fai riferimento a questo Elenco di Codici ISO 639-2.

Sebbene sia possibile eseguire paperless come root, è fortemente consigliato utilizzare un utente con privilegi ridotti e accesso disabilitato. Crea un utente e un gruppo chiamati paperless:

useradd -d /opt/paperless -M -r -s /bin/bash -U -p x paperless

Clona il repository Github di Paperless in /opt/paperless

git clone https://github.com/the-paperless-project/paperless.git /opt/paperless

Dai all’utente paperless la proprietà di quella directory:

chown -R paperless:paperless /opt/paperless

Copia il campione di configurazione incluso come punto di partenza:

cp /opt/paperless/paperless.conf.example /etc/paperless.conf

E aprilo nel tuo editor di testo:

$VISUAL /etc/paperless.conf

Scegli una directory da cui Paperless acquisirà documenti scansionati e imposta il parametro PAPERLESS_CONSUMPTION_DIR di conseguenza:

PAPERLESS_CONSUMPTION_DIR="/opt/paperless/paper_in"

Trova, decommenta (rimuovendo il carattere #) e cambia i valori delle seguenti righe in qualcosa di sicuro:

#PAPERLESS_PASSPHRASE="secret"
#PAPERLESS_SECRET_KEY="change-me"

Se il tuo scanner supporta l’invio di documenti scansionati via email, puoi far sì che paperless li acquisisca automaticamente dalla casella di posta in arrivo. Per abilitare questa funzionalità, imposta le opzioni PAPERLESSCONSUME_MAIL*. Per motivi di sicurezza, è consigliato creare un’email dedicata a Paperless. Ad esempio:

PAPERLESS_CONSUME_MAIL_HOST="imap.example.com"
PAPERLESS_CONSUME_MAIL_PORT="993"
PAPERLESS_CONSUME_MAIL_USER="[email protected]"
PAPERLESS_CONSUME_MAIL_PASS="imap_password"

Salva le tue modifiche ed esci, quindi cambia il proprietario di questo file in paperless e stringi le sue autorizzazioni:

chown paperless:paperless /etc/paperless.conf
chmod 0400 /etc/paperless.conf

Passa all’utente paperless:

su - paperless

Crea la directory di consumo:

mkdir /opt/paperless/paper_in

Crea un ambiente virtuale python. Questo fornirà un ambiente stabile e isolato in cui possiamo installare i moduli e le versioni specifiche di python richieste da Paperless.

python3 -m virtualenv --python=/usr/bin/python3 venv

Attivalo:

. venv/bin/activate

Installa i moduli python richiesti da paperless:

pip3 install -r requirements.txt

Questo comando potrebbe richiedere del tempo. Una volta terminato, esegui i seguenti comandi per inizializzare il database e creare i file statici per il servizio web:

cd src/
./manage.py migrate
./manage.py collectstatic

Crea le credenziali di accesso per l’account amministratore dell’interfaccia web eseguendo il seguente comando e rispondendo alle domande:

./manage.py createsuperuser

Prima di configurare un server web adeguato e i servizi systemd, proveremo a eseguire paperless manualmente. A questo punto, dovresti essere ancora connesso come paperless nell’ambiente virtuale python.

Avvia il server web e il consumatore di documenti in background:

./manage.py runserver 0.0.0.0:8000 &
./manage.py document_consumer &

Posiziona qualsiasi documento scansionato nella directory di consumo configurata nel Passo 3. Ad esempio:

wget https://i.imgur.com/DPr5wWG.jpg -O /opt/paperless/paper_in/test1.jpg

Naviga su http://IP_or_DOMAIN:8000/ e accedi con le credenziali scelte nel Passo 3. Nel menu “DOCUMENTI”, fai clic su “Documenti” per visualizzare l’elenco dei documenti. Nel giro di pochi minuti, il documento scansionato dovrebbe essere elaborato e disponibile.

Ferma paperless prima di procedere al passaggio successivo:

pkill -f manage.py

Creeremo file di unità systemd in modo da poter gestire correttamente i servizi web e di consumo. Esci di nuovo nella tua shell root:

exit

Crea un file di unità per il servizio web:

$VISUAL /etc/systemd/system/paperless-webserver.service

E inserisci quanto segue:

[Unit]
Description=Paperless Gunicorn Web Server
Requires=network.target
[Service]
User=paperless
Group=paperless
ExecStart=/opt/paperless/venv/bin/gunicorn --pythonpath=/opt/paperless/src paperless.wsgi -w 3 -b 127.0.0.1:8000
Restart=on-failure
[Install]
WantedBy=multi-user.target

NOTA: Potresti voler modificare il numero di processi worker nel comando ExecStart. Il servizio mostrato qui avvia Gunicorn con 3 worker ( -w 3).

Successivamente, crea un altro file di unità per il processo del consumatore di documenti:

$VISUAL /etc/systemd/system/paperless-consumer.service

E inserisci quanto segue:

[Unit]
Description=Paperless Document Consumer
Requires=network.target
[Service]
User=paperless
Group=paperless
ExecStart=/opt/paperless/venv/bin/python3 /opt/paperless/src/manage.py document_consumer
Restart=on-failure
[Install]
WantedBy=multi-user.target

Avvia questi servizi:

systemctl daemon-reload
systemctl start paperless-webserver.service paperless-consumer.service

Assicurati che entrambi siano in esecuzione:

systemctl status paperless-webserver.service paperless-consumer.service

Se desideri che paperless si avvii automaticamente all’avvio del sistema, esegui il comando:

systemctl enable paperless-webserver.service paperless-consumer.service

Installa Nginx e certbot:

apt update
apt install -y nginx certbot

Assicurati che Nginx sia abilitato e in esecuzione:

systemctl enable --now nginx.service

Ottieni un certificato Let’s Encrypt per il tuo dominio con certbot:

certbot certonly --webroot --webroot-path /var/www/html -d your_domain

Disabilita il file di configurazione predefinito di Nginx e aprine uno nuovo:

rm /etc/nginx/sites-enabled/default
$VISUAL /etc/nginx/sites-available/paperless

Inserisci quanto segue, sostituisci your_domain con il tuo nome di dominio:

server {
    listen 80;
    server_name your_domain;
    return 301 https://$server_name$request_uri;
    access_log /var/log/nginx/paperless_access.log;
    error_log /var/log/nginx/paperless_error.log;
}
server {
    listen 443 ssl;
    server_name your_domain;
    index index.html index.htm index.php;
    access_log /var/log/nginx/paperless_access.log;
    error_log /var/log/nginx/paperless_error.log;
    ssl on;
    ssl_certificate /etc/letsencrypt/live/your_domain/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your_domain/privkey.pem;
    location /static {
        autoindex on;
        alias /opt/paperless/static;
    }
    location / {
        proxy_set_header Host $http_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 $scheme;
        proxy_pass http://127.0.0.1:8000;
    }
}

Abilita questa configurazione collegandola nella directory sites-enabled di Nginx e controlla eventuali errori:

ln -s /etc/nginx/sites-available/paperless /etc/nginx/sites-enabled
nginx -t

Quindi carica le modifiche:

systemctl reload nginx.service

La tua istanza di Paperless dovrebbe ora essere accessibile su https://your_domain.

Poiché l’utente di sistema paperless non ha bisogno di accesso a una shell funzionante dopo la configurazione iniziale, possiamo cambiarlo in /usr/sbin/nologin:

usermod -s /usr/sbin/nologin paperless

Se il server web Gunicorn non riesce ad avviarsi con il messaggio di errore [ERROR] Connection in use, controlla eventuali processi già legati alla porta 8000/tcp:

ss -lntp

Termina/disabilita il processo problematico se necessario, oppure modifica /etc/systemd/system/paperless-webserver.service e /etc/nginx/sites-enabled/paperless per utilizzare un’altra porta di rete per Gunicorn.

Share: X/Twitter LinkedIn
#Installazione software

Ricevi i nuovi post nella tua casella di posta.

Nessuno spam. Disiscriviti in qualsiasi momento.