Migrer de Papermerge vers Paperless-ngx

• Correctifs de sécurité absents : toute vulnérabilité découverte après l'archivage restera ouverte — FastAPI et ses dépendances publient plusieurs advisories par mois
• Compatibilité Python en recul : les nouvelles versions de Python abandonnent des API dépréciées ; une mise à jour de l'OS suffit à casser l'environnement
• Plugins et intégrations orphelins : les connecteurs tiers (scanners, clients mail, webhooks) ne seront plus mis à jour pour suivre l'évolution de l'API REST Papermerge
• Aucune migration de schéma officielle : si un bug de base de données est découvert, aucun correctif ne viendra du dépôt archivé
• Prise en charge du support contractuel impossible : aucun éditeur ne couvrira une installation sur un projet archivé
• Écosystème qui se referme : les images Docker officielles cessent d'être publiées, et les images non officielles introduisent un risque de supply chain

• OCR multi-langues via Tesseract : français, arabe, espagnol, anglais et des dizaines d'autres langues configurables par variable d'environnement
• Tags hiérarchiques : organisation fine des documents avec héritage de règles d'assignation automatique
• Correspondants : identification des expéditeurs/destinataires récurrents, assignation automatique par règle
• Stockage compatible S3 : archivage des originaux vers un bucket S3 ou compatible (MinIO, Garage) sans modifier l'interface
• API REST documentée : intégration avec des workflows externes (n8n, scripts cURL) via /api/documents/
• Dossier de consommation : tout fichier déposé dans /consume est ingéré automatiquement — connexion naturelle aux scanners réseau et clients mail

Papermerge v3 vs Paperless-ngx

Faites défiler le tableau

• VPS : 2 vCPU / 2 Go RAM minimum — 4 Go recommandés si l'OCR tourne en parallèle sur plusieurs documents à l'ingestion
• Docker et Docker Compose : version Docker ≥ 24, Docker Compose ≥ 2.20 (plugin intégré, pas le binaire Python legacy)
• 40 Go de stockage SSD minimum pour les originaux + les données d'index ; prévoir de la marge selon le volume d'archives
• Domaine ou sous-domaine avec un certificat TLS valide — Paperless-ngx n'impose pas HTTPS mais le recommande fortement pour les sessions et les tokens API
• Accès root ou sudo sur le VPS pour installer Docker et configurer le reverse proxy
• Sauvegarde de votre instance Papermerge existante avant toute manipulation : export des documents + dump de la base de données

Migrer de Papermerge vers Paperless-ngx

1. 01

   Exporter vos documents depuis Papermerge

   Dans l'interface Papermerge, rendez-vous dans Documents → Export. Sélectionnez « Tous les documents » et lancez l'export. Papermerge génère un fichier ZIP contenant les originaux (PDF, images) organisés par dossier. Téléchargez ce fichier sur votre poste local ou transférez-le directement sur le futur VPS via scp :

   scp papermerge-export.zip user@votre-vps:/tmp/

2. 02

   Décompresser l'export et préparer le dossier de consommation

   Sur le VPS, décompressez l'archive dans un répertoire temporaire :

   mkdir -p /opt/paperless-import
   unzip /tmp/papermerge-export.zip -d /opt/paperless-import/

   Vous obtenez une arborescence de répertoires et de fichiers. Paperless-ngx consommera ces fichiers via son dossier de consommation dans une étape suivante.

3. 03

   Installer Paperless-ngx via Docker Compose officiel

   Récupérez le fichier docker-compose.yml officiel depuis le dépôt Paperless-ngx :

   mkdir -p /opt/paperless && cd /opt/paperless
   curl -fsSL https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml -o docker-compose.yml
   curl -fsSL https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/.env.example -o .env

   Éditez le fichier .env : posez PAPERLESS_URL, PAPERLESS_SECRET_KEY (chaîne aléatoire longue), PAPERLESS_OCR_LANGUAGE (ex. fra+eng pour français + anglais), et PAPERLESS_TIME_ZONE (Europe/Paris ou votre fuseau).

4. 04

   Démarrer l'instance et créer le compte administrateur

   Lancez les conteneurs en arrière-plan :

   docker compose up -d

   Attendez que le service soit prêt (30 à 60 secondes), puis créez le superutilisateur :

   docker compose exec webserver python3 manage.py createsuperuser

   Connectez-vous sur http://localhost:8000 (ou votre domaine) pour vérifier que l'interface répond.

