Set Up Paperless-NGX as a Self-Hosted Document Archive

Why Paperless-NGX Belongs on Your Home Server

Paper documents pile up fast – tax returns, insurance policies, medical records, rental agreements. Scanning them into a folder on your desktop solves nothing, because finding any specific file six months later becomes its own project. Paperless-NGX fixes this by giving every scanned document a searchable index, automatic tag suggestions, and a clean web interface that works from any device on your network. It is the difference between a digital shoebox and an actual archive.

Paperless-NGX is a community-maintained fork of the original Paperless project, built around Django and a Python-based OCR pipeline. It supports automatic document ingestion from a watched folder, full-text search powered by Whoosh or Elasticsearch, and correspondent tagging that learns your patterns over time. If you already run a home server with Docker, adding Paperless-NGX is straightforward. This guide walks through the full setup using Docker Compose, from initial configuration to your first scanned document.

What You Need Before You Start

The minimum hardware requirement is modest – a machine with at least 2GB of RAM and a couple of gigabytes of free disk space to start, though your archive will grow. Paperless-NGX runs comfortably on a Raspberry Pi 4, an old mini PC, or any server already handling other self-hosted services. Docker and Docker Compose must be installed. If you are also running Uptime Kuma as a self-hosted status page monitor, you already have the right environment.

You will also want a scanner or a scanning app on your phone. Android apps like Microsoft Lens or Adobe Scan output PDF files that Paperless-NGX handles well. The application accepts PDFs, images in JPEG and PNG format, and plain text files. Anything dropped into the consume folder gets picked up automatically, OCR’d, and indexed without manual intervention.

Setting Up With Docker Compose

Paperless-NGX ships with an official Docker Compose configuration that bundles the web application, a Redis broker, and a PostgreSQL database into a single stack. Start by downloading the official docker-compose.yml and .env files from the Paperless-NGX GitHub releases page. The project maintains versioned releases, so grab the latest stable tag rather than pulling from the main branch.

Open the .env file in a text editor. The variables you need to set immediately are PAPERLESS_URL, which should match the address you plan to use to access the app, PAPERLESS_SECRET_KEY, which is a random string you generate yourself, and PAPERLESS_TIME_ZONE, set to your local timezone in standard format like America/New_York or Europe/London. Set PAPERLESS_OCR_LANGUAGE to the language code matching your documents – eng for English, deu for German, or a combined string like eng+fra for multilingual archives. Wrong timezone settings will cause document date parsing to produce incorrect results, which affects how the automatic date detection feature works on receipts and letters.

The Compose file defines three volume mounts you should map to real directories on your host: one for consumed documents, one for the media storage where processed files live, and one for export backups. Create these directories before running the stack. A typical layout places them under a single paperless folder in your home directory or wherever you keep Docker data. The consume directory is the inbox – anything you drop there gets processed and moved to media storage. Do not store originals only in the consume folder, because the application moves files out of it after ingestion.

With the configuration in place, run docker compose up -d from the directory containing your Compose file. The first startup takes a few minutes while the containers initialize and the database schema is created. Once the stack is running, create your admin account by executing docker compose exec webserver python3 manage.py createsuperuser and following the prompts. That account is how you log into the web interface for the first time.

Configuring Tags, Correspondents, and Document Types

Paperless-NGX organizes documents across three dimensions: tags, correspondents, and document types. Correspondents are the entities that send or receive documents – your bank, your employer, your landlord. Document types are categories like Invoice, Statement, or Contract. Tags are freeform labels you can stack on any document. None of these are mandatory, but building them out before you start ingesting documents pays off when you are searching for a specific utility bill from two years ago.

The application includes a workflow automation feature that applies tags, correspondents, and document types based on rules you define. A rule can match on the text content of a document – if the word “Verizon” appears in the body, assign the correspondent “Verizon” and the tag “Utilities” automatically. Building out a basic set of rules for your most common document senders takes around thirty minutes and reduces manual sorting to near zero for routine paperwork. You access this under Settings – Workflows in the web interface.

Ingesting Documents and Searching the Archive

The consume folder is the simplest ingestion method. Set up an automatic sync from your phone’s scanner app to that directory using Syncthing, a network share, or SFTP, and every scan you take will be processed within a minute or two of landing on the server. Paperless-NGX also supports email ingestion, where it polls a mailbox and pulls in attachments matching rules you configure – useful for e-statements and digital invoices that never existed as paper.

Full-text search covers the OCR’d content of every document in your archive. Type a fragment of an account number, a dollar amount, or a date range into the search bar and Paperless-NGX returns matches across the full body text, not just filenames or tags. The default Whoosh backend handles archives of several thousand documents without any extra configuration. For archives reaching tens of thousands of documents, switching to an Elasticsearch backend gives noticeably faster query times, and the Compose file includes an optional Elasticsearch service definition you can uncomment.

The saved views feature lets you pin filtered queries to your dashboard – all untagged documents, everything ingested in the last seven days, or invoices with no correspondent assigned. Running a saved view for untagged documents as a daily check takes thirty seconds and keeps your archive from quietly accumulating clutter. A messy Paperless-NGX archive is almost always the result of skipping this step for a few weeks, not a flaw in the application itself.