Installation de Paperless-ngx avec Docker Compose sous Debian 13

Paperless-ngx est un système de gestion de documents open source soutenu par la communauté qui transforme vos documents physiques en une archive en ligne consultable, vous permettant ainsi de conserver moins de papier.

Configuration de Debian 13

Pour les tests, j’ai installé une machine virtuelle sous Debian 13 avec VirtualBox sans interface graphique avec le serveur SSH installé (j’ai créé l’utilisateur dominique). Si vous avez des problèmes pour utiliser certaines lignes de commande du Shell Bash modifiez la variable d’environnement PATH. Vous pouvez commenter la ligne du sources.list qui correspond au CDROM d’installation. Un serveur doit être en IP fixe. Éventuellement, modifier le port SSH.

Installation de Docker et Docker Compose

Alternative 100 % Debian (sans dépôt Docker)

apt install docker.io docker-compose

Pour que Docker démarre automatiquement avec la machine :

systemctl enable docker

Pour vérifier que Docker est bien installé :

systemctl status docker

Utilisateur, groupe et dossier

En administrateur root (su).

Ajouter mon utilisateur « dominique » créé lors de l’installation de Debian au groupe docker :

usermod -aG docker dominique

Créez le dossier :

mkdir -p /opt/paperless-ngx

Attribuer le dossier à l’utilisateur et au groupe dominique :

chown dominique:dominique /opt/paperless-ngx

Aller dans le dossier :

cd /opt/paperless-ngx

Copiez les fichiers docker-compose.yml et docker-compose.env dans ce dossier.

Configuration de docker-compose.yml

Modifiez le fichier docker-compose.yml pour utiliser la version 2.20.2 et activer Redis (nécessaire pour les règles/automatisations) dans le dossier /opt/paperless-ngx :

nano docker-compose.yml
services:
  broker:
    image: redis:7
    restart: unless-stopped

  db:
    image: postgres:15
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless

  tika:
    image: apache/tika:3.2.3.0-full
    restart: unless-stopped

  gotenberg:
    image: gotenberg/gotenberg:8.10.0
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"
    environment:
      - LIBREOFFICE_TIMEOUT=120  # Délai en secondes (par défaut : 30)

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.2
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - tika
      - gotenberg
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_TASK_WORKERS: 2
      PAPERLESS_OCR_LANGUAGES: fra eng
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
    dns:
      - 8.8.8.8   # Google DNS
      - 1.1.1.1   # Cloudflare DNS
volumes:
  data:
  media:
  pgdata:

Après modifications.

CRTL + X pour quitter l’éditeur nano.

O pour confirmer l’enregistrement des modifications.

Entrée pour confirmer le nom du fichier.

Ports définis à 8000.

la base de données PostgreSQL

  • Une base de données nommée paperless est créée.
  • Un utilisateur paperless avec le mot de passe paperless est configuré.

Si vous souhaitez changer le nom de la base, l’utilisateur ou le mot de passe, modifiez les valeurs dans le docker-compose.yml et ajoutez les variables correspondantes dans docker-compose.env.

Durant mes tests, j’ai paramétré le timeout pour Gotenberg ainsi que les DNS.

Configuration de docker-compose.env

Voici un exemple complet de fichier docker-compose.env pour paperless-ngx v2.20.2, incluant les paramètres essentiels pour une installation fonctionnelle avec Redis, les règles/automatisations, et l’accès à manage.py. Toujours dans le dossier /opt/paperless-ngx :

nano docker-compose.env
# Identifiants de l'utilisateur système (UID/GID)
USERMAP_UID=1000
USERMAP_GID=1000

# Configuration de l'utilisateur administrateur
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=test79
PAPERLESS_ADMIN_MAIL=mon.adresse@mail.com

# Paramètres de base
PAPERLESS_TIME_ZONE=Europe/Paris
PAPERLESS_OCR_LANGUAGES=fra eng
PAPERLESS_CONSUMER_POLLING=60
PAPERLESS_CONSUMER_RECURSIVE=true
PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true

# Configuration pour Redis (nécessaire pour les règles/automatisations)
PAPERLESS_REDIS=redis://broker:6379

# Nombre de workers pour les tâches en arrière-plan
PAPERLESS_TASK_WORKERS=2

# Chemins des volumes (adaptez selon votre configuration)
PAPERLESS_DATA_DIR=/usr/src/paperless/data
PAPERLESS_MEDIA_ROOT=/usr/src/paperless/media
PAPERLESS_EXPORT_DIR=/usr/src/paperless/export

