Héberger Paperless-ngx sur VPS : guide complet 2026

Paperless-ngx est la fork communautaire la plus active de Paperless — un système de gestion électronique de documents (GED) qui indexe vos PDF et images scannées, en extrait le texte via OCR, et vous permet de les retrouver par mot-clé, date, correspondant ou tag.

Par rapport aux alternatives (Mayan EDMS, OpenDocMan), Paperless-ngx se distingue par sa simplicité d'installation (Docker Compose en moins de 10 minutes), son interface web réactive en React, et son support de l'OCR multilingue via Tesseract.

Le projet est maintenu par sa communauté et publie des releases régulières — vérifiez la version courante sur la page des releases GitHub avant d'installer.

Cas d'usage typiques :
- Archive des factures fournisseurs pour une micro-entreprise ou une PME
- Dossier médical personnel ou familial (ordonnances, analyses, courriers)
- Gestion des documents d'une association ou d'une copropriété
- Archive des contrats et des baux pour une agence immobilière

Paperless-ngx est plus gourmand qu'il n'y paraît, surtout à l'import. Le traitement OCR d'un PDF multi-pages sollicite intensément le CPU — c'est la principale source de timeouts sur les petites configurations.

Configuration minimale recommandée :
- CPU : 2 vCPU (le traitement OCR est mono-thread par tâche, mais plusieurs tâches peuvent tourner en parallèle)
- RAM : 2 Go minimum ; 4 Go pour un usage confortable
- Stockage : SSD, 20 Go minimum pour l'application + prévoir l'espace pour vos documents
- OS : Debian 12 ou Ubuntu 22.04/24.04

Ce qui crée des timeouts sur les petits VPS : les PDFs scannés à haute résolution (300+ DPI) ou comportant de nombreuses pages (50+) peuvent dépasser le PAPERLESS_TASK_WORKERS_TIMEOUT par défaut (1 800 secondes). La section dédiée plus bas couvre la résolution.

L'installation officielle recommandée utilise Docker Compose avec trois services : paperless-ngx (l'application), redis (le broker de tâches) et postgresql (la base de données).

# Créer le répertoire de travail
mkdir -p /opt/paperless && cd /opt/paperless

# Télécharger le fichier docker-compose officiel
curl -fsSL https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml \
  -o docker-compose.yml

# Créer le fichier d'environnement
cat > .env <<'EOF'
PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)
PAPERLESS_URL=https://paperless.votre-domaine.com
PAPERLESS_TIME_ZONE=Europe/Paris
PAPERLESS_OCR_LANGUAGE=fra+eng+ara
PAPERLESS_REDIS=redis://broker:6379
PAPERLESS_DBHOST=db
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=changeme
POSTGRES_DB=paperless
POSTGRES_USER=paperless
POSTGRES_PASSWORD=changeme
EOF

# Démarrer
docker compose up -d

# Créer le compte admin
docker compose exec webserver python manage.py createsuperuser

L'interface est accessible sur le port 8000 après environ 60 secondes de démarrage. Configurez ensuite votre reverse proxy (nginx ou Traefik) pour exposer le service avec TLS.

L'OCR est le cœur de Paperless-ngx. Sa configuration détermine la qualité de l'indexation et la capacité à retrouver vos documents.

Langues Tesseract disponibles : le paramètre PAPERLESS_OCR_LANGUAGE accepte les codes de langue Tesseract séparés par +. Pour un usage franco-marocain :

PAPERLESS_OCR_LANGUAGE=fra+ara+eng

Cela active le français, l'arabe et l'anglais. Les données de langue Tesseract sont téléchargées automatiquement au premier démarrage si elles ne sont pas présentes dans l'image.

Mode OCR : PAPERLESS_OCR_MODE contrôle quand l'OCR est appliqué :
- skip (défaut) : n'OCRise pas les PDF qui ont déjà du texte sélectionnable
- redo : réapplique l'OCR même sur les PDF avec texte (utile pour améliorer la qualité)
- force : OCRise toujours, même si du texte existe

Pour la plupart des usages, skip est le bon choix — il évite de re-traiter inutilement les PDF natifs (contrats, factures générées par un logiciel).

La détection automatique des dates est l'une des fonctionnalités les plus puissantes de Paperless-ngx — et l'une des plus frustrantes quand elle ne fonctionne pas. Par défaut, Paperless-ngx essaie de détecter la date du document dans son contenu textuel et son nom de fichier. Plusieurs raisons peuvent mener à une date incorrecte ou absente.

