How to Set Up Paperless-ngx for Document Management

How to Set Up Paperless-ngx for Document Management

Paperless-ngx is a powerful document management system that transforms your physical documents into a searchable online archive. Running it on your Breeze lets you scan, tag, and organize every receipt, letter, and form with full-text OCR search capabilities.

Prerequisites

• A Breeze instance with at least 2 GB of RAM running Ubuntu 22.04+
• Docker and Docker Compose installed
• A domain or subdomain pointed to your Breeze

Step 1 — Download the Configuration

Clone the Paperless-ngx repository and prepare the Docker Compose setup:

mkdir -p ~/paperless && cd ~/paperless
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml -O docker-compose.yml
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env -O docker-compose.env

Step 2 — Configure the Environment

Edit docker-compose.env to customize your installation:

PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)
PAPERLESS_TIME_ZONE=America/New_York
PAPERLESS_OCR_LANGUAGE=eng
PAPERLESS_URL=https://docs.example.com
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=your-secure-password

Create the required data directories:

mkdir -p ./data ./media ./export ./consume

Step 3 — Start Paperless-ngx

Launch the stack, which includes PostgreSQL, Redis, Gotenberg for document conversion, and Tika for content extraction:

docker compose up -d

Wait about 60 seconds for the database migrations to complete before accessing the web interface.

Step 4 — Configure a Reverse Proxy

Set up Nginx to forward traffic to Paperless-ngx running on port 8000:

server {
    listen 443 ssl http2;
    server_name docs.example.com;
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Step 5 — Importing Documents

There are several ways to get documents into Paperless-ngx:

• Web upload — drag and drop files directly into the web interface
• Consume folder — drop files into the ./consume directory for automatic ingestion
• Email — configure an IMAP account to automatically consume emailed documents
• Mobile scanning — use any scanning app that can upload to a network share

Organizing with Tags and Correspondents

Paperless-ngx uses matching algorithms to automatically assign tags, correspondents, and document types. Set up matching rules in the admin panel under Settings → Matching. For example, create a tag called "Tax" with auto-matching on keywords like "IRS", "W-2", or "1099" so that tax documents are automatically categorized upon import.

Backup Strategy

Use the built-in exporter to create portable backups:

docker compose exec webserver document_exporter ../export

Schedule this command via cron on your Breeze to ensure regular backups of your entire document archive.