Déployer Paperless-ngx avec Docker en 2026 : tutoriel complet (OCR, consume folder, HTTPS)

Vous croulez sous les factures, contrats, fiches de paie et courriers administratifs en papier ou en PDF éparpillés ? Paperless-ngx transforme ce chaos en une bibliothèque documentaire propre, recherchable et sauvegardée. C’est une GED (gestion électronique de documents) open source qui océrise automatiquement vos documents — il reconnaît le texte des PDF scannés et des images — puis les classe par correspondant, type et date. Vous déposez un scan, et quelques secondes plus tard il est indexé, cherchable et rangé selon vos règles.

Le tout sur votre serveur, sans abonnement. Dans ce tutoriel, on déploie Paperless-ngx via Docker Compose avec son OCR et son dossier de consommation (le « consume folder » où tout document déposé est ingéré automatiquement), derrière un reverse proxy Caddy en HTTPS.

Prérequis

Un serveur ou VPS sous Ubuntu 24.04 (ou Debian 12) avec 2 Go de RAM minimum (l’OCR est gourmand ; 4 Go sont plus confortables pour de gros volumes). Un VPS chez Hetzner ou Infomaniak convient bien, mais Paperless-ngx tourne aussi très bien sur un NAS ou un mini-PC à la maison.
Docker et Docker Compose installés (commande à l’étape 1).
Un nom de domaine dont vous contrôlez le DNS. On utilisera docs.exemple.fr.
Les ports 80 et 443 ouverts pour Let’s Encrypt et le trafic HTTPS.

Étape 1 : Installer Docker et Docker Compose

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER

Déconnectez-vous/reconnectez-vous, puis vérifiez :

docker --version && docker compose version

Étape 2 : Configurer le DNS

Chez votre fournisseur DNS, créez un enregistrement A (et AAAA si IPv6) :

Type	Nom	Valeur
A	`docs.exemple.fr`	`203.0.113.10`

Vérifiez la propagation :

dig +short docs.exemple.fr

Étape 3 : Créer le réseau Docker partagé

docker network create web

Si vous suivez déjà notre tutoriel reverse proxy Caddy, ce réseau existe peut-être déjà : ignorez l’erreur éventuelle.

Étape 4 : Préparer le dossier et le fichier .env

Paperless-ngx s’appuie sur quatre conteneurs : l’application web, une base PostgreSQL, Redis (file de tâches), et Gotenberg + Tika pour convertir et lire certains formats. La configuration passe par un fichier .env.

mkdir -p ~/paperless && cd ~/paperless
nano paperless.env

# --- Sécurité ---
# Clé secrète Django (générée à l'étape suivante)
PAPERLESS_SECRET_KEY=remplacez_par_la_cle_generee

# --- URL publique (indispensable derrière un reverse proxy HTTPS) ---
PAPERLESS_URL=https://docs.exemple.fr
PAPERLESS_CSRF_TRUSTED_ORIGINS=https://docs.exemple.fr

# --- OCR : langues reconnues (fra = français, eng = anglais) ---
PAPERLESS_OCR_LANGUAGE=fra+eng

# --- Base PostgreSQL ---
PAPERLESS_DBHOST=postgres
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=remplacez_par_un_mot_de_passe_long

# --- Redis ---
PAPERLESS_REDIS=redis://redis:6379

# --- Tika / Gotenberg pour les documents Office ---
PAPERLESS_TIKA_ENABLED=1
PAPERLESS_TIKA_GOTENBERG_ENDPOINT=http://gotenberg:3000
PAPERLESS_TIKA_ENDPOINT=http://tika:9998

# --- Divers ---
PAPERLESS_TIME_ZONE=Europe/Paris
# Reclasse automatiquement le dossier de consommation par sous-dossiers
PAPERLESS_CONSUMER_RECURSIVE=true
USERMAP_UID=1000
USERMAP_GID=1000

Générez la clé secrète et un mot de passe de base :

echo "PAPERLESS_SECRET_KEY : $(openssl rand -base64 48)"
echo "PAPERLESS_DBPASS : $(openssl rand -base64 32)"

Reportez ces valeurs dans paperless.env.

Étape 5 : Le docker-compose.yml de Paperless-ngx

nano docker-compose.yml