Problème 1 : La date est en format non reconnu. Paperless-ngx détecte les formats courants (DD/MM/YYYY, YYYY-MM-DD, etc.) mais peut rater des formats ambigus (08/09/2025 : le 8 septembre ou le 9 août ?).

Solution : configurer explicitement le format de date attendu :

PAPERLESS_DATE_ORDER=DMY  # DD/MM/YYYY en priorité (format français)

Problème 2 : Le document a plusieurs dates et la mauvaise est choisie. Par exemple, une facture qui mentionne la date de la prestation ET la date d'émission — Paperless-ngx prend la première trouvée.

Solution : utiliser le champ de date manuel dans l'interface web pour corriger les documents mal datés, ou configurer des règles de correspondance (Matching rules) qui assignent une date depuis le nom de fichier.

Problème 3 : La date de création du fichier est utilisée à la place. Quand aucune date n'est trouvée dans le contenu, Paperless-ngx utilise la date de modification du fichier comme fallback — ce qui peut être très trompeur pour des documents anciens scannés récemment.

Solution : nommer les fichiers d'import avec la date du document (YYYY-MM-DD_nom-document.pdf) — Paperless-ngx détecte ce format dans le nom de fichier avant d'analyser le contenu.

Sur un VPS avec 1 ou 2 vCPU, le traitement OCR de documents volumineux peut dépasser le timeout par défaut et laisser le document en statut « En attente de traitement » indéfiniment.

Diagnostic : vérifier les logs du worker :

docker compose logs celery --tail=50

Les lignes SoftTimeLimitExceeded confirment un timeout.

Résolution — trois leviers :

1. Augmenter le timeout des tâches :

PAPERLESS_TASK_WORKERS_TIMEOUT=3600  # 1 heure (défaut : 1800s)

2. Réduire la résolution d'import. Si vous scannez vous-même les documents, 200 DPI est suffisant pour un OCR de qualité — 300 DPI double le temps de traitement sans amélioration perceptible pour du texte standard.

3. Limiter le traitement parallèle :

PAPERLESS_TASK_WORKERS=1       # 1 worker OCR à la fois (défaut : 1)
PAPERLESS_THREADS_PER_WORKER=1  # 1 thread par worker (défaut : auto)

Sur un VPS 2 vCPU, traiter deux documents en parallèle peut provoquer des timeouts que traiter le même volume séquentiellement éviterait.

4. Optimiser le préprocessing PDF :

PAPERLESS_OCR_USER_ARGS={"optimize": 1, "pdfa-image-compression": "jpeg"}

Ceci compresse les images dans les PDFs avant traitement, réduisant la charge mémoire et CPU.

Paperless-ngx gère deux types de données critiques : la base de données PostgreSQL (métadonnées, tags, correspondants, règles) et les fichiers documents. Les deux doivent être sauvegardés.

Script de sauvegarde quotidien :

#!/bin/bash
BACKUP_DIR="/backups/paperless/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Dump PostgreSQL
docker compose exec -T db pg_dump -U paperless paperless \
  | gzip > "$BACKUP_DIR/db.sql.gz"

# Export natif Paperless (inclut config et documents)
docker compose exec -T webserver document_exporter /usr/src/paperless/export
tar -czf "$BACKUP_DIR/export.tar.gz" /opt/paperless/export/

# Rotation — garder 14 jours
find /backups/paperless -maxdepth 1 -type d -mtime +14 -exec rm -rf {} +

echo "Sauvegarde terminée : $BACKUP_DIR"

Planifier ce script en cron (0 3 * * * pour 3h du matin), et vérifier que les backups arrivent bien sur un stockage externe au VPS (rsync vers un bucket S3 ou un autre serveur).

Paperless-ngx suit un rythme de releases régulier (toutes les 4 à 8 semaines). La mise à jour est simple avec Docker Compose :

# Tirer la nouvelle image
docker compose pull

# Redémarrer les services (les migrations de base de données s'appliquent automatiquement)
docker compose up -d

# Vérifier que tout est OK
docker compose logs webserver --tail=20

Avant chaque mise à jour majeure : lire le CHANGELOG sur GitHub — les versions majeures (v2.x → v3.x) peuvent nécessiter des étapes de migration supplémentaires.

Surveillance : Paperless-ngx expose des métriques Prometheus sur /metrics (nécessite PAPERLESS_ENABLE_UPDATE_CHECK=true). Une alerte sur paperless_documents_total qui n'augmente plus peut signaler un problème de traitement silencieux.