L’installation de Paperless-ngx depuis l’App Store de ZimaOS a échoué tard dans le processus, d’abord avec une erreur d’autorisation lors du téléchargement d’une image Tika depuis GitHub Container Registry, puis avec une erreur DNS concernant un miroir de registre. Cette combinaison rend le sujet plus complexe que « Paperless est défaillant » : le composant en échec était un service et un chemin d’image Tika facultatifs, et le point de terminaison du registre a changé entre les tentatives.
Le fil public n’a jamais abouti à une correction confirmée dans l’App Store de ZimaOS. Un utilisateur a remplacé l’image Tika par celle d’Apache et a atteint 100 % de l’installation, mais la pile ne fonctionnait toujours pas. La documentation actuelle de Paperless-ngx propose désormais une voie plus claire : utiliser les modèles Docker Compose maintenus et activer la variante Tika/Gotenberg uniquement lorsque ces formats de documents sont nécessaires.
Le premier échec était une erreur d’autorisation de GHCR
L’erreur initiale est survenue vers 80 % :
Head "https://ghcr.io/v2/paperless-ngx/tika/manifests/2.9.1-minimal": unauthorizedLa suppression des images Docker locales et la réinstallation n’ont pas modifié le résultat, ce qui écarte l’hypothèse d’une simple image locale obsolète.
La tentative suivante a échoué lors de la résolution DNS
Deux jours plus tard, l’erreur avait changé : la résolution DNS d’un nom d’hôte de miroir de registre échouait. Un membre de la communauté a donc suggéré de vérifier la résolution des noms, la connectivité HTTPS de base, le filtrage DNS, le comportement du VPN ou du proxy, ainsi qu’un téléchargement manuel de l’image.
Il s’agissait de diagnostics proposés par la communauté, et non d’une cause racine confirmée par IceWhale.
Tika est facultatif dans la version actuelle de Paperless-ngx
La documentation actuelle de Paperless-ngx indique que Tika et Gotenberg sont des services facultatifs utilisés pour les documents Office tels que DOC/XLSX/ODT et pour l’analyse des e-mails. Si ces formats ne sont pas nécessaires, il n’est pas nécessaire d’activer Tika.
S’ils sont nécessaires, utilisez la variante Compose maintenue qui inclut Tika et Gotenberg plutôt qu’une ancienne référence d’image de l’App Store.
Docker Compose en amont est actuellement la meilleure référence
Le guide de configuration actuel de Paperless-ngx recommande Docker pour la plupart des utilisateurs et fournit des fichiers Compose maintenus. Pour les nouvelles installations, PostgreSQL est recommandé, et des modèles intégrant Tika sont fournis séparément.
Utilisez le modèle actuel d’installation Docker Compose de Paperless-ngx si le paquet de l’App Store de ZimaOS est obsolète ou fait référence à une image auxiliaire indisponible.
Modifier uniquement l’image Tika peut ne pas suffire
Un participant a remplacé l’image Tika par apache/tika:latest. L’installation a atteint 100 %, mais l’application échouait toujours après son démarrage.
Ce résultat négatif est important, car Paperless a besoin que le point de terminaison du service, l’indicateur de fonctionnalité et l’intégration de Gotenberg correspondent à la configuration Compose. Remplacer une image de conteneur ne constitue pas nécessairement une migration complète de la pile.
Placez les données persistantes de Paperless sur l’espace de stockage principal
La taille de Paperless peut augmenter en raison des documents importés, des miniatures, des données OCR, des index de recherche et de sa base de données. La version actuelle de ZimaOS recommande de déplacer les données des applications hors du disque système avant d’installer des applications gourmandes en stockage.
Le modèle actuel des chemins de stockage des applications de ZimaOS est particulièrement pertinent pour Paperless, car son empreinte de données peut largement dépasser la taille de l’image Docker.
Les autorisations sont importantes pour le dossier de consommation
La documentation actuelle de Paperless-ngx expose USERMAP_UID et USERMAP_GID afin que le conteneur puisse écrire dans les dossiers montés depuis l’hôte. Si la pile s’installe mais ne peut pas importer de documents, vérifiez ces valeurs ainsi que les autorisations du dossier hôte au lieu de revenir au dépannage du registre.
Ne prenez pas le nom d’hôte d’un miroir de registre pour l’application Paperless
La deuxième erreur source faisait référence à un nom d’hôte de type miroir plutôt qu’au point de terminaison principal ghcr.io. Cette distinction est importante : un paquet d’application peut être parfaitement valide alors que le miroir d’images configuré, le serveur DNS ou le chemin régional du registre est indisponible.
Si un téléchargement manuel depuis le registre en amont réussit, mais que l’App Store continue d’utiliser un miroir défaillant, le problème concerne la couche du paquet ou du routage du registre, et non Paperless lui-même.
Distinguez l’échec du téléchargement de l’image de l’échec du démarrage du conteneur
Lors de la première tentative source, le téléchargement de toutes les images requises ne s’est jamais terminé. Lors de l’expérience ultérieure avec Apache Tika, l’installation a atteint 100 %, mais a ensuite échoué au démarrage. Il s’agit de deux étapes d’échec différentes, qui nécessitent des éléments de preuve différents.
- Étape de téléchargement : authentification au registre, DNS, disponibilité du miroir, balise de l’image.
- Étape de démarrage : variables d’environnement, connectivité à la base de données, points de terminaison Tika/Gotenberg, volumes, autorisations et vérifications d’état.
Sauvegardez une instance Paperless fonctionnelle avant de remplacer la pile de l’App Store
Si Paperless est déjà utilisé, ne changez pas de modèle Compose uniquement pour corriger un service auxiliaire sans protéger au préalable les documents et la base de données. Paperless fournit désormais un exportateur spécialement conçu pour la sauvegarde et la migration.
Pour une nouvelle installation, il est plus simple de partir du fichier Compose maintenu en amont ; pour une installation existante, conservez les chemins actuels de la base de données et des fichiers multimédias avant toute réécriture de la pile.
FAQ sur l’installation de Paperless-ngx
L’échec de 2025 était-il définitivement dû à un problème DNS ?
Non. Le fil montrait à la fois des erreurs d’autorisation et des erreurs DNS, et aucun diagnostic final officiel n’a été publié.
Tika est-il requis pour chaque installation de Paperless-ngx ?
Non. Il est facultatif et principalement nécessaire pour les documents Office et l’analyse des e-mails.
Le passage à apache/tika a-t-il complètement résolu le problème source ?
Non. Un utilisateur a atteint 100 % de l’installation, mais l’application ne fonctionnait toujours pas.
