Paperless-ngx: Self-Hosting a Document Management System on Your NAS

Shoving paper receipts into a shoebox and taking phone photos of tax documents is a temporary fix that creates a long-term mess. Paperless-ngx solves this by turning your NAS into an automated document management system: it OCRs every scanned page, auto-tags it by correspondent and document type using machine learning, and makes everything instantly searchable. This guide walks through the full paperless-ngx setup on your NAS, covering the Docker Compose stack, the consume folder automation that makes the system truly hands-off, and the backup strategy that keeps your digital archive safe. This guide breaks down paperless-ngx setup guide in practical terms.

What Paperless-ngx Does for Your Homelab

Paperless-ngx is a self-hosted document management application that ingests scanned documents, PDFs, and emails, then applies OCR (optical character recognition) to make every word searchable. It uses machine learning to automatically classify documents by correspondent (e.g., “Electric Company,” “Dr. Smith”) and document type (e.g., “Invoice,” “Medical Report,” “Tax Statement”). The result is a fully searchable, tagged archive that eliminates paper clutter.

For a typical homelab, Paperless-ngx runs as a Docker container on your NAS alongside other services like Jellyfin or Plex. If you’re already running a best Docker server build, adding Paperless-ngx is a natural extension. The key differentiator from a simple folder of PDFs is the consume-folder automation: drop a document into a specific network folder, and Paperless-ngx processes it automatically — no manual import steps required.

Paperless-ngx Docker NAS Setup: The 3-Service Stack

Paperless-ngx runs as a multi-service Docker Compose stack with three core components. Each plays a specific role in the document processing pipeline.

Paperless-ngx Docker Compose Configuration

Here’s a minimal but production-ready docker-compose.yml for Paperless-ngx. Create a folder called paperless on your NAS, then save this file inside it.

version: "3.8"
services:
  broker:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - ./redisdata:/data

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: changeme
    volumes:
      - ./pgdata:/var/lib/postgresql/data

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./consume:/usr/src/paperless/consume
      - ./export:/usr/src/paperless/export
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: changeme
      PAPERLESS_DBNAME: paperless
      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_TIME_ZONE: America/New_York

Run docker-compose up -d and Paperless-ngx will be available at http://your-nas-ip:8000. The first startup creates an admin user; set a strong password. If you’re running this on TrueNAS SCALE, the process is similar to installing Jellyfin on TrueNAS SCALE — you’ll use the Apps interface to deploy the Docker Compose stack.

Paperless-ngx Consume Folder: The Automation Engine

The consume folder is what makes Paperless-ngx actually useful day-to-day. It’s a network-accessible directory on your NAS where you — or your scanner — can drop documents. Paperless-ngx watches this folder constantly, picks up new files, OCRs them, classifies them, and moves them into the archive. You never need to log into the web UI just to import a document.

Paperless-ngx OCR Scanner Setup: Getting the Best Results

OCR quality determines whether your document archive is genuinely searchable or just a collection of unreadable scans. Paperless-ngx uses Tesseract OCR under the hood, which works well with clean, high-contrast scans.

Scanner Settings for Optimal OCR

For multi-page documents, set your scanner to create a single PDF file rather than one PDF per page. Paperless-ngx handles multi-page documents natively and will treat them as a single entry in the archive.

Paperless-ngx Email Import: Automating Bills and Statements

Beyond physical scanning, Paperless-ngx can pull PDF attachments directly from email accounts. This is ideal for digitizing utility bills, bank statements, and credit card statements that arrive as email attachments.

To enable email import, add these environment variables to your Docker Compose file:

PAPERLESS_EMAIL_HOST: imap.gmail.com
PAPERLESS_EMAIL_PORT: 993
PAPERLESS_EMAIL_USERNAME: your-email@gmail.com
PAPERLESS_EMAIL_PASSWORD: your-app-password
PAPERLESS_EMAIL_SSL: true
PAPERLESS_EMAIL_FOLDER: INBOX
PAPERLESS_EMAIL_PROCESSED_FOLDER: Processed

Paperless-ngx will then check the inbox, download PDF attachments, process them through OCR, and move the emails to a “Processed” folder. This turns your email inbox into a document ingestion pipeline — no manual downloading required.

Backup Strategy for Paperless-ngx: Protecting Your Digital Archive

RAID is not backup. If you lose the PostgreSQL database but still have your document files, you’ve lost all the metadata — tags, correspondents, document titles, and search indexes. Conversely, if you back up only the database but lose the original files, you have an empty index. You need both.

Automated Backup with Docker and Your NAS

If you’re using ZFS snapshots on your NAS, you can snapshot the Paperless-ngx dataset before backing up. This gives you point-in-time recovery without stopping the containers — though for database consistency, stopping the containers briefly is still the safest approach.

Paperless-ngx vs. Other Self-Hosted Document Management Options

Paperless-ngx is not the only self-hosted document management system, but it’s the most popular for good reason. Here’s how it compares to alternatives.

If you’re already running Nextcloud for file sync, you can technically use it for document archiving, but Paperless-ngx’s consume-folder automation and built-in ML classification make it far more practical for a document management workflow. The trade-off is that Paperless-ngx is a single-purpose tool — it won’t replace your file sync, calendar, or contacts.

Which Should You Choose: Paperless-ngx on TrueNAS, Unraid, or a Dedicated Docker Host?

Paperless-ngx runs identically on any platform that supports Docker. The choice comes down to how your NAS is configured and whether you want to run it alongside other services.

If you’re deciding between the two, read the TrueNAS vs Unraid comparison for a broader view. For Paperless-ngx specifically, both work well. Unraid’s user-friendly share management makes the consume folder setup slightly easier for beginners; TrueNAS’s ZFS snapshots provide a more robust backup foundation for the database.

If you’re running a dedicated Docker server (like an Intel N100 mini PC), that’s actually the ideal host — it keeps Paperless-ngx isolated from your main NAS storage, reducing the risk of Docker container issues affecting your data. Check the best Docker server build guide for hardware recommendations that handle the OCR workload comfortably.

Frequently Asked Questions