Set Up Paperless-NGX for Self-Hosted Document Management

Getting Started with Paperless-NGX

Paper documents pile up faster than most people plan for. Tax returns, insurance policies, medical records, lease agreements – stored in folders, shoved in drawers, occasionally lost when it matters most. Paperless-NGX is a self-hosted document management system that lets you scan, tag, and search every document you own, all from a web interface running on your own hardware or a private server. No subscription, no cloud vendor, no data leaving your network unless you choose it.

The project is a community-maintained fork of the original Paperless and Paperless-ng, both of which are no longer actively developed. Paperless-NGX picks up where they left off and adds a cleaner UI, better tag handling, custom fields, and active bug fixes. It runs inside Docker, connects to a scanner or watched folder, and uses optical character recognition to make every document fully searchable by its actual content – not just its filename.

Setup takes roughly an hour if you have Docker already installed.

Prerequisites and Installation

You need a machine running Linux, macOS, or Windows with Docker and Docker Compose installed. A Raspberry Pi 4 with 4GB RAM works, though OCR processing will be slower compared to a standard x86 machine. A spare desktop or a small home server like a Beelink Mini PC is a more comfortable option if you are scanning large volumes. Make sure ports 8000 (or whichever you assign) are accessible from your local network, and that you have at least 20GB of storage free for documents and the database.

Pull the official Docker Compose configuration from the Paperless-NGX GitHub repository. The quickstart script at github.com/paperless-ngx/paperless-ngx generates a docker-compose.yml and a .env file automatically. Run the script, open the generated .env file, and set PAPERLESS_URL to your server’s local IP address. Set PAPERLESS_TIME_ZONE to your timezone string (e.g., America/New_York). Optionally, set PAPERLESS_OCR_LANGUAGE – the default is English, but it supports over 100 languages via Tesseract. Once those values are in place, run docker compose up -d from the directory containing your compose file.

First boot takes a few minutes while containers initialize and the database migrates. After that, create your admin account by running docker compose exec webserver createsuperuser and following the prompts. Navigate to http://your-server-ip:8000 in a browser, log in with those credentials, and you are looking at a live Paperless-NGX instance.

Configuring Consumption, Tags, and Search

The consumption folder is where documents enter the system. Any file dropped into that folder – PDF, JPEG, PNG, TIFF – gets picked up automatically, run through OCR, and added to your document library. Inside the Docker Compose setup, this folder is mapped from a path on your host machine to the container’s internal consume directory. Set that path in your .env file using the PAPERLESS_CONSUMPTION_DIR variable, pointed at a folder your scanner or network share can write to. Once configured, you can connect any scanner that supports saving to a network folder, or use a mobile scanning app like Adobe Scan or Microsoft Lens to drop files directly into that path.

Tags, document types, and correspondents are the three organizing layers Paperless-NGX gives you. Tags work like labels – a document can have multiple. Document types are broader categories: Invoice, Contract, Medical Record. Correspondents are the sender or issuer: your bank, your insurer, your landlord. You can create these manually from the Settings menu, but the more powerful approach is to set up automatic matching rules. Under Settings, each tag or correspondent has a matching algorithm option – you can set it to match on a keyword, a regular expression, or let the built-in auto classifier learn from your manual assignments over time. After you manually tag around 10-20 documents consistently, the classifier starts predicting correctly on new ones.

Full-text search is what makes the whole system worth building. Because OCR extracts text from every document at ingestion, you can search for a dollar amount, a policy number, or a doctor’s name and get results instantly across hundreds or thousands of files. The search bar on the main documents view supports basic keyword queries, but you can also filter by tag, correspondent, document type, date range, and custom fields simultaneously. Custom fields are a newer addition – they let you attach structured data to documents, like an expiration date on an insurance policy or a reference number on a contract, and then filter your library by those values directly.

Remote Access, Backups, and Long-Term Maintenance

Keeping Paperless-NGX accessible only on your local network is fine for most home setups, but if you want to access it remotely, a reverse proxy behind a VPN is the recommended approach. Running Tailscale on both your server and your devices gives you a private encrypted connection without exposing port 8000 to the public internet. Alternatively, Cloudflare Tunnel can expose the service via a domain you control, with authentication layered on top through Cloudflare Access. Avoid putting Paperless-NGX directly on the public internet without authentication hardening – the document library you are building will contain sensitive personal records.

Backups need to cover three things: the media folder where document files are stored, the PostgreSQL or SQLite database, and the .env configuration file. The built-in document_exporter management command exports everything – files and metadata – into a portable archive you can restore from scratch. Automate this with a cron job or a scheduled Docker exec command running nightly. Store backup archives somewhere off the host machine: an external drive, a NAS, or an encrypted cloud storage bucket. Losing the database while keeping the PDFs means losing all tags, correspondents, and metadata you have built up.

Updates are straightforward. Pull the latest images with docker compose pull, then restart with docker compose up -d. Paperless-NGX runs database migrations automatically on startup, so the process rarely requires manual steps. Check the release notes on GitHub before major version updates – the project does occasionally introduce breaking changes in configuration variables.

What makes Paperless-NGX worth the setup time is not just the search or the tags – it is the shift from a reactive system (finding a document when you desperately need it) to a proactive one. Every piece of paper that enters your home becomes a searchable, indexed, backed-up record within minutes of scanning. The question is not whether you will eventually need a document you threw away or misplaced – you already know you will.