How to Set Up Paperless-ngx for a Paperless Home Office
Stop drowning in physical paperwork. Learn how to install, configure, and optimize Paperless-ngx to automatically organize, OCR, and search your documents.
In this article
- Why Paperless-ngx is the Ultimate Document Archive
- System Requirements and Hardware Options
- Step-by-Step Installation via Docker Compose
- Step 1: Prepare Your Directory Structure
- Step 2: Create the Docker Compose File
- Step 3: Launch the Stack
- Step 4: Create Your Admin Account
- Setting Up Your Document Ingestion Pipeline
- 1. The Network-Shared “Consume” Folder
- 2. Mobile Scanning Apps
- 3. Automated Email Ingestion
- Organizing Your Archive: Tags, Correspondents, and Types
- Securing and Backing Up Your Document Archive
- Local Security and Encryption
- The 3-2-1 Backup Strategy
- Conclusion
- Frequently Asked Questions
- Can I run Paperless-ngx without Docker?
- How does Paperless-ngx handle handwritten documents?
- Can I edit documents directly inside Paperless-ngx?
- What physical scanner works best with this setup?
- How do I access Paperless-ngx when I am away from home?
Despite decades of digital advancement, physical paperwork remains an unavoidable part of modern life. Tax forms, medical records, utility bills, appliance manuals, and receipts constantly threaten to clutter our physical desks and filing cabinets. Traditional digital filing methods—such as throwing PDFs into a nested folder structure on your hard drive—often fail because they require manual naming discipline and offer poor searchability.
Paperless-ngx solves this problem. It is an open-source, self-hosted document management system (DMS) that transforms your physical documents into a searchable, organized digital archive. By leveraging Optical Character Recognition (OCR) and machine learning, Paperless-ngx automatically analyzes your scanned documents, extracts text, assigns tags, and makes everything searchable within seconds. This guide provides a comprehensive walkthrough for setting up, configuring, and optimizing Paperless-ngx for your home or small office.
Why Paperless-ngx is the Ultimate Document Archive
Unlike commercial cloud storage services, Paperless-ngx runs locally on your own hardware. This approach offers three major advantages:
- Absolute Privacy: Your sensitive financial, medical, and legal documents never leave your local network or land on third-party servers.
- Powerful OCR Engine: Powered by Tesseract OCR, the system reads every word in your documents, making even scanned PDFs and images fully searchable.
- Intelligent Automation: Once you train the system with a few documents, its built-in machine learning model automatically assigns correspondents, document types, and tags to newly imported files.
System Requirements and Hardware Options
Because Paperless-ngx uses OCR processing, it requires a moderate amount of CPU power when importing new documents. However, once idle, its resource footprint is minimal. You can host it on several different hardware setups:
- A Dedicated Home Server or Mini PC: An Intel N100 or older Core i3/i5 mini PC running Linux (Ubuntu or Debian) is the ideal balance of power and energy efficiency.
- A Network Attached Storage (NAS): Synology, QNAP, or TrueNAS systems that support Docker (Container Manager) work exceptionally well.
- A Raspberry Pi: A Raspberry Pi 4 (4GB or 8GB) or Raspberry Pi 5 can handle the workload, though OCR processing of large multi-page PDFs will take slightly longer.
Step-by-Step Installation via Docker Compose
The most reliable and maintainable way to run Paperless-ngx is using Docker Compose. This method packages the application, database, and caching layers into isolated containers that can be updated with a single command.
Step 1: Prepare Your Directory Structure
First, connect to your server via SSH and create a dedicated folder structure for Paperless-ngx. Organizing your folders early prevents configuration headaches later.
Run the following commands to create the directories:
mkdir -p ~/paperless/data ~/paperless/media ~/paperless/consume ~/paperless/export
Here is what these folders do:
- data: Stores the application database and configuration files.
- media: Stores your actual digitized PDF documents.
- consume: The “watch” folder. Any PDF or image dropped here is automatically processed and imported.
- export: Used for running automated backups.
Step 2: Create the Docker Compose File
Navigate into your main directory and create the configuration file:
cd ~/paperless && nano docker-compose.yml
Paste the following standardized, robust PostgreSQL-backed configuration into the file:
version: "3.4"
services:
broker:
image: docker.io/library/redis:7
restart: unless-stopped
volumes:
- ./redis:/data
db:
image: docker.io/library/postgres:15
restart: unless-stopped
volumes:
- ./pgdata:/var/lib/postgresql/data
environment:
POSTGRES_DB: paperless
POSTGRES_USER: paperless
POSTGRES_PASSWORD: UseAStrongPasswordHere
webserver:
image: ghcr.io/paperless-ngx/paperless-ngx:latest
restart: unless-stopped
depends_on:
- db
- broker
ports:
- "8010:8000"
volumes:
- ./data:/usr/src/paperless/data
- ./media:/usr/src/paperless/media
- ./export:/usr/src/paperless/export
- ./consume:/usr/src/paperless/consume
environment:
PAPERLESS_REDIS: redis://broker:6379
PAPERLESS_DBHOST: db
PAPERLESS_DBPORT: 5432
PAPERLESS_DBNAME: paperless
PAPERLESS_DBUSER: paperless
PAPERLESS_DBPASS: UseAStrongPasswordHere
PAPERLESS_OCR_LANGUAGE: eng
PAPERLESS_TIME_ZONE: America/New_York
PAPERLESS_URL: http://your-server-ip:8010
Note: Replace “UseAStrongPasswordHere” with a unique password, and update the timezone and URL to match your local network environment. Save and close the file.
Step 3: Launch the Stack
Start the containers in detached mode by running:
docker compose up -d
Docker will download the images and start the services. This may take a couple of minutes depending on your internet connection.
Step 4: Create Your Admin Account
Once the containers are running, you must create a superuser account to log into the web interface. Run the following command:
docker compose run --rm webserver createsuperuser
Follow the on-screen prompts to set a username, email address, and secure password.
Setting Up Your Document Ingestion Pipeline
Now that Paperless-ngx is running, you can access the interface by opening a web browser and navigating to http://your-server-ip:8010. Log in with the credentials you just created.
The real power of Paperless-ngx lies in how easily you can feed documents into it. Here are the three most efficient ways to set up your ingestion pipeline:
1. The Network-Shared “Consume” Folder
By sharing the ~/paperless/consume folder on your local network using Samba (SMB), any device on your Wi-Fi network can drop files into it. Most physical document scanners support “Scan to SMB.” You can configure your physical scanner to send PDFs directly to this folder. The moment the scanner finishes, Paperless-ngx picks up the file, OCRs it, and deletes the temporary file from the consume directory.
2. Mobile Scanning Apps
You do not need a bulky flatbed scanner to use Paperless-ngx. Mobile applications like Paperless Mobile (iOS) or Swift Paperless (Android) connect directly to your instance via API. Alternatively, you can use document scanners like Adobe Scan or Genius Scan to export PDF files directly to your self-hosted network share or WebDAV folder.
3. Automated Email Ingestion
Many invoices and utility bills arrive via email. Paperless-ngx features a built-in mail processor. Under Settings > Mail Rules, you can connect Paperless-ngx to a dedicated email account (or a specific folder in your existing inbox via IMAP). You can create rules that say: “If an email arrives from ‘utilitycompany.com’ with a PDF attachment, download the attachment, import it, and mark the email as read.”
Organizing Your Archive: Tags, Correspondents, and Types
When you first upload documents, they will appear in your inbox as uncategorized text. To unlock the power of automated organization, you must establish three metadata pillars:
- Correspondents: Who sent the document (e.g., “IRS,” “State Farm,” “Water Department”).
- Document Types: What category of document it is (e.g., “Invoice,” “Tax Return,” “Medical Record,” “Contract”).
- Tags: Functional labels to help you track actions (e.g., “Tax-Year-2024,” “To-Pay,” “Urgent”).
When you manually assign these fields to your first 10 to 20 documents, make sure the matching algorithm for each tag is set to Auto. Over time, Paperless-ngx’s neural network will learn from your habits. By matching text patterns, it will accurately predict and apply these fields to new documents automatically, requiring you only to review and confirm them.
Securing and Backing Up Your Document Archive
Because these documents contain sensitive personal data, security and backup strategies are non-negotiable.
Local Security and Encryption
Always run Paperless-ngx behind a local reverse proxy (like Nginx Proxy Manager, Caddy, or Cloudflare Tunnels) if you intend to access it outside your home network. Ensure you enable HTTPS to encrypt traffic between your devices and the server.
The 3-2-1 Backup Strategy
Do not rely solely on the running Docker containers for data safety. If your server’s drive fails, you risk losing your entire archive. Implement this backup workflow:
- Use the Document Exporter: Paperless-ngx includes a utility that exports all your PDFs alongside their metadata. Run this command regularly via a cron job:
docker compose exec webserver document_exporter ../export/ - Backup the Export Folder: Use a backup utility like Restic, BorgBackup, or Duplicati to encrypt and copy the
~/paperless/exportand~/paperless/mediadirectories to an external drive or a secure cloud storage provider (like Backblaze B2 or Rsync.net).
Conclusion
Transitioning to a paperless home office requires an initial investment of time and configuration, but the long-term payoff is immense. With Paperless-ngx, you will never waste hours digging through physical folders or poorly named files to find an appliance warranty, a medical receipt, or a tax document. By self-hosting your archive, you retain complete ownership of your data while enjoying a fast, automated, and modern document search experience.
Frequently Asked Questions
Can I run Paperless-ngx without Docker?
Yes, but it is highly discouraged. A bare-metal installation requires manually configuring Gunicorn, Celery, Redis, PostgreSQL, Tesseract, and various system dependencies. Docker handles all of these components seamlessly, making updates as simple as running a single pull command.
How does Paperless-ngx handle handwritten documents?
The Tesseract OCR engine is optimized for printed text. While it can occasionally read exceptionally neat handwriting, it will struggle with cursive or messy notes. For handwritten documents, rely on descriptive manual tagging and title naming to ensure searchability.
Can I edit documents directly inside Paperless-ngx?
No. Paperless-ngx is designed strictly as a read-only document archive and retrieval system. If you need to edit a PDF, you must download it, make the changes using an external PDF editor, and upload the revised version as a new document or a new document version.
What physical scanner works best with this setup?
Any scanner that can output to multi-page PDF and save files directly to a network folder (SMB/FTP) or email them will work. Dedicated document scanners like the Fujitsu ScanSnap series are highly popular in the self-hosting community due to their speed and reliability.
How do I access Paperless-ngx when I am away from home?
To access your archive securely on the go, avoid exposing the port directly to the internet. Instead, use a self-hosted VPN solution like WireGuard or Tailscale. This allows you to securely tunnel into your home network and access Paperless-ngx as if you were sitting at your desk.