Ce tutoriel de décembre 2025 est l’un des guides communautaires les plus détaillés pour Paperless-ngx sur ZimaOS, mais il est lié à un paquet BigBear spécifique et à ZimaOS 1.5.3 Plus. Les éléments durables concernent les concepts de stockage et de configuration : attribuer au dossier de consommation un emplacement persistant clair, définir correctement l’URL de l’application, configurer les langues OCR et comprendre les services Tika/Gotenberg facultatifs.
Certains détails de la source nécessitent une mise à jour. La configuration Docker en amont de Paperless-ngx a évolué, PostgreSQL est désormais recommandé pour les nouvelles installations, les fichiers Compose actuels demandent un superutilisateur lors de la première configuration, et Tika/Gotenberg restent facultatifs plutôt qu’obligatoires pour tous les flux de traitement de documents.
Le tutoriel source a été testé sur un ZimaBoard 2 aux ressources modestes
L’auteur a documenté un système basé sur un N150 doté de 16 Go de RAM et exécutant ZimaOS 1.5.3 Plus. L’objectif était un accès au réseau local ou via Tailscale pour un usage domestique, et non une exposition directe au public.
Cette portée est importante, car un déploiement sur Internet public nécessite une stratégie différente en matière de HTTPS, de proxy inverse, d’authentification et de sécurité.
Le guide utilisait l’installation personnalisée de BigBear Paperless-ngx
Le processus source consistait à rechercher le paquet BigBear Paperless-ngx dans l’App Store, à ouvrir le menu déroulant d’installation, puis à choisir Installation personnalisée afin de pouvoir modifier les volumes et les valeurs d’environnement avant le premier démarrage.
Il s’agit d’un processus propre au paquet. Une définition actuelle de l’application peut ajouter, supprimer ou renommer des services et des variables.
Donnez au répertoire de consommation un chemin hôte persistant et clair
/usr/src/paperless/consume comme dossier avec lequel les utilisateurs sont les plus susceptibles d’interagir lorsqu’ils y déposent des documents.La documentation actuelle de Paperless en amont utilise toujours /usr/src/paperless/consume comme destination standard du conteneur et permettait explicitement de modifier le côté hôte de ce montage de liaison.
Le tutoriel définissait les variables d’administration, de consommation, d’OCR et d’URL
Principaux choix de la source :
- nom d’utilisateur et mot de passe administrateur personnalisés ;
- consommation récursive des documents ;
- suppression des originaux du dossier de consommation après ingestion réussie ;
- nettoyage OCR et paramètres de langue ;
- origine approuvée pour CSRF et URL de l’application ;
- Points de terminaison Tika/Gotenberg.
PAPERLESS_URL et les origines CSRF doivent correspondre à la manière dont vous accédez réellement à Paperless
Le tutoriel avertissait qu’une configuration incorrecte de l’URL ou de l’origine pouvait provoquer une erreur 403 lors de la vérification CSRF. Cela reste conceptuellement exact.
La documentation actuelle de Paperless indique PAPERLESS_URL doit être défini lorsque l’application se trouve derrière un proxy inverse et doit représenter le domaine ou l’URL utilisés publiquement. Ne codez pas en dur l’adresse LAN de l’auteur de la source dans une autre installation.
Les paramètres OCR ont également été ajustés dans Paperless
Les langues OCR doivent correspondre aux packs linguistiques disponibles dans le conteneur. L’ajout de langues peut augmenter la taille de l’image ou modifier les exigences liées aux conteneurs sans privilèges, selon le paquet utilisé.
Redémarrer après chaque ajout important dans le dossier de consommation relève du conseil de la source, et non d’une exigence amont
La version actuelle de Paperless-ngx est conçue pour surveiller en continu le répertoire de consommation. La documentation amont n’indique pas que les gros lots nécessitent normalement un redémarrage. Si les documents cessent d’être traités, vérifiez plutôt les autorisations, les journaux du consommateur, la prise en charge des notifications du système de fichiers ainsi que l’état du courtier et des workers, au lieu de faire du redémarrage un rituel obligatoire.
La configuration amont actuelle recommande PostgreSQL pour les nouvelles installations
La configuration Docker actuelle de Paperless-ngx recommande PostgreSQL pour les nouvelles installations, bien que SQLite et MariaDB restent disponibles dans les configurations prises en charge.
Pour une archive documentaire à long terme, la topologie Compose amont actuelle constitue une meilleure référence que de supposer que le service de base de données BigBear 2025 reste exactement inchangé.
Tika et Gotenberg sont facultatifs
La documentation actuelle de Paperless indique que Tika et Gotenberg sont nécessaires pour analyser les documents Office tels que DOC/XLSX/ODT et les fichiers d’e-mails. Si vous n’ingérez que des formats pris en charge par le cœur de Paperless, cette fonctionnalité peut rester désactivée.
Utilisez la configuration Docker actuelle de Paperless-ngx avant de reconstruire manuellement l'ancienne pile BigBear.
Les autorisations du dossier de consommation comptent plus que les redémarrages répétés
La configuration amont actuelle expose USERMAP_UID et USERMAP_GID afin que le conteneur puisse écrire sur les montages bind de l’hôte. Si Paperless détecte un dossier consume mais ne peut pas traiter ou supprimer les fichiers, vérifiez les droits du répertoire mappé et l’identité du conteneur.
Sur ZimaOS, vérifiez également que le chemin consume de l’hôte se trouve sur le stockage géré prévu et qu’il ne s’agit pas d’un mappage de volume en lecture seule.
Supprimer les originaux de /consume n’est pas la même chose que supprimer les documents archivés
La source a activé PAPERLESS_CONSUMER_DELETE_ORIGINALS=true. Cela contrôle ce qu’il advient du fichier d’entrée dans le répertoire consume après une ingestion réussie. Le document archivé géré par Paperless reste dans son stockage multimédia.
Testez ce comportement avec des documents jetables avant de connecter un scanner automatisé ou un service de synchronisation à un dossier de production.
Les réponses concernant Paperless-AI relèvent d’une intégration distincte
Des réponses ultérieures ont indiqué que Paperless-AI pouvait lire les documents via l’API Paperless, mais échouait à analyser les documents ou à écrire les balises avec la configuration OpenAI intégrée. Des utilisateurs ont signalé que Mistral fonctionnait et qu’une configuration OpenAI manuelle permettait de contourner le problème.
Ces réponses ne prouvent pas que l’installation principale de Paperless-ngx est défaillante. Paperless-AI est une intégration tierce distincte, avec sa propre configuration de fournisseur et d’API.
Les erreurs 500 ultérieures et les questions sur les mots de passe n’ont pas été résolues dans le fil
En février 2026, un utilisateur a signalé une erreur HTTP 500 lors de l’importation, et en mai 2026, un autre utilisateur n’a pas réussi à utiliser les mots de passe attendus. Le fil public ne contient pas de diagnostic final pour ces cas.
Ne transformez pas les identifiants d’exemple du tutoriel d’origine en méthode de connexion universelle pour les versions ultérieures de BigBear.
Exporter les données de Paperless avant toute modification majeure des paquets
La version actuelle de Paperless fournit un exportateur de documents qui inclut les documents, les miniatures, les métadonnées et les informations issues de la base de données pour les opérations de migration et de sauvegarde. Utilisez un export compatible avec l’application ainsi que des sauvegardes normales du stockage avant de remplacer la base de données ou la pile Compose.
FAQ de Paperless-ngx sur ZimaOS
Tika est-il requis pour chaque installation de Paperless-ngx ?
Non. C’est facultatif et principalement nécessaire pour les documents Office et l’analyse des e-mails.
Les gros lots de documents à ingérer nécessitent-ils normalement un redémarrage ?
L’auteur de la source le recommandait d’après son expérience, mais la documentation actuelle du projet en amont n’en fait pas une exigence normale.
Quelle base de données la version actuelle de Paperless recommande-t-elle pour les nouvelles installations ?
PostgreSQL est le moteur recommandé pour les nouveaux déploiements Docker.
Paperless-AI fait-il partie de Paperless-ngx lui-même ?
Non. Il s’agit d’une intégration tierce distincte abordée plus loin dans le fil.
