Self Hosted Guru
/2 min readApp

Paperless-ngx: self-hosted document archive in Docker

Paperless-ngx scans, OCRs and indexes your paper documents so you can search them. How to install it with Docker Compose and PostgreSQL.

self-hosteddockerdocuments

Paperless-ngx turns a pile of paper into a searchable archive. You drop a scan or a PDF into a folder, it runs OCR, guesses the correspondent, the document type and the tags, and stores the result. After that every invoice, contract and letter can be found by its text.

What you need

  • A server with Docker and the Compose plugin
  • A scanner or a phone scanning app that can save files to a folder or send them by email

Install

The project keeps ready-made compose files in its repository. Create a folder and download the PostgreSQL variant together with its two environment files:

mkdir paperless && cd paperless
wget -O docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
wget -O docker-compose.env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
wget -O .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env

Edit docker-compose.env. One value is required and a few are worth setting:

# Required. A long random string, unique to this install.
PAPERLESS_SECRET_KEY=change-me
# The public address, if the archive is reachable through a domain
PAPERLESS_URL=https://paperless.example.com
# Your timezone, the default is UTC
PAPERLESS_TIME_ZONE=Europe/Berlin
# The language most of your documents are written in
PAPERLESS_OCR_LANGUAGE=eng
# Your user on the host, so you can write to the consume folder
USERMAP_UID=1000
USERMAP_GID=1000

Generate the secret key with:

python3 -c "import secrets; print(secrets.token_urlsafe(64))"

The compose file sets the database password to paperless. The database is not published outside the Docker network, but change POSTGRES_PASSWORD in docker-compose.yml before the first start if you want your own value, and add a matching PAPERLESS_DBPASS to docker-compose.env.

Start the stack:

docker compose pull
docker compose up -d

It runs three containers: the web server, PostgreSQL and Valkey as the task broker.

First run

Open http://<host>:8000. On the first visit Paperless-ngx asks you to create the superuser account.

Two folders appear next to the compose file:

  • consume: every file placed here is imported and then removed from the folder. Point your scanner at it.
  • export: the target for the document exporter.

Drop a PDF into consume and watch it appear in the web interface with its text recognised.

The image installs OCR data for English, German, Italian, Spanish and French. Other languages are added with PAPERLESS_OCR_LANGUAGES, see the comments in docker-compose.env.

Backup

Documents and the database live in Docker volumes (media, data, pgdata). The supported way to back up is the built-in exporter, which writes everything into the export folder:

docker compose exec -T webserver document_exporter ../export

Updating

docker compose pull && docker compose up -d

Read the release notes before a major version: the bundled PostgreSQL image tag can change between releases, and a database major upgrade needs its own steps.

Related