How to Set Up Paperless-ngx With Docker (Go Paperless in an Afternoon)

Paperless-ngx is a document management system that takes your scanned documents, PDFs, and photos of receipts and makes them searchable. OCR extracts the text, automatic tagging applies based on rules you set, and the result is a searchable archive you can query from a browser.

I’ve been running it for over a year. Scanning a piece of mail takes about 10 seconds — drop it in a folder, Paperless does the rest. I haven’t thought about filing since.

This guide covers a full Docker Compose setup with Redis and a PostgreSQL backend (the production-appropriate stack), plus the inbox folder configuration.

Before you start: Docker and Docker Compose are required. Docker setup guide →

The compose file

Paperless-ngx requires three containers: the application itself, Redis (for task queuing), and a database (Postgres or SQLite — Postgres is better for anything beyond a test install).

Create the directory:

mkdir -p ~/docker/paperless-ngx
cd ~/docker/paperless-ngx

Create docker-compose.yml:

services:
  broker:
    image: docker.io/library/redis:7
    container_name: paperless-redis
    restart: unless-stopped
    volumes:
      - ./redis:/data

  db:
    image: docker.io/library/postgres:16
    container_name: paperless-postgres
    restart: unless-stopped
    volumes:
      - ./postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: changeme-use-a-real-password

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless-ngx
    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_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: changeme-use-a-real-password
      PAPERLESS_SECRET_KEY: change-this-to-a-random-string-at-least-50-chars
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: changeme
      PAPERLESS_ADMIN_MAIL: [email protected]
      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_TIME_ZONE: America/New_York
      PAPERLESS_URL: https://paperless.yourdomain.com

The /consume volume is important — this is the inbox. Any file you drop into ~/docker/paperless-ngx/consume on your server gets processed automatically.

Start it:

docker compose up -d

The first start takes a few minutes while the database initializes. Access the UI at http://your-server-ip:8010.

Log in with the admin credentials you set in the environment variables.

Configure your first correspondent and tags

Before throwing documents at it, set up some basic organization.

Correspondents are the senders — your bank, your insurance company, the IRS. Paperless can auto-assign them based on content matching rules.

Go to Settings → Correspondents → Add. Add a few:

• Your bank name
• Insurance company
• Utility company

Tags are categories. I use:

• Finance
• Medical
• Insurance
• Tax
• Home
• Vehicle

To auto-assign tags, go to a tag and click Add Matching Rule:

• Pattern: State Farm (text that appears in the document)
• Algorithm: Any word
• Case insensitive: Yes
• Assign tag: Insurance

Build these rules gradually as you add documents. Don’t try to set up everything perfectly before you start.

Setting up the consume folder

The ~/docker/paperless-ngx/consume directory is watched continuously. Drop a PDF, JPG, PNG, or TIFF there and Paperless picks it up within a minute or two, OCRs it, and adds it to the inbox.

A few ways to use this:

Scanner with network folder: Most modern document scanners can scan to a network share. Mount your consume folder as a Samba share, point the scanner at it, and scanning becomes one-button operation.

Phone scanning: A mobile scanning app (I use the iOS Files app with a shortcut) can upload directly to a folder. If you have Syncthing running, you can sync a phone folder to the consume directory.

Email-to-paperless: Paperless-ngx has an email consumption feature. Configure it to check an email address and process attachments automatically. Set it up under Settings → Mail Accounts.

Drag and drop: The web UI has a direct upload button. Not automated, but works fine for batch uploading an existing pile of PDFs.

Configure storage paths (optional)

By default, Paperless names stored files with internal IDs. You can configure a template that creates human-readable paths:

Go to Settings → Document Processing → Storage Path:

{created_year}/{correspondent}/{title}

This organizes files like 2026/State Farm/Auto Insurance Renewal.pdf in the underlying storage — useful if you ever need to access files directly.

Set up a proxy host in NPM

Paperless shouldn’t be exposed to the internet, but you want HTTPS access on your local network and via Tailscale.

In Nginx Proxy Manager, add a new proxy host:

• Domain: paperless.yourdomain.com
• Forward to: your-server-ip:8010
• SSL: Request certificate, force SSL on

Update the PAPERLESS_URL in your compose file to match this URL and restart:

docker compose down && docker compose up -d

Backing up Paperless

The most important thing to back up: the media folder contains all your actual documents. The data folder contains the database (if using SQLite — with Postgres, back up the postgres folder).

# Manual backup
tar -czf paperless-backup-$(date +%Y%m%d).tar.gz ~/docker/paperless-ngx/media ~/docker/paperless-ngx/data

Automate this with a cron job or include it in your Proxmox backup schedule.

Troubleshooting

Documents stuck in inbox: Check logs with docker logs paperless-ngx. Common causes: permissions issue on the consume folder, Celery worker not running, Redis connection problem.

Poor OCR quality: Try adding PAPERLESS_OCR_PAGES: 1 to skip blank pages, or adjust PAPERLESS_OCR_MODE: skip_noarchive to skip re-OCR of already-searchable PDFs.

High CPU usage: OCR is CPU-intensive. Add PAPERLESS_TASK_WORKERS: 1 to limit parallelism if it’s overwhelming your machine.

For document files you want to sync offsite alongside Paperless, Syncthing is a clean pairing — Syncthing setup guide →.