Installation · 5 min read · Sep 25, 2025

Comment installer Paperless avec Nginx sur Debian

Paperless est une application Python qui ingère des documents numérisés, les indexe et les présente dans une interface web conviviale. Dans ce tutoriel, nous allons installer Paperless avec un proxy inverse HTTPS Nginx sur Debian 10.

  • Un système Debian 10 sur lequel vous avez un accès root.
  • Un nom de domaine enregistré pointant vers votre serveur.

Tous les commandes montrées dans ce document doivent être exécutées en tant que root, sauf indication contraire.

Définissez la variable d’environnement $VISUAL sur un éditeur de texte de votre choix. Par exemple, pour utiliser nano :

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

Paperless nécessite plusieurs composants logiciels pour son installation et son fonctionnement. Installez-les comme suit :

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++

Si vous allez travailler avec des documents dans des langues autres que l’anglais, installez les fichiers de langue Tesseract correspondants. Par exemple, pour le français et l’espagnol :

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

Vous pouvez lister tous les paquets tesseract disponibles en utilisant :

apt list tesseract-ocr-*

Si vous n’êtes pas sûr du code à 3 lettres correspondant à la langue souhaitée, consultez cette liste de codes ISO 639-2.

Bien qu’il soit possible d’exécuter paperless en tant que root, il est fortement recommandé d’utiliser un utilisateur avec des privilèges réduits et un accès désactivé. Créez un utilisateur et un groupe nommés paperless :

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

Clonez le dépôt Github de Paperless dans /opt/paperless

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

Donnez à l’utilisateur paperless la propriété de ce répertoire :

chown -R paperless:paperless /opt/paperless

Copiez l’exemple de configuration inclus comme point de départ :

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

Et ouvrez-le dans votre éditeur de texte :

$VISUAL /etc/paperless.conf

Choisissez un répertoire à partir duquel Paperless ingérera les documents numérisés et définissez le paramètre PAPERLESS_CONSUMPTION_DIR en conséquence :

PAPERLESS_CONSUMPTION_DIR="/opt/paperless/paper_in"

Trouvez, décommentez (en supprimant le caractère #) et changez les valeurs des lignes suivantes pour quelque chose de sécurisé :

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

Si votre scanner prend en charge l’envoi par e-mail de documents numérisés, vous pouvez faire en sorte que paperless les ingère automatiquement depuis la boîte de réception. Pour activer cette fonctionnalité, définissez les options PAPERLESSCONSUME_MAIL*. Pour des raisons de sécurité, il est recommandé de créer un compte de messagerie dédié à Paperless. Par exemple :

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

Enregistrez vos modifications et quittez, puis changez le propriétaire de ce fichier en paperless et renforcez ses permissions :

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

Passez à l’utilisateur paperless :

su - paperless

Créez le répertoire de consommation :

mkdir /opt/paperless/paper_in

Créez un environnement virtuel Python. Cela fournira un environnement stable et isolé où nous pourrons installer les modules Python spécifiques et les versions requises par Paperless.

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

Activez-le :

. venv/bin/activate

Installez les modules Python requis par paperless :

pip3 install -r requirements.txt

Cette commande peut prendre un certain temps. Une fois terminée, exécutez les commandes suivantes pour initialiser la base de données et créer les fichiers statiques pour le service web :

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

Créez des identifiants de connexion pour le compte administrateur de l’interface web en exécutant la commande suivante et en répondant aux invites :

./manage.py createsuperuser

Avant de configurer un serveur web approprié et des services systemd, nous allons essayer d’exécuter paperless manuellement. À ce stade, vous devriez toujours être connecté en tant que paperless dans l’environnement virtuel Python.

Démarrez le serveur web et le consommateur de documents en arrière-plan :

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

Placez tout document numérisé dans le répertoire de consommation configuré à l’étape 3. Par exemple :

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

Accédez à http://IP_or_DOMAIN:8000/ et connectez-vous avec les identifiants choisis à l’étape 3. Dans le menu “DOCUMENTS”, cliquez sur “Documents” pour voir la liste des documents. Dans quelques minutes, le document numérisé devrait être traité et disponible.

Arrêtez paperless avant de passer à l’étape suivante :

pkill -f manage.py

Nous allons créer des fichiers d’unité systemd afin de pouvoir gérer correctement les services web et de consommateur. Sortez de votre shell root :

exit

Créez un fichier d’unité pour le service web :

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

Et entrez ce qui suit :

[Unit]
Description=Serveur Web Gunicorn Paperless
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

REMARQUE : Vous voudrez peut-être modifier le nombre de processus de travail dans la commande ExecStart. Le service montré ici démarre Gunicorn avec 3 travailleurs ( -w 3).

Ensuite, créez un autre fichier d’unité pour le processus de consommateur de documents :

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

Et entrez ce qui suit :

[Unit]
Description=Consommateur de Documents Paperless
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

Démarrez ces services :

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

Assurez-vous qu’ils fonctionnent tous les deux :

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

Si vous souhaitez que paperless démarre automatiquement au démarrage du système, exécutez la commande :

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

Installez Nginx et certbot :

apt update
apt install -y nginx certbot

Assurez-vous que Nginx est activé et en cours d’exécution :

systemctl enable --now nginx.service

Obtenez un certificat Let’s Encrypt pour votre domaine avec certbot :

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

Désactivez le fichier de configuration Nginx par défaut et ouvrez un nouveau :

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

Entrez ce qui suit, remplacez your_domain par votre nom de domaine :

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;
    }
}

Activez cette configuration en créant un lien vers elle dans le répertoire Nginx sites-enabled, et vérifiez s’il y a des erreurs :

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

Puis chargez les modifications :

systemctl reload nginx.service

Votre instance Paperless devrait maintenant être accessible à https://your_domain.

Puisque l’utilisateur système paperless n’a pas besoin d’accès à un shell fonctionnel après la configuration initiale, nous pouvons le changer en /usr/sbin/nologin :

usermod -s /usr/sbin/nologin paperless

Si le serveur web Gunicorn ne parvient pas à démarrer avec le message d’erreur [ERROR] Connection in use, vérifiez s’il y a des processus déjà liés au port 8000/tcp :

ss -lntp

Tuez/Désactivez le processus en question si nécessaire, ou modifiez /etc/systemd/system/paperless-webserver.service et /etc/nginx/sites-enabled/paperless pour utiliser un autre port réseau pour Gunicorn.

Share: X/Twitter LinkedIn
#Installation

Recevez de nouveaux articles dans votre boîte de réception.

Aucun spam. Désabonnez-vous à tout moment.