De installatie van de Paperless-ngx-bron mislukte laat in het ZimaOS App Store-proces: eerst verscheen er een autorisatiefout bij het ophalen van een Tika-image uit de GitHub Container Registry en later een DNS-fout voor een registriespiegel. Daardoor is de thread ingewikkelder dan alleen “Paperless werkt niet”: het falende onderdeel was een optionele Tika-service/image-route en het registry-eindpunt veranderde tussen de pogingen.
De openbare thread kwam niet tot een bevestigde oplossing in de ZimaOS App Store. Eén gebruiker wijzigde het Tika-image naar dat van Apache en bereikte 100% installatie, maar de stack draaide nog steeds niet. De huidige documentatie van Paperless-ngx biedt inmiddels een duidelijkere route: gebruik de onderhouden Docker Compose-sjablonen en schakel de Tika/Gotenberg-variant alleen in wanneer die documentindelingen nodig zijn.
De eerste fout was een GHCR-autorisatiefout
De oorspronkelijke fout trad op rond 80%:
Head "https://ghcr.io/v2/paperless-ngx/tika/manifests/2.9.1-minimal": unauthorizedHet verwijderen van lokale Docker-images en opnieuw installeren veranderde de uitkomst niet, wat tegen een eenvoudig verouderd lokaal image pleit.
De volgende poging mislukte bij de DNS-resolutie
Twee dagen later was de fout veranderd in een mislukte DNS-lookup voor een hostnaam van een registriespiegel. Daarom stelde een communitybeantwoorder voor om naamresolutie, basale HTTPS-connectiviteit, DNS-filtering, VPN-/proxygedrag en het handmatig ophalen van een image te controleren.
Dat waren communitydiagnoses, geen door IceWhale bevestigde hoofdoorzaak.
Tika is optioneel in de huidige versie van Paperless-ngx
Volgens de huidige documentatie van Paperless-ngx zijn Tika en Gotenberg optionele services voor Office-documenten zoals DOC/XLSX/ODT en voor het verwerken van e-mail. Als die indelingen niet nodig zijn, hoeft Tika helemaal niet te worden ingeschakeld.
Als ze wel nodig zijn, gebruik dan de onderhouden Compose-variant met Tika en Gotenberg in plaats van een verouderde imageverwijzing uit de App Store.
De huidige Docker Compose van het upstreamproject is de beste basis
De huidige installatiehandleiding van Paperless-ngx raadt Docker voor de meeste gebruikers aan en biedt onderhouden Compose-bestanden. Voor nieuwe installaties wordt PostgreSQL aanbevolen; sjablonen met Tika worden afzonderlijk aangeboden.
Gebruik het huidige Paperless-ngx Docker Compose-installatiemodel als het ZimaOS App Store-pakket verouderd is of verwijst naar een niet-beschikbaar aanvullend image.
Alleen het Tika-image wijzigen is mogelijk niet voldoende
Een deelnemer verving het Tika-image door apache/tika:latest. De installatie bereikte 100%, maar de applicatie werkte na het opstarten nog steeds niet.
Dat negatieve resultaat is belangrijk, omdat Paperless het service-eindpunt, de functievlag en de Gotenberg-integratie moet laten overeenkomen met de Compose-configuratie. Een containerimage vervangen is niet noodzakelijkerwijs een volledige migratie van de stack.
Plaats permanente Paperless-gegevens op de hoofdopslag
Paperless kan groeien door opgeslagen documenten, miniaturen, OCR-gegevens, zoekindexen en de database. De huidige aanbeveling voor ZimaOS is om appgegevens vóór de installatie van opslagintensieve applicaties van de systeemschijf te verplaatsen.
Het huidige model voor app-opslagpaden in ZimaOS is bijzonder relevant voor Paperless, omdat de gegevensvoetafdruk veel groter kan worden dan de omvang van het Docker-image.
Rechten zijn belangrijk voor de consumptiemap
De huidige documentatie van Paperless-ngx biedt USERMAP_UID en USERMAP_GID, zodat de container naar aan de host gekoppelde mappen kan schrijven. Als de stack wordt geïnstalleerd maar geen documenten kan verwerken, controleer dan deze waarden en de rechten van de hostmap in plaats van terug te keren naar problemen met het registry.
Beschouw een hostnaam van een registriespiegel niet als de Paperless-applicatie
De tweede bronfout verwees naar een hostnaam in de stijl van een spiegelserver in plaats van naar het hoofdendpoint ghcr.io. Dat onderscheid is belangrijk: een applicatiepakket kan volledig geldig zijn terwijl de geconfigureerde imagespiegel, DNS-server of regionale registryroute niet beschikbaar is.
Als een handmatige pull vanaf het upstreamregistry slaagt maar de App Store toch een defecte spiegel probeert te gebruiken, ligt het probleem bij de pakket- of registryrouteringslaag en niet bij Paperless zelf.
Maak onderscheid tussen een fout bij het ophalen van images en een fout bij het starten van containers
De eerste poging uit de bron voltooide het ophalen van alle vereiste images niet. Het latere experiment met Apache Tika bereikte 100% installatie, maar mislukte daarna tijdens het opstarten. Dit zijn twee verschillende foutfasen waarvoor verschillend bewijsmateriaal nodig is.
- Ophaalfase: registry-authenticatie, DNS, beschikbaarheid van de spiegel en imagetag.
- Opstartfase: omgevingsvariabelen, databaseverbinding, Tika-/Gotenberg-eindpunten, volumes, rechten en healthchecks.
Maak een back-up van een werkende Paperless-instantie voordat je de App Store-stack vervangt
Als Paperless al in gebruik is, stap dan niet zomaar over op Compose-sjablonen om alleen een aanvullende service te repareren zonder eerst de documenten en database te beschermen. De huidige upstreamversie van Paperless bevat speciaal voor back-up en migratie een exporter.
Voor een nieuwe installatie is het eenvoudiger om te beginnen met het onderhouden upstream-Compose-bestand. Maak bij een bestaande installatie eerst een back-up van de huidige database en mediapaden voordat je de stack herschrijft.
Veelgestelde vragen over de installatie van Paperless-ngx
Was de fout uit 2025 definitief een DNS-probleem?
Nee. De thread liet zowel autorisatie- als DNS-fouten zien en er werd geen officiële einddiagnose gepubliceerd.
Is Tika vereist voor elke Paperless-ngx-installatie?
Nee. Tika is optioneel en voornamelijk nodig voor Office-documenten en het verwerken van e-mail.
Loste het overschakelen naar apache/tika de oorspronkelijke situatie volledig op?
Nee. Eén gebruiker bereikte 100% installatie, maar de applicatie draaide nog steeds niet.
