Qu’est-ce que Paperless-ngx ?

Paperless-ngx est un système de gestion électronique de documents (GED) libre, conçu pour l’auto-hébergement. Vous lui donnez un PDF ou une photo de document : il en extrait le texte par reconnaissance optique de caractères (OCR), l’indexe, propose un classement et conserve l’original à côté d’une version archivée.

Le projet est la suite communautaire de Paperless et de Paperless-ng. Il se déploie avant tout avec Docker, et l’image est publiée sur le registre de conteneurs GitHub.

Pourquoi l’adopter

Retrouver un document par son contenu

L’OCR rend le texte de chaque page interrogeable. Plus besoin de se rappeler du nom du fichier ou du dossier : la barre de recherche retrouve « contrat chaudière » ou un numéro de client à l’intérieur même d’un scan.

Un classement qui se fait presque tout seul

Chaque document peut recevoir des étiquettes, un correspondant (l’émetteur), un type de document et un chemin de stockage. Des règles de correspondance, ou un apprentissage à partir de vos propres classements, attribuent ces métadonnées automatiquement aux nouveaux documents. Le tri manuel se limite aux cas inédits.

Une porte d’entrée pour tous vos papiers

• Dossier surveillé : tout fichier déposé dans le dossier consume est traité. Un scanner réseau qui envoie vers un partage SMB ou NFS suffit à alimenter la GED.
• Boîtes e-mail : des règles de messagerie récupèrent les pièces jointes (factures, relevés) et les classent.
• Glisser-déposer depuis l’interface web, et une API REST pour les automatisations et applications tierces.

Des documents vivants, pas un simple dépôt de PDF

Champs personnalisés (montant, échéance, numéro de compte), notes, versions d’un document, vues enregistrées affichées sur le tableau de bord, workflows déclenchés à l’arrivée ou à la modification d’un document : l’outil sert aussi de pense-bête administratif, par exemple pour suivre les factures impayées.

Vos données restent chez vous

Aucun abonnement, aucun envoi vers un cloud tiers : les documents sont stockés sur votre serveur. L’application gère plusieurs utilisateurs avec des droits par document, ce qui permet de partager une GED familiale tout en gardant certains dossiers privés. Le contenu est stocké dans des formats ouverts, et un export complet est intégré.

Prérequis

• Un serveur ou mini-PC sous Linux (ou un NAS compatible Docker) ; Paperless-ngx tourne sur architectures amd64, arm et arm64.
• Docker et le plugin Docker Compose (docker compose). Suivez le guide d’installation officiel de Docker pour votre distribution.
• De la marge en mémoire et en processeur : l’OCR est gourmand, surtout lors de l’import d’une grosse archive. Prévoyez plusieurs Go de RAM libres.
• De l’espace disque pour les originaux et les versions archivées, soit grossièrement le double de vos fichiers.

Installation avec Docker Compose

Deux voies existent. Dans les deux cas, on obtient la même pile de trois conteneurs : webserver (l’application), db (PostgreSQL, recommandé pour une nouvelle installation) et broker (file de tâches Valkey, compatible Redis).

Option 1 : le script d’installation (le plus rapide)

Le projet fournit un script interactif qui pose quelques questions (port, dossier de données, base de données, fuseau horaire, langue de l’OCR, utilisateur administrateur), télécharge les fichiers et lance la pile :

bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Option 2 : installation manuelle, pas à pas

Cette voie donne la maîtrise complète des fichiers et s’intègre mieux à une gestion par dépôt Git ou par Portainer.

1. Créer le dossier du projet

sudo mkdir -p /opt/paperless/{consume,export}
sudo chown -R $USER:$USER /opt/paperless
cd /opt/paperless

2. Récupérer les fichiers officiels : le compose PostgreSQL, le fichier d’environnement et le fichier .env qui fixe le nom du projet.

B=https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose
curl -fsSL $B/docker-compose.postgres.yml -o docker-compose.yml
curl -fsSL $B/docker-compose.env          -o docker-compose.env
curl -fsSL $B/.env                        -o .env

Pour lire aussi les documents Office (Word, Excel, LibreOffice), prenez à la place le fichier docker-compose.postgres-tika.yml qui ajoute les conteneurs Tika et Gotenberg.

3. Vérifier le docker-compose.yml. Voici, sans ses commentaires, la version officielle au moment de la rédaction :

docker-compose.yml

services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql

volumes:
  data:
  media:
  pgdata:
  redisdata:

Trois points à connaître :

