mercredi 3 décembre 2025

Déployer Paperless-ngx sur Debian 13 avec Docker et Portainer

Installation de Paperless-ngx avec Docker Compose

Installation de Paperless-ngx avec Docker Compose

Déployez votre GED personnelle avec support OCR et fichiers Office

Webographie

Objectif

Installer et configurer Paperless-ngx, une solution complète de gestion électronique de documents (GED) avec OCR multilingue et support des fichiers Office. Cette installation inclut tous les services nécessaires : PostgreSQL, Redis, Gotenberg (conversion Office) et Tika (extraction de texte).

Prérequis

  • ✅ Docker installé et fonctionnel
  • ✅ Docker Compose disponible
  • ✅ (Optionnel) Portainer pour la gestion via interface web
  • ✅ Au moins 4 GB de RAM disponible

Vérification rapide :

docker --version
docker compose version

1. Création de la structure de dossiers

Créez les répertoires nécessaires pour Paperless-ngx :

# Création de la structure complète
mkdir -p /opt/paperless-ngx/{consume,data,media,export,postgres,redis}

# Attribution des permissions (remplacez 1000:1000 par votre UID:GID)
sudo chown -R 1000:1000 /opt/paperless-ngx

# Vérification
ls -la /opt/paperless-ngx/

Structure des dossiers :

  • consume/ - Documents à traiter automatiquement
  • data/ - Données de l'application
  • media/ - Documents archivés et traités
  • export/ - Exports et sauvegardes
  • postgres/ - Base de données PostgreSQL
  • redis/ - Cache Redis

💡 Trouver votre UID:GID :

id
# Résultat : uid=1000(votre_user) gid=1000(votre_user)

2. Création du fichier docker-compose.yml

Créez le fichier de configuration Docker Compose :

cd /opt/paperless-ngx
nano docker-compose.yml

Contenu du fichier :

version: "3.8"

services:
  broker:
    image: redis:7
    container_name: paperless-redis
    restart: unless-stopped
    volumes:
      - ./redis:/data
    environment:
      TZ: Europe/Paris

  db:
    image: postgres:16
    container_name: paperless-db
    restart: unless-stopped
    volumes:
      - ./postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperlessuser
      POSTGRES_PASSWORD: ChangezCeMotDePasse123!
      TZ: Europe/Paris

  gotenberg:
    image: gotenberg/gotenberg:8
    container_name: paperless-gotenberg
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    image: apache/tika:latest
    container_name: paperless-tika
    restart: unless-stopped

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless-ngx
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8095:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      # Base de données
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperlessuser
      PAPERLESS_DBPASS: ChangezCeMotDePasse123!
      
      # Services de conversion
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      
      # Configuration OCR
      PAPERLESS_OCR_LANGUAGE: fra+eng
      
      # Configuration générale
      PAPERLESS_TIME_ZONE: Europe/Paris
      PAPERLESS_SECRET_KEY: ChangezCetteCleSuperSecrete2024!
      PAPERLESS_URL: http://192.168.1.100:8095
      
      # Compte administrateur (création automatique)
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: VotreMotDePasseAdmin123!
      PAPERLESS_ADMIN_MAIL: admin@example.com
      
      # Permissions
      USERMAP_UID: 1000
      USERMAP_GID: 1000

⚠️ PERSONNALISATION OBLIGATOIRE :

Paramètre À modifier
POSTGRES_PASSWORD Mot de passe PostgreSQL (doit être identique à PAPERLESS_DBPASS)
PAPERLESS_DBPASS Mot de passe PostgreSQL (même valeur que ci-dessus)
PAPERLESS_SECRET_KEY Clé secrète unique (générez-en une avec openssl rand -base64 32)
PAPERLESS_URL Votre IP ou nom de domaine
PAPERLESS_ADMIN_USER Nom d'utilisateur admin (optionnel, par défaut "admin")
PAPERLESS_ADMIN_PASSWORD Mot de passe du compte admin
PAPERLESS_ADMIN_MAIL Votre adresse email
USERMAP_UID / USERMAP_GID Votre UID:GID (trouvé avec id)
PAPERLESS_OCR_LANGUAGE Langues OCR : fra (français), eng (anglais), deu (allemand), spa (espagnol), etc.

