Paperless-ngx: Go Paperless with Self-Hosted Document Management

Escape the Paper Chaos

Receipts, invoices, contracts, warranties, tax documents - paper accumulates relentlessly. Finding that one receipt from two years ago means digging through boxes and folders. There has to be a better way.

Paperless-ngx is a document management system that transforms your physical documents into a searchable, organized digital archive. Scan it once, find it instantly forever.

Key Features

• OCR processing: Automatically extracts text from scanned documents
• Full-text search: Find documents by any word they contain
• Auto-tagging: Machine learning suggests tags and correspondents
• Email consumption: Forward emails with attachments directly to Paperless
• Mobile scanning: Use your phone as a scanner
• Customizable workflows: Automatic matching and filing rules

Docker Compose Setup

version: "3.8"

services:
  paperless-broker:
    image: redis:alpine
    container_name: paperless-broker
    restart: unless-stopped

  paperless-db:
    image: postgres:15
    container_name: paperless-db
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped

  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    depends_on:
      - paperless-db
      - paperless-broker
    ports:
      - "8000: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://paperless-broker:6379
      PAPERLESS_DBHOST: paperless-db
      PAPERLESS_DBPASS: ${DB_PASSWORD}
      PAPERLESS_SECRET_KEY: ${SECRET_KEY}
      PAPERLESS_TIME_ZONE: America/New_York
      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
    restart: unless-stopped

volumes:
  pgdata:

Environment Configuration

Create a .env file:

DB_PASSWORD=your_database_password
SECRET_KEY=your_very_long_random_secret_key
ADMIN_PASSWORD=your_admin_password

Generate the secret key with:

openssl rand -base64 64

Setting Up Document Consumption

Paperless watches the consume folder for new documents. Any file placed there is automatically processed.

Scanner Integration

Configure your network scanner to save directly to the consume folder:

• Set up SMB/CIFS share pointing to the consume folder
• Configure scanner to save as PDF to this share
• Documents are automatically imported and OCR'd

Mobile Scanning

Use apps like Adobe Scan, Microsoft Lens, or SwiftScan to capture documents with your phone, then upload to the consume folder or use the web interface.

Organizing with Tags and Correspondents

Paperless uses three main organizational methods:

• Tags: Categories like "Tax", "Medical", "Receipts", "Important"
• Correspondents: Who the document is from/to (companies, people)
• Document Types: Invoice, Contract, Letter, Receipt

Create matching rules to automatically apply these based on document content:

# Example matching rule
If document contains "Amazon" → Set correspondent to "Amazon"
If document contains "Invoice" → Set document type to "Invoice"
If document contains "Tax" → Add tag "Tax Documents"

Email Consumption

Forward emails with attachments directly to Paperless. Add this to your environment:

PAPERLESS_EMAIL_TASK_CRON: "*/10 * * * *"
PAPERLESS_EMAIL_HOST: imap.gmail.com
PAPERLESS_EMAIL_PORT: 993
PAPERLESS_EMAIL_HOST_USER: [email protected]
PAPERLESS_EMAIL_HOST_PASSWORD: your_app_password

Forward receipts and important emails to a dedicated address, and they'll appear in Paperless automatically.

Practical Workflow

Here's a real-world paperless workflow:

• Daily: Mail comes in → Scan immediately → Shred original
• Receipts: Snap photo with phone → Upload → Auto-tagged
• Emails: Forward important PDFs → Auto-processed
• Tax time: Filter by "Tax" tag → Export all documents

Search That Actually Works

The real power of Paperless is search. OCR processes every document, so you can search by:

• Any word in the document text
• Date ranges
• Tags, correspondents, document types
• Custom fields you define

Find that warranty certificate by searching the product name. Find all invoices from a vendor instantly.

Never Lose a Document Again

With Paperless-ngx, every important document is a search away. No more digging through filing cabinets or hoping you kept that receipt. Scan once, find forever - that's the promise of a paperless homelab.