# Paramètres optionnels pour le traitement des documents
PAPERLESS_TIKA_ENABLED=1
PAPERLESS_TIKA_GOTENBERG_ENDPOINT=http://gotenberg:3000
PAPERLESS_TIKA_ENDPOINT=http://tika:9998

# Paramètres pour l'authentification HTTP (si utilisé derrière un proxy)
# PAPERLESS_ENABLE_HTTP_REMOTE_USER=true

# Paramètres pour la base de données (si vous utilisez PostgreSQL)
PAPERLESS_DBHOST=db
PAPERLESS_DBPORT=5432
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=paperless

Après modifications.

CRTL + X pour quitter l’éditeur nano.

O pour confirmer l’enregistrement des modifications.

Entrée pour confirmer le nom du fichier.

Explications des paramètres clés :

  • USERMAP_UID/GID : Doivent correspondre à votre utilisateur Linux pour éviter les problèmes de permissions (Dans mon cas 1000 vérifié avec la commande : id dominique).
  • PAPERLESS_ADMIN_* : Identifiants de l’administrateur de l’interface web (Dans mon cas, utilisateur : admin, mots de passe : test79, adresse mail, à personnaliser.).
  • PAPERLESS_REDIS : Obligatoire pour les règles/automatisations.
  • PAPERLESS_OCR_LANGUAGES : Langues pour la reconnaissance optique (ex: fra eng pour français et anglais).
  • PAPERLESS_DATA_DIR/MEDIA_ROOT/EXPORT_DIR : Chemins internes aux conteneurs, ne pas modifier sauf besoin spécifique.
  • PAPERLESS_TIKA_* : À activer si vous utilisez Tika et Gotenberg pour le traitement avancé des documents.

Lancement de paperless-ngx

Démarrez les conteneurs depuis le dossier /opt/paperless-ngx :

docker compose up -d

Accès à l’interface et à manage.py

  • L’interface web est accessible sur http://adresse_IP:8000 (Dans mon cas, utilisateur : admin, mots de passe : test79).

Pour accéder à manage.py (par exemple pour lancer des commandes Django)

docker compose exec webserver python3 manage.py [commande]

Exemple pour créer un superutilisateur :

cd /opt/paperless-ngx
docker compose exec webserver python3 manage.py createsuperuser

Tika et Gotenberg

Pourquoi ces services ?

  • Tika : Permet d’extraire le texte et les métadonnées de nombreux types de fichiers (PDF, Office, etc.).
  • Gotenberg : Convertit les fichiers (comme les emails .eml) en PDF pour un traitement optimal par paperless-ngx.


Consulter les logs Tika et Gotenberg :

docker compose logs tika gotenberg

Pour voir la dernière version de Tika :

https://hub.docker.com/r/apache/tika

Exemple si l’on veut modifier le fichier docker-compose.yml

Si on veut modifier une configuration déjà existante :

cd /opt/paperless-ngx

arrêter nos conteneurs Docker :

docker compose down

Redémarrer les conteneurs après avoir modifié les fichiers de configuration :

docker compose up -d

Pour vérifier le résultat dans mon cas :

docker logs -f paperless-ngx-webserver-1

Pour lister les conteneurs :

docker ps

Voir également les commandes Docker

Pour recevoir les fichiers depuis une adresse mail

1 – docker-compose.env (optionnel)

Je ne suis pas convaincu de l’utilité de cette configuration dans mon cas. Pour le moment, je teste sans l’utiliser. Je conserve néanmoins ces informations

Je passe directement à la « Configuration depuis l’interface WEB des comptes de messageries ».

On peut ajouter à la fin du fichier docker-compose.env la configuration IMAP d’une adresse mail (Mailo par exemple) :

cd /opt/paperless-ngx
nano docker-compose.env
# Configuration IMAP pour Mailo
PAPERLESS_MAIL_SERVER=mail.mailo.com
PAPERLESS_MAIL_PORT=993
PAPERLESS_MAIL_USERNAME=mon.adresse@mailo.com
PAPERLESS_MAIL_PASSWORD=mon-mot-de-passe
PAPERLESS_MAIL_USE_SSL=true
PAPERLESS_MAIL_USE_TLS=false
PAPERLESS_MAIL_FOLDER=INBOX
PAPERLESS_MAIL_FILTER=""

Après modifications.

CRTL + X pour quitter l’éditeur nano.

O pour confirmer l’enregistrement des modifications.

Entrée pour confirmer le nom du fichier.

Si vous modifiez une configuration existante, arrêtez puis recréez les conteneurs Docker comme vu précédemment.