💡 Générer une clé secrète sécurisée :

openssl rand -base64 32

3. Déploiement de Paperless-ngx

Lancez le stack complet :

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

Vérifiez que tous les conteneurs sont démarrés :

docker compose ps

Vous devriez voir 5 conteneurs avec le statut "Up" :

  • ✅ paperless-ngx - Application principale
  • ✅ paperless-db - Base de données PostgreSQL
  • ✅ paperless-redis - Cache Redis
  • ✅ paperless-gotenberg - Conversion Office
  • ✅ paperless-tika - Extraction de texte

Surveillez les logs pendant le démarrage initial :

docker compose logs -f

Attendez que l'initialisation soit terminée (peut prendre 1-2 minutes au premier démarrage).

4. Première connexion

Accédez à l'interface web :

http://VOTRE-IP:8095

Connectez-vous avec les identifiants définis :

  • Nom d'utilisateur : admin (ou celui défini dans PAPERLESS_ADMIN_USER)
  • Mot de passe : celui défini dans PAPERLESS_ADMIN_PASSWORD

🎉 Félicitations ! Paperless-ngx est opérationnel !

5. Configuration initiale recommandée

Paramètres OCR (Settings → OCR) :

  • OCR mode : skip (sauter si texte déjà présent)
  • OCR language : Vérifier que fra+eng est bien configuré
  • Auto-rotate pages : Activé ✅

Métadonnées de base à créer :

1. Correspondants (Correspondents)

Créez des correspondants pour identifier automatiquement les expéditeurs/destinataires :

  • EDF, Orange, Banque, Assurance, Employeur, etc.

2. Tags

Organisez vos documents avec des tags :

  • Facture, Contrat, Administratif, Personnel, Impôts, Santé, etc.

3. Types de documents (Document types)

Catégorisez vos documents :

  • Facture, Contrat, Courrier, Reçu, Certificat, etc.

4. Chemins de stockage (Storage paths) - Optionnel

Organisez physiquement vos documents archivés sur le disque.

6. Test avec un fichier Office

Méthode 1 : Upload via l'interface web

  1. Cliquez sur le bouton "Upload" en haut à droite
  2. Sélectionnez un document Word, Excel ou PowerPoint
  3. Attendez le traitement (quelques secondes à quelques minutes)
  4. Vérifiez que le document apparaît dans la liste
  5. Ouvrez-le et testez la recherche de texte

Méthode 2 : Dépôt dans le dossier consume

# Copiez un fichier dans le dossier consume
cp ~/document-test.docx /opt/paperless-ngx/consume/

# Surveillez les logs du traitement
docker compose logs -f webserver

Le fichier sera automatiquement détecté, traité et supprimé du dossier consume une fois indexé.

7. Commandes utiles

Gestion du stack :

# Voir les logs
docker compose logs -f

# Redémarrer tous les conteneurs
docker compose restart

# Arrêter le stack
docker compose stop

# Démarrer le stack
docker compose start

# Redéployer après modification du docker-compose.yml
docker compose up -d

# Mettre à jour les images
docker compose pull
docker compose up -d

Logs spécifiques :

# Logs de Paperless-ngx
docker compose logs -f webserver

# Logs de PostgreSQL
docker compose logs -f db

# Logs de Gotenberg (conversion Office)
docker compose logs -f gotenberg

# Logs de Tika (extraction texte)
docker compose logs -f tika

Gestion des utilisateurs :

# Créer un utilisateur supplémentaire
docker exec -it paperless-ngx python3 manage.py createsuperuser

# Changer le mot de passe d'un utilisateur
docker exec -it paperless-ngx python3 manage.py changepassword admin

