Homelab 12: every paper you own, scanned, read and searchable with Paperless-ngx

Level IntermediateEstimated time 1 hRead first Homelab 2: one HTTPS entrance for all your services, Homelab 5: backups that survive an attack on your serverA word you don't know? Glossary

Paperless-ngx turns paper into a searchable archive. A scan, a phone photo, an Office file or an e-mail lands in a folder; Paperless reads it with OCR, guesses the correspondent and the type, tags it, and files it. Then a search for a word finds it on any page of any document, years later.

Anything dropped in the consume folder is read (OCR in your language), converted, tagged and filed. The archive keeps the original and a searchable PDF; the exporter writes everything, files and metadata, for your backup.

A bit of history

Paperless started in 2015 as one developer's way to scan, OCR and forget his paper mail. The community carried it through two forks, paperless-ng and then paperless-ngx in 2022, adding machine-learning classification: documents file themselves by correspondent, type and tag once it has seen a few examples.

1. Run it

The project publishes Docker Compose files: Paperless with PostgreSQL and Redis, and a variant with Tika and Gotenberg to read Office documents and e-mails as well. Take that variant, pin the version, and set at least:

PAPERLESS_SECRET_KEY=<a long random value>    # required: it refuses to start without it
PAPERLESS_URL=https://paperless.yourdomain.tld  # behind a proxy: allowed hosts and CSRF in one setting
PAPERLESS_OCR_LANGUAGE=fra                       # the language of most of your papers
PAPERLESS_TIKA_ENABLED=1

Publish it through your HTTPS proxy (Homelab 2), or keep it on your private network (Homelab 6): these are your most personal documents.

2. Feed it

Share the consume folder on your network and point your scanner at it, or upload from the web page and the mobile apps. Paperless picks a file up, processes it, and removes it from the folder. Teach it once: correct the correspondent and the tags on a few documents, and the automatic matching learns.

3. Back it up the way it expects

The exporter writes every document and all the metadata (tags, correspondents, notes) into a folder you can back up and import anywhere:

docker compose exec -T webserver document_exporter ../export

Run it every night before your copy (Homelab 5). To restore: document_importer on that folder, in a fresh instance.

Traps

The OCR language defaults to English. French papers read as English come out full of errors and searches miss. French is included in the image: set fra. Combinations such as fra+eng work, at the cost of much more processor time.

A consume folder on a network share does not notify Paperless of new files. Turn on polling (PAPERLESS_CONSUMER_POLLING_INTERVAL), or files wait forever.

Copying the database alone is not a backup of Paperless: the files and the database must match. Use the exporter, which writes both consistently.

Sources

Paperless-ngx, official repository

Found this useful? Tell us what to measure next.