Die Installation der Paperless-ngx-Quelle ist im ZimaOS-App-Store-Prozess spät fehlgeschlagen: zunächst mit einem nicht autorisierten Fehler beim Abrufen eines Tika-Images aus der GitHub Container Registry und später mit einem DNS-Fehler bei einem Registry-Mirror. Dadurch ist der Thread komplizierter als die Aussage „Paperless ist defekt“: Die fehlschlagende Komponente war ein optionaler Tika-Dienst beziehungsweise Image-Pfad, und der Registry-Endpunkt änderte sich zwischen den Versuchen.
Der öffentliche Thread erreichte keine bestätigte Lösung für den ZimaOS-App-Store. Ein Benutzer änderte das Tika-Image auf das Apache-Image und erreichte eine Installationsquote von 100 %, doch der Stack lief weiterhin nicht. Die aktuelle Dokumentation von Paperless-ngx bietet nun einen klareren Weg: Verwenden Sie die gepflegten Docker-Compose-Vorlagen und aktivieren Sie die Tika-/Gotenberg-Variante nur, wenn diese Dokumentformate benötigt werden.
Der erste Fehler war ein GHCR-Autorisierungsfehler
Der ursprüngliche Fehler trat bei etwa 80 % auf:
Head "https://ghcr.io/v2/paperless-ngx/tika/manifests/2.9.1-minimal": unauthorizedDas Löschen lokaler Docker-Images und eine erneute Installation änderten nichts am Ergebnis, was gegen ein einfaches veraltetes lokales Image spricht.
Der nächste Versuch scheiterte an der DNS-Auflösung
Zwei Tage später hatte sich der Fehler in eine fehlgeschlagene DNS-Abfrage für einen Registry-Mirror-Hostnamen geändert. Ein Community-Mitglied empfahl daher, die Namensauflösung, die grundlegende HTTPS-Konnektivität, DNS-Filter, VPN-/Proxy-Verhalten und einen manuellen Image-Pull zu prüfen.
Das waren Diagnoseschritte aus der Community, keine von IceWhale bestätigte Ursache.
Tika ist in aktuellen Paperless-ngx-Versionen optional
Die aktuelle Dokumentation von Paperless-ngx besagt, dass Tika und Gotenberg optionale Dienste sind, die für Office-Dokumente wie DOC/XLSX/ODT sowie für die E-Mail-Verarbeitung verwendet werden. Wenn diese Formate nicht benötigt werden, muss Tika überhaupt nicht aktiviert werden.
Falls sie benötigt werden, verwenden Sie die gepflegte Compose-Variante mit Tika und Gotenberg statt einer veralteten App-Store-Referenz auf ein Image.
Das aktuelle Docker Compose des Upstream-Projekts ist die beste Grundlage
Die aktuelle Einrichtungsanleitung von Paperless-ngx empfiehlt Docker für die meisten Benutzer und stellt gepflegte Compose-Dateien bereit. Für neue Installationen wird PostgreSQL empfohlen, und Vorlagen mit aktivierter Tika-Unterstützung werden separat angeboten.
Verwenden Sie das aktuelle Docker-Compose-Installationsmodell von Paperless-ngx, wenn das ZimaOS-App-Store-Paket veraltet ist oder auf ein nicht verfügbares zusätzliches Image verweist.
Nur das Tika-Image zu ändern, reicht möglicherweise nicht aus
Ein Teilnehmer ersetzte das Tika-Image durch apache/tika:latest. Die Installation erreichte 100 %, doch die Anwendung schlug nach dem Start weiterhin fehl.
Dieses negative Ergebnis ist relevant, da Paperless den Dienstendpunkt, das Feature-Flag und die Gotenberg-Integration passend zur Compose-Konfiguration benötigt. Das Ersetzen eines Container-Images ist nicht zwangsläufig eine vollständige Migration des Stacks.
Legen Sie persistente Paperless-Daten auf dem Hauptspeicher ab
Paperless kann durch gespeicherte Dokumente, Miniaturansichten, OCR-Daten, Suchindizes und seine Datenbank wachsen. Das aktuelle ZimaOS empfiehlt, App-Daten vor der Installation speicherintensiver Anwendungen vom Systemlaufwerk zu verschieben.
Das aktuelle ZimaOS-Modell für App-Speicherpfade ist für Paperless besonders relevant, da dessen Datenumfang weit über die Größe des Docker-Images hinauswachsen kann.
Berechtigungen für den Consumption-Ordner sind wichtig
Die aktuelle Dokumentation von Paperless-ngx stellt USERMAP_UID und USERMAP_GID bereit, damit der Container in per Bind-Mount eingebundene Ordner auf dem Host schreiben kann. Wenn der Stack installiert wird, aber keine Dokumente einlesen kann, überprüfen Sie diese Werte und die Berechtigungen des Host-Ordners, statt erneut die Registry zu untersuchen.
Behandeln Sie einen Registry-Mirror-Hostnamen nicht als die Paperless-Anwendung
Der zweite Fehler aus der Quelle verwies auf einen Mirror-ähnlichen Hostnamen statt auf den eigentlichen ghcr.io-Endpunkt. Dieser Unterschied ist wichtig: Ein Anwendungspaket kann vollkommen gültig sein, während der konfigurierte Image-Mirror, der DNS-Server oder der regionale Registry-Pfad nicht verfügbar ist.
Wenn ein manueller Pull aus der Upstream-Registry erfolgreich ist, der App Store aber weiterhin einen fehlerhaften Mirror verwendet, liegt das Problem in der Paket- oder Registry-Routing-Schicht und nicht bei Paperless selbst.
Unterscheiden Sie zwischen einem Image-Pull- und einem Container-Startfehler
Der erste Versuch aus der Quelle konnte den Pull aller erforderlichen Images nicht abschließen. Das spätere Apache-Tika-Experiment erreichte eine Installationsquote von 100 %, schlug jedoch anschließend beim Start fehl. Dies sind zwei unterschiedliche Fehlerphasen, die unterschiedliche Nachweise erfordern.
- Pull-Phase: Registry-Authentifizierung, DNS, Verfügbarkeit des Mirrors, Image-Tag.
- Startphase: Umgebungsvariablen, Datenbankverbindung, Tika-/Gotenberg-Endpunkte, Volumes, Berechtigungen und Healthchecks.
Sichern Sie eine funktionierende Paperless-Instanz, bevor Sie den App-Store-Stack ersetzen
Wenn Paperless bereits verwendet wird, wechseln Sie nicht einfach die Compose-Vorlagen, um einen zusätzlichen Dienst zu reparieren, ohne vorher Dokumente und Datenbank zu schützen. Das aktuelle Paperless-ngx enthält eigens für Sicherung und Migration einen Exporter.
Bei einer neuen Installation ist der Start mit der gepflegten Upstream-Compose-Datei einfacher. Bei einer bestehenden Installation sollten Sie die aktuelle Datenbank und die Medienpfade sichern, bevor Sie den Stack neu schreiben.
FAQ zur Paperless-ngx-Installation
War der Fehler von 2025 eindeutig ein DNS-Problem?
Nein. Der Thread zeigte sowohl Autorisierungs- als auch DNS-Fehler, und es wurde keine offizielle abschließende Diagnose veröffentlicht.
Ist Tika für jede Paperless-ngx-Installation erforderlich?
Nein. Tika ist optional und wird hauptsächlich für Office-Dokumente und die E-Mail-Verarbeitung benötigt.
Hat der Wechsel zu apache/tika den Fall aus der Quelle vollständig gelöst?
Nein. Ein Benutzer erreichte eine Installationsquote von 100 %, aber die Anwendung lief weiterhin nicht.
