Réponse actuelle : n’utilisez pas l’échec d’installation de la bêta 1.4.2 comme modèle de configuration de Paperless-ngx en 2026
L’installation initiale s’est arrêtée à 83 % sur ZimaOS 1.4.2-beta2, et IceWhale a indiqué que cette version avait modifié la technologie de source et de proxy d’installation des applications, et que le problème était en cours de résolution. Les versions actuelles de ZimaOS publient désormais une procédure d’installation dédiée à Paperless-ngx, tandis que le projet en amont propose une méthode Docker Compose mature. Considérez le blocage de 2025 comme un bug historique de l’installateur, et non comme la preuve que Paperless-ngx est fondamentalement incompatible avec ZimaOS.
Commencez par la configuration actuelle de l’App Store de ZimaOS
Les instructions actuelles de ZimaOS utilisent Paperless-ngx depuis l’App Store avec une installation personnalisée, afin que vous puissiez définir le chemin de stockage, les identifiants administrateur, les langues OCR et les valeurs d’URL de confiance avant le premier démarrage. La configuration de Paperless sur ZimaOS constitue la base actuelle spécifique au produit.
Les exigences de Paperless-ngx vous aident à dimensionner l’application avant de lancer d’importants travaux d’OCR.
Placez les données persistantes sur un stockage que vous pouvez sauvegarder
Paperless gère plusieurs types d’état : les données de la base de données, les données de l’application, les médias et documents, les fichiers exportés ainsi que le dossier de consommation. Conservez ces chemins de manière persistante, en dehors de la couche de conteneur éphémère. Si vous supprimez AppData pendant le dépannage, vous risquez également de supprimer les éléments ou l’état nécessaires pour comprendre pourquoi l’installation précédente a échoué.
La configuration Docker de Paperless définit les services en amont et le déploiement PostgreSQL recommandé.
Comprenez la question de Tika et Gotenberg
Paperless peut fonctionner sans Tika ni Gotenberg pour son flux principal de documents PDF et image. Tika et Gotenberg sont des services optionnels utilisés lorsque vous souhaitez prendre en charge les fichiers Office et l’analyse des e-mails. Si un paquet rencontre une erreur liée à Tika, déterminez d’abord si vous avez réellement besoin de cette fonctionnalité avant de bloquer toute l’installation.
Les paramètres Tika de Paperless répertorient les points de terminaison et les variables d’activation.
Si l’installation s’arrête à un pourcentage, surveillez les conteneurs au lieu d’attendre des heures
docker ps -a
docker logs --tail=200 paperless-webserver
docker logs --tail=200 paperless-db
docker logs --tail=200 paperless-redisLes noms exacts des conteneurs dépendent du paquet de l’App Store. Recherchez un échec de récupération d’image, un problème de disponibilité de la base de données, des permissions incorrectes, une configuration CSRF ou un service qui redémarre en boucle. « 83 % » est un symptôme de l’interface ; les journaux des conteneurs identifient le composant défaillant.
Corrigez les propriétaires du dossier de consommation avant d’accuser l’OCR
Paperless doit pouvoir lire et déplacer les fichiers du répertoire de consommation. La configuration Docker en amont prend en charge USERMAP_UID/USERMAP_GID pour aligner les permissions de l’hôte. Si les fichiers apparaissent dans le dossier de consommation de l’hôte, mais que Paperless ne les traite jamais, vérifiez le propriétaire, le chemin de montage et les notifications du système de fichiers.
Les exigences des applications ZimaOS vous aident à éviter de placer une archive de documents en croissance sur un petit disque système.
Configurez correctement l’URL externe
Lorsque Paperless est accessible via une adresse d’hôte ZimaOS ou un proxy inverse, définissez les origines de confiance et l’URL publique sur l’adresse réellement ouverte par les utilisateurs. Une configuration incorrecte de l’origine se manifeste souvent plus tard par une erreur CSRF 403, même lorsque tous les conteneurs fonctionnent correctement.
Sauvegardez ensemble la base de données et les documents
Vos fichiers de documents sans la base de données Paperless perdent leurs étiquettes, correspondants, champs personnalisés et états de flux de travail ; la base de données sans les médias perd les documents eux-mêmes. Sauvegardez les deux comme une seule unité de récupération et testez une restauration avant les mises à niveau importantes.
La sauvegarde ZimaOS fournit la couche de récupération au niveau du NAS.
FAQ
Pourquoi Paperless-ngx s’est-il arrêté à 83 % sur ZimaOS ?
Dans le cas d’origine, IceWhale a attribué l’échec aux changements de source d’application et de proxy dans la version bêta 1.4.2 de ZimaOS. Sur un système actuel, consultez les journaux des conteneurs au lieu de supposer qu’il s’agit du même ancien bug.
Paperless-ngx nécessite-t-il Tika ?
Non, pas pour la gestion principale des documents PDF et image. Tika et Gotenberg sont optionnels lorsque vous avez besoin de l’analyse de documents Office et d’e-mails.
Où le dossier de consommation doit-il se trouver ?
Utilisez un stockage de données ZimaOS persistant avec un chemin d’hôte clair et des permissions permettant au conteneur Paperless de lire et de modifier les fichiers.
Dois-je supprimer AppData et réinstaller l’application ?
Uniquement après avoir compris quelles données seront supprimées et effectué une sauvegarde. La réinstallation ne corrigera pas un mauvais chemin de volume, un problème de permissions ou une configuration d’URL incorrecte.
Quelle base de données une nouvelle installation de Paperless doit-elle utiliser ?
Le projet en amont recommande actuellement PostgreSQL pour les nouvelles installations.