• 8000:8000 : le port de gauche est celui exposé sur votre machine. Changez-le (par exemple 8283:8000) si 8000 est déjà pris.
• ./consume et ./export sont des dossiers visibles sur l’hôte ; data et media sont des volumes gérés par Docker. Pour garder tous les documents dans un dossier précis (un montage NAS, par exemple), remplacez media:/usr/src/paperless/media par /chemin/vers/media:/usr/src/paperless/media.
• Le mot de passe PostgreSQL par défaut est paperless. La base n’est pas exposée hors du réseau Docker, mais si vous le changez, modifiez aussi PAPERLESS_DBPASS du service webserver.

4. Régler le fichier d’environnement. Ouvrez docker-compose.env : seule la clé secrète est active par défaut, et elle doit être remplacée.

docker-compose.env

PAPERLESS_SECRET_KEY=remplacez-par-une-longue-chaine-aleatoire
PAPERLESS_TIME_ZONE=Europe/Paris
PAPERLESS_OCR_LANGUAGE=fra+eng
#PAPERLESS_URL=https://paperless.exemple.fr
#USERMAP_UID=1000
#USERMAP_GID=1000

Pour générer la clé : openssl rand -base64 48.

5. Télécharger les images et démarrer

docker compose pull
docker compose up -d
docker compose ps

Le premier démarrage prend une à deux minutes (migrations de la base). Suivez-le avec docker compose logs -f webserver.

6. Créer le compte administrateur

docker compose run --rm webserver createsuperuser

Saisissez l’identifiant, l’e-mail (facultatif) et le mot de passe, puis ouvrez http://ADRESSE_DU_SERVEUR:8000 et connectez-vous. Le compte créé ici est le seul au départ.

Réglages à faire dès le départ

Après toute modification du fichier d’environnement : docker compose up -d recrée le conteneur avec les nouvelles valeurs.

Premiers pas

1. Déposer des documents : glissez-les dans l’interface, ou copiez-les dans /opt/paperless/consume. Ils apparaissent après traitement, avec l’étiquette « Inbox » si elle existe.
2. Créer vos attributs dans Gérer : correspondants (EDF, impôts, banque), types (facture, contrat, relevé), étiquettes. Pour chacun, choisissez l’algorithme de correspondance : « Automatique » s’appuie sur ce que vous avez déjà classé.
3. Corriger les premiers classements : l’apprentissage automatique s’affine avec vos corrections. Quelques dizaines de documents suffisent à améliorer nettement les propositions.
4. Enregistrer des vues (documents fiscaux, factures impayées) et les épingler sur le tableau de bord.
5. Brancher le scanner ou une règle de messagerie pour automatiser l’arrivée des documents.

Sauvegarde et mise à jour

Sauvegarder

Ne vous contentez pas de copier les volumes Docker pendant que la base tourne. Utilisez l’exporteur intégré, qui produit les fichiers d’origine, les métadonnées et un manifeste restaurable :

docker compose exec -T webserver document_exporter ../export --no-progress-bar

Le résultat se trouve dans /opt/paperless/export : copiez ce dossier vers un second support, de préférence hors de la machine. Vous pouvez planifier la commande par cron chaque nuit. Pour restaurer, le conteneur propose la commande symétrique document_importer.

Mettre à jour

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

Lisez les notes de version avant les changements de version majeure : certaines évolutions de PostgreSQL ou de la base demandent une manipulation. Si vous voulez éviter les surprises, remplacez latest par un numéro de version précis dans le fichier compose et montez-le vous-même.

Sécurité et accès distant

• Ne publiez pas le port 8000 directement sur Internet. Placez un reverse proxy HTTPS (Nginx, Apache, Caddy, Traefik) devant, et renseignez PAPERLESS_URL.
• Pour un usage purement domestique, un VPN (WireGuard, Tailscale, ZeroTier) donne accès à la GED depuis l’extérieur sans l’exposer.
• Créez un compte par personne plutôt que de partager le compte administrateur, et utilisez les permissions par document pour les dossiers sensibles.
• Vos documents contiennent des données personnelles et financières : chiffrez le support des sauvegardes.

Pour conclure

Une heure suffit pour monter Paperless-ngx : quelques fichiers, trois conteneurs, un compte administrateur. Le vrai gain vient ensuite, quand un courrier numérisé retrouve tout seul son étiquette, son correspondant et sa date. Une fois l’habitude prise, le papier passe au scanner dès son arrivée et la question « où ai-je mis cette facture ? » disparaît.