2 – Configuration depuis l’interface WEB des comptes de messageries

J’ai testé la configuration de deux adresses mail Mailo avec cette procédure.

J’ai ensuite poursuivi la configuration depuis l’interface WEB.

Courriel ==> Comptes de messagerie ==> Ajouter un compte

  • Nom : mon.adresse@mailo.com
  • Serveur IMAP : mail.mailo.com
  • Port IMAP : 993
  • Sécurité IMAP : SSL
  • Nom d’utilisateur : mon.adresse@mailo.com
  • Mot de passe : mon-mot-de-passe
  • Le mot de passe est un jeton d’authentification : Décoché
  • Jeu de caractères : UTF-8

Puis Enregister

Courriel ==> Règles de courriel ==> Ajouter une règle

  • Nom : mon.adresse@mailo.com par exemple
  • Compte : mon.adresse@mailo.com
  • Ordre : 1 par exemple
  • Âge maximum (jours) : 30 par exemple

J’ai conservé les options par défaut pour le reste…

Puis Enregister

3 – Plus d’informations pour les dépannages

  • Configurer un seul compte dans docker-compose.env (optionnel, je n’utilise pas).
  • Ajouter tous les comptes supplémentaires dans l’interface graphique.

Depuis le dossier :

cd /opt/paperless-ngx

Vérifier les logs pour confirmer le traitement :

docker compose logs webserver

Tester la connectivité avec curl (pour vérifier si le serveur IMAP répond, celui de mailo dans mon cas) :

docker compose exec webserver curl -v telnet://imap.mailo.com:993

Quitter avec CTRL + C

j’ai rencontré des problèmes de DNS…

Pour voir les serveurs DNS utilisés par le conteneur :

docker compose exec webserver cat /etc/resolv.conf

Pour vérifier le bon fonctionnement des comptes de messagerie

Depuis l’interface WEB :

Courriel ==> Comptes de messagerie ==> Modifier ==> Tester

Journaux ==> mail.log

Arrêt et redémarrage manuel du serveur

Se déconnecter de l’interface WEB.

Pour arrêter les conteneurs Docker depuis la console ou depuis un terminal en SSH.

1 – Arrêt

cd /opt/paperless-ngx
docker compose down
  • Cette commande arrête tous les conteneurs (paperless-ngx, Redis, PostgreSQL, Tika, Gotenberg) de manière propre, sans perdre de données.

Si vous avez configuré le service :

systemctl stop paperless-ngx.service

Vérifier que les conteneurs sont bien arrêtés :

docker ps

Redémarrer le serveur (si nécessaire) :

docker compose up -d

En administrateur root (su).

Redémarrage du serveur sous Debian 13 :

shutdown -r now

Arrêt du serveur sous Debian 13 :

shutdown -h now

2 – Redémarrage

Si vous n’utilisez pas le démarrage automatique du service.

cd /opt/paperless-ngx
docker compose up -d

Activer le service Docker au démarrage de Debian 13

Vérifiez que Docker est configuré pour démarrer automatiquement en administrateur root (su) :

systemctl enable docker
  • Cela garantit que le démon Docker est lancé dès le démarrage du système.

1 – Créer un service système pour paperless-ngx

Créez un fichier de service pour gérer le démarrage automatique de vos conteneurs paperless-ngx en administrateur root (su) :

nano /etc/systemd/system/paperless-ngx.service
[Unit]
Description=Paperless-ngx Docker Compose
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/paperless-ngx
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

Après modifications.

CRTL + X pour quitter l’éditeur nano.

O pour confirmer l’enregistrement des modifications.

Entrée pour confirmer le nom du fichier.

2 – Activer le service paperless-ngx

Activez le service pour qu’il démarre automatiquement en administrateur root (su) :

systemctl enable paperless-ngx.service

Démarrer le service immédiatement (optionnel dans le cas où Paperless est arrêté) :

systemctl start paperless-ngx.service

Pour vérifier que tout fonctionne :

systemctl status paperless-ngx.service

Pour l’arrêt du service :

systemctl stop paperless-ngx.service

3 – Voir également les services Linux

Installations réalisées

J’ai commencé par une installation sur une machine virtuelle sous VirtualBox sur mon ordinateur personnel sous Linux Mint. Maintenant, je travaille sur une installation sur un serveur sous Proxmox. La machine virtuelle se trouvant derrière un pare-feu IPFire, j’ai dû autoriser l’accès via le port 8000. L’envoi de documents par mail a bien fonctionné.

Dominique Renaudeau

Retour en haut