Paperless-ngx can turn a folder of scans, invoices, and PDFs into a searchable self-hosted document archive, but dependable operation depends on more than starting a container. This guide covers a reusable Docker Compose workflow, PostgreSQL and Redis, persistent storage, OCR, ingestion, classification, permissions, backups, upgrades, and restore testing.
Overview
Paperless-ngx is best treated as a document-processing system rather than a simple file browser. Files enter through a consume directory, an upload, a client, or an optional mail workflow. The application then uses OCR and classification tools to create searchable text and metadata before storing the document in its archive.
A practical self-hosted deployment normally includes four roles:
- Paperless-ngx: the web application, task processing, document search, and management interface.
- PostgreSQL: the database for document metadata, users, tags, correspondents, document types, and configuration.
- Redis: the message broker used for background tasks.
- Persistent storage: directories for application data, the document archive, incoming files, and exports.
Use a dedicated directory on the host, restrict access to the application and database services, and place the web interface behind a reverse proxy or private network. Before deploying, check the current Paperless-ngx documentation for supported image requirements, environment variables, database versions, OCR components, and migration notes. Image tags and configuration names can change between releases.
For the broader backup design, see Docker Backup Strategy for Self-Hosted Apps. If you already operate PostgreSQL for multiple applications, also review Self-Hosted PostgreSQL for Docker Apps.
Checklist by scenario
1. Prepare the host
- Choose a stable Linux host with enough disk space for original files, OCR output, thumbnails, database growth, and backups.
- Create a dedicated project directory such as
/srv/paperlessand protect it from unrelated containers. - Apply basic server hardening: updates, SSH key authentication, a firewall, limited administrative access, and time synchronization.
- Decide whether Paperless-ngx is reachable only on your LAN, through a VPN, or through a public HTTPS reverse proxy.
- Measure available storage before importing an existing archive. Keep backups on a separate disk or host rather than inside the project directory.
2. Create the Docker Compose stack
Use the official Paperless-ngx Compose example as the starting point, then adapt its image references and settings to your environment. A typical stack defines a Paperless-ngx service, PostgreSQL, and Redis. The application should depend on healthy or available supporting services, but remember that a Compose dependency is not a substitute for a proper health check.
Set secrets and environment-specific values through a protected .env file or another secret mechanism. At minimum, plan values for the application URL, timezone, database name and credentials, Redis connection, OCR languages, user creation, and any mail or proxy settings you use. Do not commit database passwords or secret keys to a public Git repository.
Use named volumes or explicit bind mounts consistently. Bind mounts make host-level backup and inspection straightforward; named volumes can be convenient but require you to know their Docker storage location. Whichever model you choose, document it before the first import.
3. Map storage deliberately
| Path or function | Purpose | Backup and maintenance note |
|---|---|---|
| Data directory | Application state, search index, and generated data | Back up it together with the database; do not delete it casually. |
| Media directory | Managed document archive and converted files | This is usually the most important large data set. |
| Consume directory | Incoming files waiting for processing | Keep it separate so scanners and watched folders have a clear target. |
| Export directory | Files produced by exports | Use for migration or recovery workflows, then protect or remove copies. |
| PostgreSQL data | Metadata, users, and classification configuration | Use a database-aware backup in addition to file-level copies. |
| Redis data | Queue and broker state | Usually reconstructible, but persistent configuration should follow the current project guidance. |
Keep permissions aligned with the UID and GID expected by the containers. A consume directory that is writable by every user on the server may be convenient, but it increases the chance of accidental or unauthorized imports.
4. Configure OCR and ingestion
Choose OCR languages that match the documents you actually scan. Additional languages can improve coverage for mixed archives but may affect processing time and resource use. Confirm that the required language data is installed or enabled according to the current container documentation.
For scanner workflows, configure the scanner to place PDFs or images in the consume directory, or use a controlled network share that maps to it. For email ingestion, create a dedicated mailbox or forwarding path, restrict who can send to it, and test attachments, sender handling, duplicate messages, and failure notifications. Mail ingestion behavior and client support should be rechecked after major releases.
Start with a small test batch containing a clean text PDF, a scanned image, a multipage document, a rotated page, and a document with a non-Latin or mixed language if relevant. Confirm that each item is imported, OCR text is searchable, the original document opens, and the expected metadata is retained.
5. Build a classification system
Define document types for stable categories such as invoices, contracts, statements, or identity records. Use correspondents for the organization or person that issued a document, and tags for cross-cutting properties such as tax year, renewal, household member, or action required.
Keep names predictable and avoid creating a new tag for every minor variation. After manual classification works, add matching rules or automatic assignment carefully. Test rules against a sample set before applying them to a large archive. Permissions should reflect the sensitivity of the documents: create separate users or groups where needed, and avoid sharing the whole archive simply because one folder is intended for collaboration.
6. Operate and maintain the archive
- Monitor container logs, task failures, disk usage, database health, and the age of unprocessed files.
- Back up PostgreSQL with a logical or otherwise database-consistent method, and back up the Paperless-ngx data and media directories.
- Encrypt backups when they contain personal, financial, legal, or health-related documents.
- Keep at least one backup away from the primary server and periodically verify that it can be read.
- Use controlled image updates rather than automatically accepting every image change. A review-and-rollback workflow is described in Renovate for Docker Compose.
What to double-check
OCR troubleshooting flow
- Is the file processed? Check the consume directory, application logs, and background task status. A file that remains untouched may indicate permissions, an invalid file, or a worker problem.
- Does the document open? If the original is unavailable, inspect storage mounts and available disk space before investigating OCR.
- Is the text searchable? Confirm the selected OCR languages and whether the source already contains a text layer. Test another known-good document.
- Is the output wrong? Check scan resolution, page rotation, contrast, compression, and language selection. OCR cannot reliably recover text that is missing or unreadable in the source.
- Are tasks stuck? Check Redis connectivity, worker logs, CPU and memory pressure, and whether another large batch is monopolizing processing.
Upgrade runbook
- Read the release notes and migration instructions for the target version.
- Record the current image tags, Compose file, environment file, and volume paths.
- Run and verify a database backup, then capture a file-level backup or snapshot of media and application data.
- Test the backup or at least inspect its contents and restore procedure before making changes.
- Pull the reviewed images and recreate the stack during a maintenance window.
- Watch migration logs and verify login, search, OCR, uploads, downloads, permissions, and mail ingestion.
- Keep the previous image references and rollback plan until normal operation is confirmed.
Restore-validation procedure
Recovery is not complete when files have merely been copied back. On an isolated host, restore the database, application data, and media to the documented paths. Start the required services, confirm that the database and application versions are compatible, and verify that documents, tags, correspondents, users, search results, and permissions are present. Import a test file, run OCR, download an original, and check that the consume workflow still works. Record the result and the time required; that record makes the next incident less uncertain.
Common mistakes
- Backing up only the media directory: the PDFs may survive, but metadata, users, tags, and search configuration can be lost without the database and application data.
- Using the consume directory as permanent storage: it is an intake area, not a substitute for the managed archive.
- Publishing the database or Redis port: expose only the web service required by your access design.
- Changing paths without documenting them: backup jobs and restore instructions can silently target an empty directory.
- Importing everything at once: a small test batch reveals OCR, permissions, and classification problems before they affect the archive.
- Updating without a rollback plan: a current backup, known image tag, and recent Compose file are part of the upgrade, not optional paperwork.
- Overusing automatic rules: a broad correspondent or tag rule can misclassify hundreds of documents quickly. Review samples before enabling bulk automation.
- Ignoring sensitive data: secure the web interface, backups, mail source, scanner share, and administrator accounts as one system.
When to revisit
Revisit this Paperless-ngx checklist before adding a scanner, changing mail sources, importing a large archive, exposing the service through a new reverse proxy, or changing storage. Review it before seasonal document cycles such as tax preparation or annual renewals, when ingestion volume and classification rules often change.
Recheck the official project documentation before every major upgrade and after important security or migration advisories. Also revisit the design when the host changes, the database moves, OCR languages are added, or backups are redesigned. At least periodically, perform a restore-validation exercise rather than waiting for a failed disk or corrupted database.
The practical next step is to write down your Compose file version, volume map, secrets location, backup commands, restore commands, and test documents. Then deploy a small batch, confirm the complete ingest-to-search workflow, and only afterward make Paperless-ngx the destination for the rest of your archive.