Paperless-ngx: the filing cabinet that answers questions

The intake path is the part that decides if this works

Paperless watches a consumption directory. Anything dropped in is processed: OCR, classification, tagging, and a rename based on the metadata. The household pattern here is that the scanner writes to a folder on the NAS and never to Paperless directly, so a failed scan is a file sitting in a folder rather than a job that vanished.

A second consumption subfolder is set up with a different naming convention for the documents that should be treated as incoming correspondence rather than archived records. Getting the consumption structure right at the start saves re-tagging a thousand documents later.

# consume/           -> normal intake
# consume/inbox/     -> mail and bills, tagged as incoming
# drop a PDF in and watch it process
docker logs -f paperless | grep -i consuming

OCR on a Pi: slow, but the right kind of slow

Tesseract on a Pi 4 processes about twenty-five pages a minute at default settings. A ten-page utility bill takes twenty seconds; a hundred-page mortgage document takes four minutes and pins one core while it does.

The worker count is deliberately set to one. Two OCR workers on a four-core board make everything else on the rack feel sluggish, and there is no household volume of documents that justifies the second one.

Filename format and consumer-grade metadata

The filename format is a template over the metadata fields and it is applied at consumption time, not at rename time. Choosing it late means either living with inconsistent names or triggering a re-processing of the whole archive.

Dates are the field most likely to be wrong, because Paperless guesses them from the document text. For anything where the date matters legally, open the document and correct the date before it disappears into the archive, because a wrong date is harder to find later than a missing one.

PAPERLESS_FILENAME_FORMAT: '{created}-{correspondent}-{title}'
# -> 2026-03-14-Northwind Energy-Annual statement.pdf
# change it and run: document_renamer

The export is the real backup

The media directory alone is not enough: without the database, the tags, the correspondents and the document types all vanish, leaving a pile of correctly named PDFs. Without the media directory the database is a list of documents that do not exist.

document_exporter writes both plus the metadata into one portable tree that a future version of Paperless can re-import. It runs monthly here, on top of the nightly file-level copy, because it is the only artefact that survives a complete rebuild of the stack.

docker exec paperless document_exporter /usr/src/paperless/media/export \
  --no-thumbnail --use-filename-format
# the export tree is self-describing and re-importable

compose file

Drop the whole file at /srv/homelab/paperless-ngx/compose.yaml. Tags are pinned, never latest: rolling back on a Pi is far more work than upgrading.

services:
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.14.5
    container_name: paperless
    restart: unless-stopped
    ports:
      - "8010:8000/tcp"
    environment:
      TZ: Asia/Shanghai
      PAPERLESS_REDIS: redis://paperless-redis:6379
      PAPERLESS_DBHOST: paperless-db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: ${PAPERLESS_DB_PASSWORD}
      PAPERLESS_OCR_LANGUAGES: eng chi_sim
      PAPERLESS_OCR_LANGUAGE: eng+chi_sim
      PAPERLESS_TIME_ZONE: Asia/Shanghai
      PAPERLESS_URL: https://docs.lan
      PAPERLESS_OCR_MODE: skip_noarchive
      PAPERLESS_FILENAME_FORMAT: '{created}-{correspondent}-{title}'
      PAPERLESS_TASK_WORKERS: "1"
      PAPERLESS_THREADS_PER_WORKER: "1"
      USERMAP_UID: "1000"
      USERMAP_GID: "1000"
    volumes:
      - /srv/homelab/paperless/data:/usr/src/paperless/data
      - /srv/homelab/paperless/media:/usr/src/paperless/media
      - /mnt/nas/paperless-consume:/usr/src/paperless/consume
    depends_on:
      paperless-db:
        condition: service_healthy
    networks: [rack]

  paperless-redis:
    image: redis:7.4-alpine
    container_name: paperless-redis
    restart: unless-stopped
    networks: [rack]

  paperless-db:
    image: postgres:16-alpine
    container_name: paperless-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${PAPERLESS_DB_PASSWORD}
    volumes:
      - /srv/homelab/paperless/db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U paperless"]
      interval: 10s
      timeout: 5s
      retries: 6
    networks: [rack]

networks:
  rack:
    external: true

Hardening checklist

• the instance sits behind the authentication portal, because a searchable index of every household document is not something to leave on one_factor if it can be helped
• user accounts are per person and the admin account is only used for configuration, so an ordinary session cannot change the pipeline rules
• the consumption directory is a folder on the NAS that only one household account can write to, which is the intake path for the scanner
• the OCR language set is trimmed to the languages actually in use, both for speed and because unused language packs are extra untested parsing code

Verify it went in clean

• A dropped PDF appears in the archive with searchable text within a minute of being consumed
• Searching for a phrase that exists only in a scanned page returns the document, which proves OCR ran
• The document_exporter output re-imports into a scratch instance with the same tag structure
• The consumption directory is empty after a batch is processed, with anything failed moved to the failed folder rather than looping

Hardware questions

Is a Pi fast enough to OCR a real archive?

For household volumes, yes. A thousand documents averaging four pages is about two and a half hours of background OCR at one page per two and a half seconds. Run it overnight and it is done. Where the Pi struggles is bulk-importing fifty thousand pages, which is a job to do on a laptop and then move the data directory over.

What happens to documents that were scanned badly?

They end up in the archive with poor text but the original image intact, so they are still findable by the metadata you correct by hand. Re-scanning is possible but rare; better scanners and a 300 dpi setting prevent the problem rather than fixing it.

Can I use this for documents I might need to hand to someone official?

Yes, and the export tree is designed for exactly that: the originals, PDF/A versions where the mode is enabled, and the OCR text side by side. For legal matters the originals are what count, which is why the consume workflow never modifies the source file.