services:
  redis:
    image: docker.io/library/redis:7-alpine
    container_name: paperless_redis
    restart: unless-stopped
    volumes:
      - redisdata:/data
    networks:
      - paperless-internal

  postgres:
    image: docker.io/library/postgres:16-alpine
    container_name: paperless_postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${PAPERLESS_DBPASS}
    env_file:
      - paperless.env
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - paperless-internal

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    restart: unless-stopped
    depends_on:
      - postgres
      - redis
      - gotenberg
      - tika
    env_file:
      - paperless.env
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    healthcheck:
      test: ["CMD", "curl", "-fs", "-S", "--max-time", "2", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 5
    networks:
      - web
      - paperless-internal

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

  tika:
    image: docker.io/apache/tika:latest
    container_name: paperless_tika
    restart: unless-stopped
    networks:
      - paperless-internal

volumes:
  data:
  media:
  pgdata:
  redisdata:

networks:
  web:
    external: true
  paperless-internal:

Le service webserver est sur deux réseaux : paperless-internal (base, Redis, Gotenberg, Tika) et web (pour Caddy). Les volumes ./consume et ./export sont des dossiers locaux : le premier est le dossier de consommation, le second sert aux exports/sauvegardes. Aucune section ports: sur le webserver : tout passe par le reverse proxy.

Étape 6 : Le Caddyfile pour le HTTPS automatique

Si vous avez déjà un Caddy, ajoutez le bloc de site. Sinon, créez un dossier Caddy :

mkdir -p ~/caddy && cd ~/caddy
nano Caddyfile

{
    email admin@exemple.fr
}

docs.exemple.fr {
    encode gzip zstd

    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
        -Server
    }

    # Paperless accepte de gros fichiers PDF scannés
    request_body {
        max_size 200MB
    }

    reverse_proxy paperless:8000
}

Le port interne de Paperless-ngx est 8000.

Puis le docker-compose.yml de Caddy :

nano docker-compose.yml

services:
  caddy:
    image: caddy:2-alpine
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - web

volumes:
  caddy_data:
  caddy_config:

networks:
  web:
    external: true

Étape 7 : Lancer les services et créer le compte admin

Démarrez Paperless (le premier lancement télécharge plusieurs images et les modèles OCR), puis Caddy :

cd ~/paperless && docker compose up -d
cd ~/caddy && docker compose up -d

Créez le superutilisateur (compte administrateur) avec la commande dédiée :

cd ~/paperless
docker compose run --rm webserver createsuperuser

Saisissez un nom d’utilisateur, un email et un mot de passe fort. Visitez ensuite https://docs.exemple.fr et connectez-vous : l’interface de Paperless-ngx s’affiche.

Étape 8 : Le dossier de consommation (consume folder)

C’est la fonctionnalité phare. Tout fichier déposé dans le dossier ~/paperless/consume est automatiquement ingéré, océrisé, indexé puis supprimé du dossier (l’original est conservé dans la médiathèque interne). Testez-le :

# Copiez un PDF de test dans le dossier de consommation
cp ~/un-document.pdf ~/paperless/consume/
# Suivez l'ingestion dans les logs
docker compose -f ~/paperless/docker-compose.yml logs -f webserver

Quelques secondes plus tard, le document apparaît dans l’interface, son texte est cherchable.

Pour aller plus loin, vous pouvez monter ce dossier de consommation en partage réseau (Samba/NFS) : votre scanner ou votre imprimante multifonction peut alors « scanner vers le dossier », et chaque numérisation atterrit directement dans Paperless. Vous pouvez aussi automatiser l’import des PDF reçus par email via les règles de l’application.

Étape 9 : Régler le classement automatique

Paperless-ngx range les documents par correspondants, types de document et étiquettes. Dans Administration → Règles de traitement, créez des règles qui appliquent automatiquement un correspondant ou une étiquette selon le contenu OCR (par exemple : tout document contenant « EDF » reçoit le correspondant « EDF » et l’étiquette « Énergie »). Plus vous traitez de documents, plus le moteur d’auto-suggestion s’affine.

Étape 10 : Sauvegardes

Deux options. La plus robuste est l’export natif de Paperless, qui produit une archive complète (documents + base + métadonnées) réimportable :

nano ~/paperless/backup.sh

#!/bin/bash
set -euo pipefail
cd "$HOME/paperless"
STAMP=$(date +%Y%m%d-%H%M%S)

# Export natif Paperless (documents + métadonnées) dans ./export
docker compose exec -T webserver document_exporter ../export -d

# Archive l'export daté
tar -czf "$HOME/paperless/paperless-export-$STAMP.tar.gz" -C "$HOME/paperless/export" .

# Conserve 14 jours d'archives
find "$HOME/paperless" -maxdepth 1 -name 'paperless-export-*.tar.gz' -mtime +14 -delete

