Current Answer: Do Not Use the 1.4.2 Beta Install Failure as the 2026 Paperless-ngx Setup Model
The original installation stopped at 83% on ZimaOS 1.4.2-beta2, and IceWhale said that release had changed the app install source/proxy technology and the issue was being fixed. Current ZimaOS now publishes a dedicated Paperless-ngx installation procedure and the upstream project has a mature Docker Compose path. Treat the 2025 stall as a historical installer bug, not evidence that Paperless-ngx is fundamentally incompatible with ZimaOS.
Start With the Current ZimaOS App Store Configuration
Current ZimaOS instructions use Paperless-ngx from the App Store with Custom Install so you can set the consumption path, administrator credentials, OCR languages and trusted URL values before first start. The ZimaOS Paperless setup is the current product-specific baseline.
The Paperless-ngx requirements helps size the app before large OCR jobs.
Put Persistent Data on Storage You Can Back Up
Paperless has several types of state: database data, application data, media/documents, exported files and the consume folder. Keep those paths persistent outside the disposable container layer. If you delete AppData while debugging, you may also delete the evidence or state needed to understand why the previous install failed.
The Paperless Docker setup defines the upstream services and recommended PostgreSQL deployment.
Understand the Tika and Gotenberg Question
Paperless can run without Tika/Gotenberg for its core PDF/image document flow. Tika and Gotenberg are optional services used when you want Office files and email parsing. If a package has a Tika-related failure, decide whether you actually need that feature before blocking the entire installation on it.
The Paperless Tika settings lists the endpoints and activation variables.
If Installation Stops at a Percentage, Watch the Containers Instead of Waiting for Hours
docker ps -a
docker logs --tail=200 paperless-webserver
docker logs --tail=200 paperless-db
docker logs --tail=200 paperless-redisThe exact container names depend on the App Store package. Look for image-pull failure, database readiness, permissions, CSRF configuration or a service stuck restarting. “83%” is a UI symptom; the container logs identify the failing component.
Fix Consume-Folder Ownership Before Blaming OCR
Paperless must be able to read and move files from the consume directory. Upstream Docker configuration supports USERMAP_UID/USERMAP_GID for host permission alignment. If files appear in the host consume folder but Paperless never processes them, check ownership, mount path and filesystem notifications.
The ZimaOS app requirements helps avoid putting a growing document archive onto a small OS drive.
Configure the External URL Correctly
When Paperless is accessed through a ZimaOS host address or reverse proxy, set the trusted origins and public URL to the address users actually open. A bad origin configuration often shows up later as a 403 CSRF error even though every container is healthy.
Back Up the Database and Documents Together
Your document files without the Paperless database lose tags, correspondents, custom fields and workflow state; the database without the media loses the actual documents. Back up both as one recovery unit and test a restore before major upgrades.
The ZimaOS backup provides the NAS-level recovery layer.
FAQ
Why did Paperless-ngx stop at 83% on ZimaOS?
In the source case, IceWhale tied the failure to app-source/proxy changes in ZimaOS 1.4.2 beta. On a current system, inspect container logs rather than assuming the same old bug.
Does Paperless-ngx require Tika?
No for core PDF/image document management. Tika and Gotenberg are optional when you need Office-document and email parsing.
Where should the consume folder live?
Use persistent ZimaOS data storage with a clear host path and permissions that the Paperless container can read and modify.
Should I delete AppData and reinstall?
Only after you understand what data will be removed and have a backup. Reinstalling does not fix a bad volume path, permission or URL configuration.
Which database should a new Paperless install use?
The upstream project currently recommends PostgreSQL for new installations.
