Deze tutorial uit december 2025 is een van de uitgebreidere communityhandleidingen voor Paperless-ngx op ZimaOS, maar is gekoppeld aan een specifiek BigBear-pakket en ZimaOS 1.5.3 Plus. De blijvende onderdelen zijn de opslag- en configuratieconcepten: geef de consume-map een duidelijke persistente locatie, stel de applicatie-URL correct in, configureer OCR-talen en begrijp de optionele Tika/Gotenberg-services.
Sommige details uit de bron hebben een actuele afbakening nodig. De upstream Docker-installatie van Paperless-ngx is geëvolueerd, PostgreSQL wordt nu aanbevolen voor nieuwe installaties, de huidige Compose-bestanden vragen tijdens de eerste configuratie om een superuser en Tika/Gotenberg blijven optioneel in plaats van verplicht voor elke documentworkflow.
De brontutorial werd getest op een bescheiden ZimaBoard 2
De auteur documenteerde een systeem op basis van een N150 met 16 GB RAM waarop ZimaOS 1.5.3 Plus draaide. Het doel was toegang via het lokale netwerk of Tailscale voor thuisgebruik, niet rechtstreekse publieke blootstelling.
Die reikwijdte is belangrijk, omdat een implementatie op het openbare internet een ander plan voor HTTPS, reverse proxy, authenticatie en beveiliging vereist.
De handleiding gebruikte BigBear Paperless-ngx Custom Install
In de bronworkflow werd in de App Store gezocht naar het BigBear Paperless-ngx-pakket, werd de installatielijst geopend en werd Custom Install gekozen, zodat volumes en omgevingswaarden vóór de eerste start konden worden bewerkt.
Dat is een pakket-specifieke werkwijze. Een actuele appdefinitie kan services en variabelen toevoegen, verwijderen of hernoemen.
Geef de consume-map een duidelijk persistent hostpad
/usr/src/paperless/consume als de map waarmee gebruikers waarschijnlijk het vaakst werken wanneer ze documenten toevoegen.De huidige upstream-documentatie van Paperless gebruikt nog steeds /usr/src/paperless/consume als de standaardcontainerbestemming en wordt expliciet ondersteund dat de hostzijde van die bind-mount kan worden gewijzigd.
In de tutorial werden de variabelen voor beheerder, verwerker, OCR en URL ingesteld
Belangrijke bronkeuzes waren:
- aangepaste beheerdersgebruikersnaam en -wachtwoord;
- recursieve documentverwerking;
- originelen uit de consume-map verwijderen na succesvolle opname;
- OCR-opruiming en taalinstellingen;
- Vertrouwde CSRF-origin en applicatie-URL;
- Tika/Gotenberg-eindpunten.
PAPERLESS_URL en CSRF Origins moeten overeenkomen met hoe u Paperless daadwerkelijk benadert
De tutorial waarschuwde dat een onjuiste URL-/origin-configuratie een 403-fout wegens mislukte CSRF-verificatie kon veroorzaken. Dat blijft conceptueel correct.
De huidige Paperless-documentatie vermeldt PAPERLESS_URL moet worden ingesteld wanneer de applicatie achter een reverse proxy staat en moet het extern gebruikte domein/de URL vertegenwoordigen. Gebruik het LAN-adres van de auteur van de bron niet hardgecodeerd in een andere installatie.
Ook binnen Paperless werden de OCR-instellingen aangepast
OCR-talen moeten overeenkomen met de taalpakketten die in de container beschikbaar zijn. Het toevoegen van talen kan de imagegrootte vergroten of de vereisten voor rootless containers wijzigen, afhankelijk van het huidige pakket.
Opnieuw opstarten na elke grote batch in de verwerkingsmap is advies van de bron, geen upstream-vereiste
De huidige versie van Paperless-ngx is ontworpen om de verwerkingsmap continu te controleren. De upstream-documentatie vermeldt niet dat grote batches normaal gesproken een herstart vereisen. Als documenten niet meer worden verwerkt, controleer dan de machtigingen, consumerlogboeken, ondersteuning voor bestandsysteemmeldingen en de status van de broker/worker, in plaats van herstarten tot een verplichte routine te maken.
De huidige upstream-configuratie raadt PostgreSQL aan voor nieuwe installaties
De huidige Docker-configuratie van Paperless-ngx raadt PostgreSQL aan voor nieuwe installaties, hoewel SQLite en MariaDB beschikbaar blijven in ondersteunde configuraties.
Voor een langdurig documentarchief is de huidige upstream-Compose-topologie daarom een betere referentie dan ervan uitgaan dat exact dezelfde BigBear-databaseservice uit 2025 nog steeds ongewijzigd is.
Tika en Gotenberg zijn optioneel
De huidige Paperless-documentatie vermeldt dat Tika en Gotenberg nodig zijn voor het parseren van Office-documenten zoals DOC/XLSX/ODT en e-mailbestanden. Als je alleen indelingen verwerkt die door de basisstack van Paperless worden ondersteund, kan deze functie uitgeschakeld blijven.
Gebruik de huidige Paperless-ngx Docker-configuratie voordat je de historische BigBear-stack handmatig opnieuw opbouwt.
Machtigingen voor de verwerkingsmap zijn belangrijker dan herhaaldelijk opnieuw opstarten
De huidige upstream-configuratie stelt bloot USERMAP_UID en USERMAP_GID zodat de container naar host-bindmounts kan schrijven. Als Paperless een consume-map ziet maar bestanden niet kan verwerken of verwijderen, controleer dan het eigenaarschap van de gekoppelde map en de identiteit van de container.
Controleer op ZimaOS ook of het consume-pad op de beoogde beheerde opslag staat en niet op een alleen-lezen volumekoppeling.
Originelen uit /consume verwijderen is niet hetzelfde als gearchiveerde documenten verwijderen
De bron heeft ingeschakeld PAPERLESS_CONSUMER_DELETE_ORIGINALS=true. Dit bepaalt wat er na succesvolle verwerking met het invoerbestand in de consume-map gebeurt. Het door Paperless beheerde gearchiveerde document blijft in de mediaopslag staan.
Test dit gedrag met wegwerpdocumenten voordat je een geautomatiseerde scanner of synchronisatieservice naar een productiemap laat verwijzen.
Antwoorden over Paperless-AI horen bij een afzonderlijke integratie
In latere antwoorden werd besproken dat Paperless-AI documenten via de Paperless-API kan lezen, maar met de ingebouwde OpenAI-configuratie geen tags kan analyseren of schrijven. Gebruikers meldden dat Mistral werkte en dat handmatige OpenAI-configuratie het probleem omzeilde.
Deze antwoorden bewijzen niet dat de kerninstallatie van Paperless-ngx defect is. Paperless-AI is een afzonderlijke integratie van een derde partij met eigen provider- en API-configuratie.
Latere 500-fouten en wachtwoordvragen zijn in de thread niet opgelost
Een gebruiker meldde in februari 2026 een HTTP 500 tijdens het uploaden, en een andere gebruiker kon in mei 2026 niet met de verwachte wachtwoorden inloggen. De openbare thread bevat voor die gevallen geen definitieve diagnoses.
Maak van de voorbeeldgegevens uit de oorspronkelijke tutorial geen universeel recept voor inloggen op latere BigBear-releases.
Exporteer Paperless-gegevens voordat je grote pakketwijzigingen uitvoert
De huidige Paperless-versie biedt een documentexporteur die documenten, miniaturen, metagegevens en uit de database afgeleide informatie bevat voor migratie- en back-upworkflows. Gebruik een applicatiebewuste export en maak normale back-ups van de opslag voordat je de database of de Compose-stack vervangt.
Veelgestelde vragen over Paperless-ngx op ZimaOS
Is Tika vereist voor elke Paperless-ngx-installatie?
Nee. Dit is optioneel en voornamelijk nodig voor Office-documenten en het parseren van e-mails.
Hebben grote verwerkingsbatches normaal gesproken een herstart nodig?
De auteur van de bron beval dit op basis van diens ervaring aan, maar de huidige upstream-documentatie stelt een herstart niet als normale vereiste.
Welke database raadt de huidige Paperless-versie aan voor nieuwe installaties?
PostgreSQL is de aanbevolen backend voor nieuwe Docker-implementaties.
Maakt Paperless-AI zelf deel uit van Paperless-ngx?
Nee. Het is een afzonderlijke integratie van een derde partij die later in de thread wordt besproken.