chmod +x ~/paperless/backup.sh
(crontab -l 2>/dev/null; echo "0 3 * * * $HOME/paperless/backup.sh") | crontab -

Vos documents administratifs sont irremplaçables : envoyez ces archives hors-site et chiffrées avec notre guide sauvegarde automatique avec Restic et Backblaze.

Vérification finale

# Les conteneurs tournent
docker compose -f ~/paperless/docker-compose.yml ps

# Le HTTP redirige vers HTTPS (code 308)
curl -sI http://docs.exemple.fr | head -1

# Le HTTPS répond
curl -sI https://docs.exemple.fr | head -1

Sécurité et durcissement

Pare-feu UFW strict. N’ouvrez que 80, 443 et SSH. Les ports internes (PostgreSQL, Redis, Tika, Gotenberg) ne sont jamais exposés.
Mot de passe admin fort et, idéalement, comptes utilisateurs séparés avec permissions par document.
Clé secrète protégée. paperless.env contient PAPERLESS_SECRET_KEY et le mot de passe de base : chmod 600 paperless.env, ne le versionnez jamais.
Mises à jour maîtrisées. Certaines versions migrent la base : faites un export (étape 10) avant, puis docker compose pull && docker compose up -d. Voir aussi installer et sécuriser un VPS Ubuntu.

Pièges courants et dépannage

OCR en anglais sur des documents français. PAPERLESS_OCR_LANGUAGE ne contient pas fra. Mettez fra+eng et relancez ; pour l’existant, refaites passer les documents.
Erreur CSRF à la connexion. PAPERLESS_URL et PAPERLESS_CSRF_TRUSTED_ORIGINS ne correspondent pas à l’URL HTTPS publique. Corrigez-les et redémarrez.
Le dossier de consommation n’ingère rien. Vérifiez les permissions (USERMAP_UID/GID doit correspondre au propriétaire du dossier) et les logs. Sur un partage réseau, activez PAPERLESS_CONSUMER_POLLING car inotify ne fonctionne pas toujours.
Manque de RAM pendant l’OCR. L’océrisation de gros PDF est lourde : ajoutez de la RAM/du swap, ou limitez les tâches OCR parallèles.

FAQ

Qu’est-ce que l’OCR et pourquoi est-ce essentiel ici ?

L’OCR (reconnaissance optique de caractères) extrait le texte d’un document scanné ou d’une image. C’est ce qui rend un PDF scanné cherchable : sans OCR, un scan n’est qu’une image, impossible à retrouver par son contenu. Paperless-ngx océrise automatiquement chaque document ingéré, dans les langues que vous configurez, ce qui vous permet de retrouver n’importe quel papier par un mot qu’il contient.

Comment fonctionne exactement le dossier de consommation ?

C’est un dossier surveillé : tout fichier que vous y déposez (manuellement, par scanner, par partage réseau) est automatiquement ingéré, océrisé, indexé et classé selon vos règles, puis retiré du dossier. C’est la façon la plus simple d’alimenter votre GED : « scanner vers le dossier » et oublier.

Puis-je faire scanner directement mon imprimante multifonction vers Paperless ?

Oui. Montez le dossier de consommation en partage réseau (Samba/NFS), puis configurez votre scanner ou imprimante multifonction pour « scanner vers ce dossier ». Chaque numérisation est traitée automatiquement. Pensez à activer le polling si inotify ne détecte pas les fichiers sur un partage réseau.

À quoi servent Gotenberg et Tika ?

Ils étendent les formats pris en charge : Tika extrait le contenu des documents Office (Word, Excel…) et Gotenberg les convertit en PDF pour un archivage uniforme. Sans eux, Paperless gère parfaitement PDF et images, mais pas les fichiers bureautiques. Optionnels mais recommandés si vous archivez de l’Office.

Mes documents sont-ils stockés en clair sur le serveur ?

Oui, les fichiers sont stockés tels quels dans le volume media (pas de chiffrement au repos par défaut). La protection repose sur le chiffrement du disque et des sauvegardes chiffrées hors-site. Pour des documents très sensibles, chiffrez le volume sous-jacent au niveau du système de fichiers.

Paperless-ngx, Mayan EDMS ou Docspell : lequel choisir ?

Paperless-ngx est le plus populaire et le plus simple à déployer pour un usage personnel ou familial ; Mayan EDMS vise les besoins d’entreprise avec des workflows avancés ; Docspell se distingue sur le traitement et le rapprochement automatiques. Pour la plupart des homelabs, Paperless-ngx est le meilleur point de départ. Notre comparatif Paperless-ngx vs Mayan vs Docspell détaille les différences.