8. Architecture de la solution

Service Rôle Port
Paperless-ngx Application GED principale avec interface web 8095
PostgreSQL Base de données pour métadonnées et index Interne
Redis Cache et file d'attente pour traitement asynchrone Interne
Gotenberg Conversion de fichiers Office (docx, xlsx, pptx) vers PDF Interne
Tika Extraction de texte et métadonnées de tous types de fichiers Interne

Flux de traitement d'un document :

  1. 📄 Document déposé dans consume/ ou uploadé via l'interface
  2. 🔄 Tika extrait le texte et les métadonnées
  3. 📋 Gotenberg convertit les fichiers Office en PDF si nécessaire
  4. 👁️ OCR (Tesseract) analyse les images et PDFs scannés
  5. 💾 Document stocké dans media/, métadonnées dans PostgreSQL
  6. 🔍 Document indexé et recherchable instantanément

Fonctionnalités principales

✅ Ce que Paperless-ngx peut faire :

  • 📸 OCR multilingue sur documents scannés
  • 📁 Traitement automatique des fichiers Office (Word, Excel, PowerPoint)
  • 🔍 Recherche plein texte ultra-rapide
  • 🏷️ Organisation avec tags, correspondants et types de documents
  • 📱 Application mobile (Android/iOS) pour scanner directement
  • 📧 Import automatique depuis email (via fetchmail/getmail)
  • 🔄 Règles de traitement automatiques
  • 📤 Export en masse (PDF, ZIP)
  • 👥 Multi-utilisateurs avec permissions
  • 🌐 API REST complète pour intégrations
  • 🔒 Stockage local sécurisé (RGPD compliant)

Dépannage rapide

Problème Solution
Conteneurs ne démarrent pas Vérifiez les logs : docker compose logs
Erreur de permissions Vérifiez les UID:GID dans le docker-compose.yml et les permissions des dossiers
PostgreSQL ne démarre pas Vérifiez l'espace disque et les logs : docker compose logs db
OCR ne fonctionne pas Vérifiez la langue configurée dans PAPERLESS_OCR_LANGUAGE
Fichiers Office non traités Vérifiez les logs de Gotenberg et Tika
Interface web inaccessible Vérifiez le port 8095 et les logs du webserver

Réinitialisation complète (⚠️ PERTE DE DONNÉES) :

docker compose down -v
sudo rm -rf /opt/paperless-ngx/{postgres,redis,data,media}/*
docker compose up -d

Conclusion

Vous avez maintenant une installation complète de Paperless-ngx opérationnelle ! Cette solution vous permet de :

  • ✅ Dématérialiser tous vos documents papier
  • ✅ Organiser factures, contrats et courriers administratifs
  • ✅ Rechercher instantanément dans tous vos documents
  • ✅ Traiter automatiquement les fichiers Office
  • ✅ Respecter le RGPD avec hébergement local

🎯 Paperless-ngx transforme votre chaos documentaire en bibliothèque numérique parfaitement organisée !

Pour aller plus loin

  • 🔒 Sécurité : Configurez un reverse proxy (Nginx, Traefik) avec HTTPS
  • 📧 Email : Intégrez fetchmail pour import automatique des pièces jointes
  • 📱 Mobile : Installez l'app Paperless Mobile pour scanner avec votre smartphone
  • 💾 Sauvegarde : Automatisez les backups des dossiers data/, media/ et postgres/
  • 🔄 Automatisation : Créez des règles de traitement pour tag et classement automatiques
  • 🌐 Accès distant : Utilisez Cloudflare Tunnel ou Tailscale pour accès sécurisé depuis l'extérieur
à Aucun commentaire:
Libellés : , , , , , , , , , , ,
Inscription à : Commentaires (Atom)

Déployer Paperless-ngx sur Debian 13 avec Docker et Portainer

Installation de Paperless-ngx avec Docker Compose Installation de Paperless-ngx avec Docker Compose Déployez votre GED pers...