Physical paperwork, tax records, medical receipts, and appliance manuals clutter physical space and are notoriously difficult to retrieve when needed. Storing unorganized scanned PDFs on standard file shares provides no text indexing or metadata filtering.

Paperless-ngx transforms physical documents into a fully indexed, searchable digital library. Utilizing automated Tesseract Optical Character Recognition (OCR), machine learning document classification, and background consumption folders, Paperless-ngx organizes your household records automatically.

# compose.yaml
services:
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.14.7
    container_name: paperless-ngx
    restart: unless-stopped
    depends_on:
      - paperless-db
      - paperless-valkey
    environment:
      - PAPERLESS_REDIS=redis://paperless-valkey:6379
      - PAPERLESS_DBSERVER=paperless-db
      - PAPERLESS_DBNAME=paperless
      - PAPERLESS_DBUSER=paperless
      - PAPERLESS_DBPASS_FILE=/run/secrets/db_password
      - PAPERLESS_SECRET_KEY_FILE=/run/secrets/secret_key
      - PAPERLESS_URL=https://paperless.example.com
      - PAPERLESS_TIME_ZONE=America/Denver
      - PAPERLESS_OCR_LANGUAGE=eng
      - PAPERLESS_TASK_WORKERS=2
    secrets:
      - db_password
      - secret_key
    volumes:
      - /mnt/fastpool/apps/paperless/data:/usr/src/paperless/data
      - /mnt/datapool/documents/media:/usr/src/paperless/media
      - /mnt/datapool/documents/consume:/usr/src/paperless/consume
      - /mnt/datapool/documents/export:/usr/src/paperless/export
    networks:
      - paperless-net
      - proxy-tier
    deploy:
      resources:
        limits:
          memory: 3G

  paperless-db:
    image: postgres:16-alpine
    container_name: paperless-db
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    environment:
      - POSTGRES_DB=paperless
      - POSTGRES_USER=paperless
      - POSTGRES_PASSWORD_FILE=/run/secrets/db_password
    secrets:
      - db_password
    volumes:
      - /mnt/fastpool/apps/paperless/pgdata:/var/lib/postgresql/data
    networks:
      - paperless-net

  paperless-valkey:
    image: valkey/valkey:8.0-alpine
    container_name: paperless-valkey
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    networks:
      - paperless-net

secrets:
  db_password:
    file: ./secrets/db_password.txt
  secret_key:
    file: ./secrets/secret_key.txt

networks:
  paperless-net:
  proxy-tier:
    external: true

1. The Automated Document Pipeline

Paperless-ngx operates around an automated document lifecycle:

1. Ingestion (Consumption Directory): Any document dropped into the /consume directory (via network scanner, mobile scanner app, or Samba share) is instantly picked up by an inotify filesystem watcher.
2. OCR Processing: The document is processed by Tesseract OCR, generating a searchable PDF layer while preserving the original document unmodified.
3. Classification & Tagging: Built-in machine learning models analyze the text to automatically apply correspondent labels (e.g. “Internal Revenue Service”), document types (e.g. “Tax Return”), and dates.
4. Structured Storage: Files are automatically saved into deterministic filesystem structures using template rules (e.g. {created_year}/{correspondent}/{title}.pdf).

2. Network Scanner & Mobile Ingestion

To achieve a frictionless household workflow, expose the /consume folder as an SMB share on your local network:

• Physical Network Scanners: Configure your all-in-one printer/scanner to save directly to \\nas.home.local\paperless-consume with a single physical button press.
• Mobile Ingestion: Use mobile scanner apps (like QuickScan on iOS or Document Scanner on Android) configured to upload directly via WebDAV or Tailscale.

3. Automated Document Export & Offsite Archiving

Never lock your documents inside a database. Configure Paperless-ngx to maintain a plain-filesystem mirrored export:

# Trigger an automated plaintext export mirroring physical folders
docker exec -t paperless-ngx document_exporter /usr/src/paperless/export

This exports all documents alongside human-readable metadata sidecar files (manifest.json), ensuring your entire household archive remains accessible even if the application is rebuilt from scratch.

Related Runbooks in This Series

• OpenZFS Dataset Architecture, ARC Caching & TrueNAS SCALE Optimization
• Automated Encrypted Remote Backups with Restic, Systemd Timers & Backblaze B2 / S3
• Modern Reverse Proxy Architecture: Caddy Server & Cloudflare Tunnels for Container Ingress
• Fleet-Wide Intrusion Prevention: Deploying CrowdSec with Docker, Caddy & Firewall Bouncers