Übersicht

Paperless ist eine Open-Source-Dokumentenverwaltung, mit der ihr Rechnungen, Verträge, Briefe und viele weitere Dokumente digital archivieren könnt. Statt Ordner und Papierstapel zu durchsuchen, übernimmt Paperless die Texterkennung per OCR und macht eure Dokumente vollständig durchsuchbar.

In diesem Artikel installieren wir Paperless mit Docker und PostgreSQL, richten die Grundkonfiguration ein und schauen uns anschließend die wichtigsten Funktionen an. Außerdem werfen wir einen Blick auf Automatisierungen, Dokumentenimporte und die verschiedenen Möglichkeiten, Ordnung in eure Unterlagen zu bringen.

Das Video zum Artikel findet Ihr hier: https://youtu.be/bVmtotDi6GU

Installation

Docker

Als Erstes installieren wir Docker, falls das noch nicht geschehen ist, da wir Paperless mit Docker betreiben möchten. Das können wir ganz einfach mit dem offiziellen Convenience Script von Docker machen.

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

Verzeichnis

Bevor wir fortfahren, müssen wir uns ein geeignetes Verzeichnis erstellen, wo wir Paperless später laufen lassen wollen. Ich habe meine Docker-Compose Stacks immer gerne unter /opt, darunter erstelle ich einen neuen Ordner für Paperless mit:

sudo mkdir /opt/paperless
cd /opt/paperless

Docker Compose

Als Nächstes benötigen wir natürlich das docker-compose.yml File.

Hier gibt es verschiedene Varianten. Ich habe mich für Paperless mit PostgreSQL als Datenbank entschieden. Zusätzlich habe ich ein paar Anpassungen vorgenommen, bspw. das Hinterlegen der Postgres-Variablen in der .env. Bzw. wird im Default der Name docker-compose.env verwendet, ich habe das File aber .env benannt.

Am Ende sieht das Ganze bei mir so aus:

services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    restart: unless-stopped
    volumes:
      - ./redisdata:/data
    networks:
      - default
  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    networks:
      - default
  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
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: .env
    environment:
      - PAPERLESS_REDIS=redis://broker:6379
      - PAPERLESS_DBHOST=db
      - PAPERLESS_DBENGINE=postgresql
      - PAPERLESS_DBNAME=${POSTGRES_DB}
      - PAPERLESS_DBUSER=${POSTGRES_USER}
      - PAPERLESS_DBPASS=${POSTGRES_PASSWORD}
    networks:
      - default

networks:
  default:
    name: paperless-internal

Environment File

Für Paperless benötigen wir ein Environment-File. Ein Example-File gibt es ebenfalls im Paperless-Repo.

Dort habe ich in meinem Fall noch die Postgres-Variablen hinzugefügt. Fertig sieht das dann bspw. so aus:

###############################################################################
# Postgresql settings                                                      #
###############################################################################

POSTGRES_USER=paperless-user
#Generate with openssl rand -hex 24
POSTGRES_PASSWORD=
POSTGRES_DB=paperless-db

###############################################################################
# Paperless-ngx settings                                                      #
###############################################################################

# See http://docs.paperless-ngx.com/configuration/ for all available options.

# The UID and GID of the user used to run paperless in the container. Set this
# to your UID and GID on the host so that you have write access to the
# consumption directory.
#USERMAP_UID=1000
#USERMAP_GID=1000

# See the documentation linked above for all options. A few commonly adjusted settings
# are provided below.

# This is required if you will be exposing Paperless-ngx on a public domain
# (if doing so please consider security measures such as reverse proxy)
PAPERLESS_URL=https://paperless.eure-domain.de

# Required. A unique secret key for session tokens and signing.
# Generate with: python3 -c "import secrets; print(secrets.token_urlsafe(64))"
PAPERLESS_SECRET_KEY=

# Use this variable to set a timezone for the Paperless Docker containers. Defaults to UTC.
PAPERLESS_TIME_ZONE=Europe/Berlin

# The default language to use for OCR. Set this to the language most of your
# documents are written in.
PAPERLESS_OCR_LANGUAGE=deu

# Additional languages to install for text recognition, separated by a whitespace.
# Note that this is different from PAPERLESS_OCR_LANGUAGE (default=eng), which defines
# the language used for OCR.
# The container installs English, German, Italian, Spanish and French by default.
# See https://packages.debian.org/search?keywords=tesseract-ocr-&searchon=names
# for available languages.
PAPERLESS_OCR_LANGUAGES=deu

Das war dann auch schon alles an Files, die wir benötigen.

Start

Nachdem wir nun also die docker-compose.yaml in unserem Paperless-Verzeichnis haben und unser Environment-File angepasst haben, können wir den Container starten.

sudo docker compose up -d

Reverse Proxy

Um Paperless via der angegebenen Domain erreichen zu können, nutze ich einen Reverse-Proxy. In dem aktuellen Lab basiert das auf dem Nginx Proxy Manager. Eine weitere und noch schlankere Möglichkeit ist die Umsetzung mit Caddy.

Um jetzt Paperless erreichen zu können, lege ich einen neuen Host im Nginx Proxy Manager an, der auf den Server Paperless-Server zeigt.

Wenn ihr Reverse-Proxy & Paperless auf einem Server habt, könnt ihr auch mit Docker-Netzwerken arbeiten.