5. 05

   Importer les documents exportés de Papermerge

   Copiez l'arborescence exportée dans le dossier de consommation de Paperless-ngx. Par défaut, ce dossier est le volume consume déclaré dans docker-compose.yml :

   cp -r /opt/paperless-import/* /opt/paperless/consume/

   Paperless-ngx va détecter automatiquement les nouveaux fichiers et les ingérer via Celery. Vous pouvez surveiller la progression dans l'onglet Logs de l'interface ou via :

   docker compose logs -f celeryworker

   L'OCR et l'indexation prennent quelques secondes à quelques minutes par document selon la taille et la langue.

6. 06

   Configurer le reverse proxy et le TLS

   Exposez Paperless-ngx derrière nginx. Exemple de bloc minimal pour un sous-domaine :

   server {
       listen 443 ssl;
       server_name docs.votre-domaine.com;
       ssl_certificate /etc/letsencrypt/live/docs.votre-domaine.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/docs.votre-domaine.com/privkey.pem;
       location / {
           proxy_pass http://127.0.0.1:8000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }

   Régénérez ou demandez un certificat Let's Encrypt pour ce sous-domaine, puis rechargez nginx.

7. 07

   Vérifier l'OCR et la couverture des documents importés

   Dans l'interface Paperless-ngx, ouvrez quelques documents importés et vérifiez que leur contenu est bien indexé (barre de recherche fonctionnelle). Pour les documents dont l'OCR a échoué (icône d'avertissement), relancez l'OCR manuellement depuis l'interface ou via l'API REST :

   curl -X POST http://localhost:8000/api/documents/<id>/redo_ocr/ \
     -H 'Authorization: Token <votre-token>'

8. 08

   Tester et valider avant de couper l'ancienne instance

   Après l'import complet, vérifiez que le nombre de documents dans Paperless-ngx correspond à celui de votre export Papermerge. Testez la recherche plein texte sur des termes connus, vérifiez les pièces jointes et les originaux téléchargeables. Une fois la validation effectuée, vous pouvez arrêter l'instance Papermerge et supprimer ses conteneurs : docker compose down depuis son répertoire de déploiement.

• OCR : PAPERLESS_OCR_LANGUAGE accepte une liste de codes Tesseract séparés par + (fra+eng+ara). Si votre corpus est multilingue, déclarez toutes les langues dès le début pour que les documents importés soient re-traités correctement
• Stockage S3 : posez PAPERLESS_STORAGE_BACKEND=s3, PAPERLESS_S3_ACCESS_KEY, PAPERLESS_S3_SECRET_KEY et PAPERLESS_S3_BUCKET_NAME pour déporter les originaux vers un bucket compatible — utile pour les corpus de plusieurs gigaoctets sur un VPS au stockage limité
• Règles d'assignation automatique : dans l'interface, créez des règles qui assignent un tag, un correspondant ou un type de document selon le contenu de l'OCR (ex. tout document contenant « facture » → tag Factures, correspondant Fournisseur X)
• Tâches planifiées : le worker Celery gère déjà la consommation automatique ; vérifiez que PAPERLESS_CONSUMER_POLLING est à 0 (inotify) ou à un intervalle raisonnable si inotify n'est pas disponible dans votre environnement Docker

• Scanner réseau : configurez votre scanner pour envoyer les numérisations par SFTP ou SMB dans /consume. Paperless-ngx les ingère dès leur arrivée, sans aucune action manuelle
• Client mail : le consommateur mail (PAPERLESS_EMAIL_HOST, PAPERLESS_EMAIL_PORT) surveille une boîte IMAP et importe automatiquement les pièces jointes PDF des messages correspondant à vos filtres (objet, expéditeur)
• API REST : l'endpoint POST /api/documents/post_document/ accepte un fichier multipart. Depuis n8n, un workflow peut envoyer toute pièce jointe reçue par e-mail directement dans Paperless en quelques secondes. Le token API se génère depuis Réglages → Jetons d'API
• Interface mobile : l'application Paperless Mobile (Android/iOS, open source) se connecte à votre instance auto-hébergée via l'URL et le token API

• Documents importés sans texte OCR : vérifiez que le code de langue Tesseract est correct (PAPERLESS_OCR_LANGUAGE=fra et non fr). Les codes valides sont listés dans la documentation Tesseract. Relancez l'OCR sur les documents concernés via l'interface ou l'API
• Dossier de consommation non surveillé : si vous utilisez un volume Docker monté depuis une partition NFS ou un stockage objet, inotify ne fonctionne pas. Posez PAPERLESS_CONSUMER_POLLING=60 pour un scan toutes les 60 secondes
• Erreur « permission denied » sur /consume : le worker Paperless tourne sous l'UID 1000. Si les fichiers copiés dans /consume appartiennent à root, changez les permissions : chown -R 1000:1000 /opt/paperless/consume/ sur l'hôte
• Import incomplet — documents manquants : Papermerge exporte les documents dans la structure de dossiers visible dans son interface. Les documents dans des dossiers imbriqués profonds sont tous exportés, mais certains noms de fichiers contenant des caractères spéciaux peuvent poser problème. Vérifiez avec find /opt/paperless-import -name '*.pdf' | wc -l et comparez au total de votre instance Papermerge