Install Paperless-ngx on a Home Server: Docker Compose Guide

A document management system in your home network has one advantage: your documents never leave the house. Paperless-ngx recognizes the text of scans and PDFs, sorts by tags and correspondents, and lets you find everything in seconds.

This guide installs Paperless-ngx 3 with Docker Compose on a home server, mini PC or Raspberry Pi. Access runs over the local network. If you want access from outside, use the guide for a VPS with HTTPS or put a reverse proxy in front, as described in Caddy as a reverse proxy. For a Synology NAS there is a separate guide.

Requirements

• A Linux machine with Docker and Docker Compose. I show everything on Debian 13; it works the same on Ubuntu or 64-bit Raspberry Pi OS.
• At least 2 GB RAM. The stack uses about 1.2 GB at idle, and text recognition needs extra room.
• Enough storage for your documents. A PDF page rarely exceeds 200 KB; with originals and archive copy, count on roughly double per page.
• A fixed IP address for the machine, for example 192.168.1.10. You need it for the address in the browser.

Install Docker with the official script:

curl -fsSL https://get.docker.com | sudo sh

Create the folders

mkdir -p ~/paperless/{data,media,export,consume,db,valkey}
cd ~/paperless

• media holds your documents, data the search index and settings.
• export receives backups.
• consume is the inbox folder for scanners and files.
• db and valkey belong to the database containers.

The Paperless container runs with user ID 1000. Check it with id -u. If the number is different, adjust USERMAP_UID and USERMAP_GID below.

Generate credentials

The following block generates a secret key and two passwords and writes the .env. Replace the IP address with your machine’s:

cat > .env <<EOF
PAPERLESS_URL=http://192.168.1.10:8000
PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu+eng
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=$(openssl rand -hex 16)
USERMAP_UID=1000
USERMAP_GID=1000
POSTGRES_PASSWORD=$(openssl rand -hex 16)
EOF
cat .env

Note the admin password. The file contains secrets and does not belong in a Git repository. Set PAPERLESS_TIME_ZONE and PAPERLESS_OCR_LANGUAGE to match you and your documents.

The compose.yaml

nano compose.yaml

services:
    broker:
        image: valkey/valkey:9
        container_name: paperless-valkey
        restart: unless-stopped
        volumes:
            - ./valkey:/data

    db:
        image: postgres:18
        container_name: paperless-db
        restart: unless-stopped
        volumes:
            - ./db:/var/lib/postgresql
        environment:
            POSTGRES_DB: paperless
            POSTGRES_USER: paperless
            POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

    gotenberg:
        image: gotenberg/gotenberg:8.38
        container_name: paperless-gotenberg
        restart: unless-stopped
        command:
            - "gotenberg"
            - "--chromium-disable-javascript=true"
            - "--chromium-allow-list=^file:///tmp/.*"

    tika:
        image: apache/tika:3.3.1.0
        container_name: paperless-tika
        restart: unless-stopped

    paperless:
        image: ghcr.io/paperless-ngx/paperless-ngx:3.4
        container_name: paperless
        restart: unless-stopped
        depends_on:
            - db
            - broker
            - gotenberg
            - tika
        ports:
            - "8000:8000"
        env_file: .env
        environment:
            PAPERLESS_REDIS: redis://broker:6379
            PAPERLESS_DBHOST: db
            PAPERLESS_DBPASS: ${POSTGRES_PASSWORD}
            PAPERLESS_TIKA_ENABLED: 1
            PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
            PAPERLESS_TIKA_ENDPOINT: http://tika:9998
        volumes:
            - ./data:/usr/src/paperless/data
            - ./media:/usr/src/paperless/media
            - ./export:/usr/src/paperless/export
            - ./consume:/usr/src/paperless/consume

• broker is Valkey, a Redis-compatible buffer. The setting is still called PAPERLESS_REDIS.
• db is PostgreSQL 18. Since version 18 the data folder lives at /var/lib/postgresql.
• gotenberg and tika are only needed for Office and email files. For a pure PDF archive, remove both services along with the three PAPERLESS_TIKA_* lines and the depends_on entries.

Start and sign in

sudo docker compose up -d
sudo docker compose ps

Wait until paperless shows the status healthy. Then open http://192.168.1.10:8000 in your browser and sign in with admin and the password from the .env. Change it right away under My Profile.

If the machine has a name on your home network, for example through your router, use that instead of the IP address. Then adjust PAPERLESS_URL and restart with sudo docker compose up -d.

If you prefer Portainer, the Synology guide walks through a Portainer stack. The steps carry over to other home servers.

On the Raspberry Pi

Paperless runs on a Raspberry Pi 4 or 5 with a 64-bit operating system. The images exist for ARM. So that text recognition does not block the Pi, these settings in the .env help:

PAPERLESS_TASK_WORKERS=1
PAPERLESS_THREADS_PER_WORKER=2
PAPERLESS_WEBSERVER_WORKERS=1

Fewer workers mean processing takes longer, but the machine stays responsive. The Paperless documentation lists more options for weak devices. An SSD (Amazon affiliate link) instead of an SD card extends lifetime noticeably, since the database writes a lot.

Backup and update

Back up your documents with the built-in exporter:

sudo docker compose exec paperless document_exporter ../export

Copy the export folder to another device. Automation is covered in Paperless backup and restore.

To update:

sudo docker compose pull
sudo docker compose up -d

The tag 3.4 delivers all patch versions automatically. For a new series, change it in the compose.yaml after reading the release notes. Never update PostgreSQL through the tag alone; follow this post instead.

What to do next

• Workflows: tag and sort new documents automatically.
• Storage paths and folder structure: readable file names on disk.
• Set up a scanner: scan straight into Paperless.
• Paperless-ngx guide: overview of costs, hardware, apps and alternatives.

FAQ

As an Amazon Associate I earn from qualifying purchases.