Erste Schritte

Nach kurzem Initialisieren ist Paperless über die gewählte Domain erreichbar. Dort angekommen, erstellen wir als Erstes einen Admin-Account.\n

Anschließend sind wir auch schon auf dem Paperless-Dashboard.

Konfiguration

Fangen wir also einmal mit der Seitenleiste an, um Paperless zu verstehen. Wir haben unter Verwaltung einige Konfigurationsmöglichkeiten.

Attribute

Unter Attribute erstellen wir quasi alles, was für die Ordnung unserer Dokumente wichtig ist.

Paperless möchte uns möglichst viel Arbeit abnehmen, daher haben wir bei allen Attributen, die wir anlegen, immer die Möglichkeit, die Zuweisung dessen an etwas zu koppeln. Bspw. ein Wort, das im Dokument vorkommt, womit klar ist, dass es von Firma XY ist. Wir haben auch die Möglichkeit, Paperless automatisch lernen zu lassen, wann das Attribut eingesetzt werden soll.

Tags

Mit Tags haben wir die Möglichkeit, unsere Dokumente zu markieren. Wir können auch einen Tag als "Inbox" erstellen, damit wir wissen, welche Dokumente wir ggf. noch überprüfen müssen.

Tipp: In den Einstellungen kann man den Inbox-Tag so einstellen, dass er beim Speichern automatisch verschwindet.

Korrespondenten

Das sind quasi unsere Vertragspartner bzw. die Firmen/Personen, von denen die Dokumente kommen.

Dokumenttyp

Mit den Dokumenttypen können wir Dokumente klassifizieren wie bspw. Rechnungen, Verträge etc.

Speicherpfade

Geben uns die Möglichkeit, eine Speicherstruktur auf dem System zu bauen. Per default legt Paperless alles in einen Ordner, das stört prinzipiell nicht, solange man via Paperless auf die Dokumente zugreift.

Wenn das Verzeichnis auch sortiert sein soll, können wir Speicherpfade erstellen und dort unsere Dokumente einsortieren.

Auch hier können wir viel automatisieren und mit Variablen arbeiten.

Infos zu den Variablen gibt es hier.

Zusatzfelder

Wie der Name sagt, können wir hier weitere Felder erstellen, die wir dann benutzen können.

Arbeitsabläufe

In diesem Reiter können wir Automatisierungen erstellen, mit denen Paperless dann anfängt, bspw. Dokumente zu verarbeiten.

E-Mail

In diesem Reiter haben wir die Möglichkeit, ein Postfach zu hinterlegen, aus welchem Paperless Dokumente importieren kann. So könnten wir beispielsweise Rechnungen, die per Mail kamen, einfach an Paperless weiterleiten.

Consume Ordner

Eine weitere Möglichkeit, Dokumente zu Paperless zu bekommen, ist der Consume Ordner. Den haben wir ja in der docker-compose.yml festgelegt und ist aktuell als Bind-Mount in dem Verzeichnis. Wir können hier aber bspw. auch einen NFS-Share nehmen, an den bspw. auch unser Drucker Dokumente scannen und ablegen kann. Dann landen die ebenfalls automatisch in Paperless.

Dokumente

Das Herzstück von Paperless, unsere Dokumente geordnet, sortiert und komplett durchsuchbar.

Je nachdem wie die Attribute konfiguriert sind, fängt Paperless hier vollautomatisch an, die Dokumente mit den passenden Werten zu bestücken. Alle Korrespondenten unten bspw. wurden von Paperless korrekt erkannt und zugewiesen.

Volltextsuche

Nachdem unsere Dokumente verarbeitet wurden, hat das lange Suchen nach dem einen Vertrag ein Ende! Wir können jetzt nach allem Möglichen suchen. Beispielsweise suche ich hier eine Vertragsnummer von einem Mobilfunkvertrag. Als Ergebnis bekomme ich alle Dokumente, wo diese Nummer auftaucht. In diesem Fall auf dem Kontoauszug und im Vertrag.

Attribute anpassen

Natürlich können wir Attribute auch händisch vergeben und anpassen. Anhand des Inbox-Tags erkennen wir super, welche Dokumente neu sind. Hier können wir alles anpassen.

Benutzer & Gruppen

Natürlich können wir auch mehrere Benutzer anlegen und so bspw. die Instanz mit der ganzen Familie nutzen. Paperless hat ein sehr granulares Rechte-System.

OIDC / SSO

Natürlich haben wir auch die Möglichkeit Paperless and einen Identity Provider anzubinden. Mehr infos dazu gibt es in der Offiziellen Dokumentation.

Fazit

Paperless gehört für mich inzwischen zu den sinnvollsten Anwendungen im Homelab. Einmal eingerichtet, spart es im Alltag jede Menge Zeit und sorgt dafür, dass Rechnungen, Verträge oder andere wichtige Dokumente nicht mehr irgendwo auf der Festplatte oder in einem Ordner verschwinden. Durch OCR, Automatisierungen und die vielen Importmöglichkeiten wächst das System fast von alleine mit und nimmt einem einen Großteil der Arbeit ab. Wer seine Dokumente endlich zentral und sauber verwalten möchte, sollte sich Paperless definitiv einmal anschauen.