Paperless-ngx : ses documents sur son serveur

Ce guide suit la documentation d'installation de Paperless-ngx, relue le 14 octobre 2026 ; la dernière version publiée est la 3.3.1. Il faut Docker Engine et son extension Compose.

Installer Paperless-ngx

Le projet propose un script interactif qui pose les fichiers et crée le compte. La méthode manuelle ci-dessous fait la même chose et laisse voir chaque fichier.

1. Créez un dossier et placez-vous dedans : mkdir ~/paperless && cd ~/paperless
2. Téléchargez les trois fichiers du dossier docker/compose du dépôt, la variante PostgreSQL, que la documentation conseille pour une nouvelle installation :

wget -O docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env

3. Réglez docker-compose.env comme décrit plus bas.
4. Dans docker-compose.yml, remplacez la ligne "8000:8000" du service webserver par "127.0.0.1:8000:8000", pour que l'interface ne soit joignable que depuis le serveur.
5. Récupérez les images, puis lancez : docker compose pull, puis docker compose up -d.
6. Ouvrez l'interface par le proxy ou un tunnel SSH ; à la première visite, elle demande de créer le compte administrateur.

Le fichier compose lance trois services : Paperless-ngx lui-même, PostgreSQL 18 et un serveur Valkey pour la file des tâches. L'image ghcr.io/paperless-ngx/paperless-ngx:latest suit toujours la dernière version stable, d'après la page d'administration citée plus bas.

Régler docker-compose.env

Le fichier rappelle comment produire la clé : python3 -c "import secrets; print(secrets.token_urlsafe(64))". Laisser la valeur d'exemple permettrait à un tiers de forger une session, prévient la documentation. L'image contient déjà la reconnaissance du français, avec l'anglais, l'allemand, l'italien et l'espagnol.

Envoyer des documents

Un document arrive dans Paperless-ngx de deux façons : glissé dans l'interface web, ou déposé dans le dossier consume à côté du fichier compose, que Paperless-ngx surveille. Un scanner qui enregistre ses fichiers dans ce dossier les fait donc entrer seul. Chaque document est lu, rendu cherchable, puis rangé.

Ouvrir l'interface en HTTPS

Paperless-ngx écoute sur le port 8000. Un proxy inverse lui donne une adresse en HTTPS ; avec Caddy installé sur le système, deux lignes suffisent :

papiers.votre-domaine.fr {
    reverse_proxy 127.0.0.1:8000
}

Mettez alors la même adresse dans PAPERLESS_URL, puis relancez avec docker compose up -d. La mise en place du proxy et du certificat est détaillée dans Un certificat SSL sur son VPS.

Sauvegarder

L'outil d'export de Paperless-ngx copie les documents, la base et les réglages dans le dossier export, d'après la page d'administration :

docker compose exec -T webserver document_exporter ../export

L'option -T évite une erreur quand la commande tourne dans une tâche planifiée, ce que montre Planifier une tâche avec cron. Copiez ensuite le dossier export hors du serveur : une copie qui reste sur la même machine disparaît avec elle.

Mettre à jour

Faites une sauvegarde et attendez qu'aucun document ne soit en cours de traitement. Puis, dans le dossier : docker compose down, docker compose pull, docker compose up -d. Lisez les notes de version avant un changement de version majeure : le passage à la version 3 demandait des étapes manuelles, selon la documentation.

Sur un VPS Hubspace

Docker et Compose sont installés à la livraison, et le compte admin les utilise sans sudo. Le pare-feu ne laisse passer que 22, 80 et 443 depuis Internet : le port 8000 reste fermé même publié par Docker, et l'accès passe par le proxy. Le projet ne fixe pas de minimum chiffré ; la reconnaissance de texte utilise tous les cœurs disponibles, et un gros lot de documents en profite. Le disque principal est sauvegardé chaque jour, avec sept jours de conservation, mais l'export reste votre vraie sauvegarde. Pour vos photos, l'équivalent est Immich. Les serveurs VPS décrivent ce qui est livré.

Questions fréquentes