In diesem Beitrag erkläre ich die Installation und Einrichtung von der Dokumentenverwaltung-Software Paperless-ngx mithilfe von Docker unter Debian.

In der heutigen digitalen Welt wird die Verwaltung und Archivierung von Dokumenten immer wichtiger. Hier kommt Paperless-ngx ins Spiel, eine leistungsstarke Open-Source-Software, die entwickelt wurde, um die Aufbewahrung und Suche nach Dokumenten zu vereinfachen. Sie ist der Nachfolger von "Paperless" und "Paperless-ng", welche beide nicht mehr weiterentwickelt werden. Paperless-ngx wird aktiv weiterentwickelt und biete die Möglichkeit Dokumente einfach zu digitalisieren, zu organisieren und leicht zugänglich zu machen. Es bietet eine benutzerfreundliche Weboberfläche und leistungsstarke Funktionen zur Verwaltung von Dokumenten aller Art. Egal, ob du Rechnungen, Verträge, Notizen oder andere wichtige Papiere speichern möchtest.

Docker installieren

Die einfachste Installation für Paperless-ngx erfolgt über Docker. Falls noch nicht geschehen, musst du also zunächst Docker und Docker Compose installieren.

Verbinde dich per PuTTY auf deinen Server. Suche zunächst nach Updates, um den Server auf den aktuellsten Stand zu bringen:

apt update

Installiere die erforderlichen Abhängigkeiten, die von Docker benötigt werden:

apt install apt-transport-https ca-certificates curl software-properties-common

Füge den offiziellen Docker-GPG-Schlüssel hinzu, um die Paketsignaturen zu überprüfen:

curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Füge die Docker-Repository hinzu:

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

Aktualisiere erneut dein Paketverzeichnis, um die Informationen aus dem Docker-Repository zu erhalten:

apt update

Installiere Docker nun mit dem folgenden Befehl:

apt install docker-ce docker-ce-cli containerd.io

Starte den Docker-Dienst und aktiviere ihn, damit er bei jedem Systemstart gestartet wird:

systemctl start docker

systemctl enable docker

Führe den folgenden Befehl aus, um Docker Compose herunterzuladen und in das Verzeichnis /usr/local/bin zu verschieben. Dieser Befehl installiert die neueste Version von Docker Compose:

curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Gib ausführbare Berechtigungen für Docker Compose:

chmod +x /usr/local/bin/docker-compose

Docker wurde nun installiert. Jetzt kann Paperless-ngx installiert werden.

Paperless-ngx installieren

Die Installation von Paperless-ngx kann aus Sicherheitsgründen nur als nicht-Root Benutzer erfolgen. Falls noch kein anderer Benutzer existiert, erstellst du einen:

adduser paperless

Befolge die weiteren Schritte, um den Benutzer anzulegen.

Vergib dem neuen Benutzer die Berechtigung, Docker zu verwenden:

usermod -aG docker paperless

Wechsel jetzt die Sitzung in den neuen Benutzer:

su paperless

Verwende für die Installation das Docker-Script von GitHub:

bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Nun wird die Software in einigen Schritten konfiguriert. Den Anfang macht die Angabe der URL, unter der Paperless-ngx später erreichbar sein wird. Sofern auch ein SSL-Zertifikat für deine Domain vorhanden ist, solltest du hier die Seite mit https angeben.

1. Application configuration
============================

The URL paperless will be available at. This is required if the
installation will be accessible via the web, otherwise can be left blank.
Example: https://paperless.example.com

URL []: http://paperless.domain.tld

Als nächstes gibst du den Port der Software an. Ich belasse es beim Standard 8000. Später kannst du in der Virtual Host Datei von Apache2 auch hinterlegen, dass der Port gar nicht eingegeben werden muss.

The port on which the paperless webserver will listen for incoming
connections.

Port [8000]: 8000

Gib im nächsten Schritt die Zeitzone für Deutschland an.

Paperless requires you to configure the current time zone correctly.
Otherwise, the dates of your documents may appear off by one day,
depending on where you are on earth.
Example: Europe/Berlin
See here for a list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Current time zone [Europe/Berlin]: Europe/Berlin

Nun musst du einen Datenbank-Typ auswählen. Ich entscheide mich für den Standard, PostgreSQL. Für Systeme mit wenig Hardware-Ressourcen sollte SQLite verwendet werden.

Database backend: PostgreSQL, MariaDB, and SQLite are available. Use PostgreSQL
if unsure. If you're running on a low-power device such as Raspberry
Pi, use SQLite to save resources.

Database backend (postgres sqlite mariadb) [postgres]: postgres

Möchtest du, dass Paperless-ngx auch Office-Dokumente analysieren können soll, aktiviert du Tika. Dieses Feature benötigt jedoch zusätzliche System-Ressourcen.

Paperless is able to use Apache Tika to support Office documents such as
Word, Excel, Powerpoint, and Libreoffice equivalents. This feature
requires more resources due to the required services.

Enable Apache Tika? (yes no) [no]: yes

Für die OCR-Texterkennung gibst du jetzt an, in welcher Sprache sich die meisten deiner Dokumente befinden. Das sollte Deutsch sein.

Specify the default language that most of your documents are written in.
Use ISO 639-2, (T) variant language codes:
https://www.loc.gov/standards/iso639-2/php/code_list.php
Common values: eng (English) deu (German) nld (Dutch) fra (French)
This can be a combination of multiple languages such as deu+eng

OCR language [eng]: deu

In den nächsten beiden Schritten bestätigst du jeweils die User-ID und Group-ID, welche bereits in der eckigen Klammer steht. Das Setup wird die Berechtigungen entsprechend für den aktuellen Benutzer setzen.

Im nächsten Schritt legst du fest, wo die Daten von Paperless-ngx liegen sollen. Das sollte dort sein, von wo aus die Website laut Virtual Host Datei direkt erreichbar ist.

The target folder is used to store the configuration files of
paperless. You can move this folder around after installing paperless.
You will need this folder whenever you want to start, stop, update or
maintain your paperless instance.

Target folder [/home/paperless-ngx]: /home/paperless/www

Die gleiche Syntax wird jetzt noch für die Verzeichnisse media, data und database festgelegt.

The consume folder is where paperless will search for new documents.
Point this to a folder where your scanner is able to put your scanned
documents.

CAUTION: You must specify an absolute path starting with / or a relative
path starting with ./ here. Examples:
  /mnt/consume
  ./consume

Consume folder [/home/paperless/www/consume]: /home/paperless/www/consume

Im letzten Schritt legst du die Anmeldedaten für dein Administrator-Konto fest. Eine E-Mail-Adresse muss hinterlegt werden, wird aber für nichts verwendet.

3. Login credentials
====================

Specify initial login credentials. You can change these later.
A mail address is required, however it is not used in paperless. You don't
need to provide an actual mail address.

Paperless username [paperless]: paperless
Paperless password:
Paperless password (again):
Email [paperless@localhost]: mail@example.com

Dir wird die Konfiguration zusammengefasst. Drücke Enter, um die Installation von Paperless-ngx zu starten.

Nach der Installation kannst du Paperless-ngx über deinen Browser aufrufen:

http://paperless.domain.tld:8000

Paperless-ngx konfigurieren

Bevor du aber deine ersten Dokumente in das Dokumentenmanagementsystem hochlädst, solltest du die Docker Compose Konfiguration anpassen. Paperless-ngx bietet eine breite Palette von Anpassungsmöglichkeiten. Je nachdem, wie du Paperless einsetzen möchtest, solltest du Einstellungen an unterschiedlichen Stellen vornehmen. Öffne dazu die docker-compose.yml Datei, welche sich direkt im Installationsverzeichnis von Paperless-ngx befindet.

Ziemlich weit unten im Bereich webserver und dann environment findest du 6 Zeilen mit Daten der Datenbank. Direkt darunter können beliebige Konfigurationen hinzugefügt werden. Alle Möglichkeiten hierzu findest du unter docs.paperless-ngx.com/configuration/.

Zunächst sollte ein Session-Token festgelegt werden. Verwenden einfach eine beliebige Folge von Zeichen. Je mehr, desto besser. Du musst dir diese Zeichenfolge nicht merken.

      PAPERLESS_SECRET_KEY: HierZufälligeZeichenVerwenden

Bei manchen Geräten wird die Sitzung beim Beenden vom Browser automatisch abgemeldet und du musst dich erneut in Paperless-ngx anmelden. Um die Sitzung beizubehalten, kannst du ebenfalls folgende Zeile hinzufügen:

      PAPERLESS_ACCOUNT_SESSION_REMEMBER: "True"

Damit die Texterkennung der hochgeladenen Dokumente ordnungsgemäß funktioniert, musst du hier unbedingt die Sprache für OCR festlegen. Empfehlenswert ist Deutsch und Englisch:

      PAPERLESS_OCR_LANGUAGE: deu+eng

Digital signierte PDF-Dokumente, z.B. von Banken, können Probleme mit der OCR-Erkennung machen. Daher sollte mit folgender Konfiguration festgelegt werden, dass digitale Signaturen in den hochgeladenen Dokumenten ungültig gemacht werden. Das bedeutet, dass Paperless-ngx bewusst die digitalen Signaturen entfernt oder unbrauchbar macht, um den Inhalt problemlos auslesen zu können.

      PAPERLESS_OCR_USER_ARGS: '{"invalidate_digital_signatures": true}'

Standardmäßig werden die hochgeladenen Dokumente unter media/documents/archive/ gespeichert. Wenn du hier aber eine gewisse Ordnung bewahren möchtest, kannst du die Art der Speicherung anpassen. Beispielsweise so, dass die Dokumente in einem Ordner des jeweiligen Jahres abgelegt werden und sich der Name der Datei ändert zu "EindeutigeIDVonPaperless_NameDesDokuments":

      PAPERLESS_FILENAME_FORMAT: '{{ created_year }}/{{ doc_pk }}_{{ title }}'

Weitere mögliche Variablen findest du hier in der Doku: docs.paperless-ngx.com/advanced_usage/#file-name-handling

Weitere Konfigurationsmöglichkeiten findest du in der Dokumentation: docs.paperless-ngx.com/configuration/

Kurze Einführung in Paperless-ngx

In Paperless-ngx angemeldet empfehle ich als erstes die Einstellungen durchzugehen und nach eigenem Empfinden einzustellen.

Unter Konfiguration OCR-Einstellungen empfehle ich noch, Ausgabetyp zu pdfa umzustellen, in das Feld Sprache den Wert deu+eng einzutragen und die Schräglagenkorrektur zu aktivieren. Das wurde zwar teilweise bereits in der docker-compose.yml vorher eingestellt, aber sicher ist sicher. Außerdem hat diese Konfiguration Vorrang vor den Einstellungen in der Datei docker-compose.yml.

Außerdem sollten unter Verwalten Tags eigene Tags erstellt werden, damit gescannten Dokumente und Briefe später einfacher zugeordnet und gefunden werden können. Die Tour erklärt dir ebenfalls die Grundfunktionen.

Unter Verwalten lassen sich auch Dokumenttypen erstellen. Ich persönlich nutze als Typ Brief, Dokument und Sonstiges.

Über die Startseite kannst du einen Scan auswählen und hochladen. Anschließend findest du das Dokument unter Dokumente. Über das Stift-Symbol kannst du Details und weiterer Optionen dieses Dokuments ändern. Ein Titel, das Datum und die entsprechenden Tags sollten als minimum gesetzt werden.

Die Software erkennt anhand der OCR-Texterkennung das Datum der Dokumente in der Regel automatisch, oder es wird das Erstelldatum verwendet, und trägt dieses Datum entsprechend ein, außerdem lernt eine KI die verschiedenen Arten der Dokumente und vergibt dann automatisch nach dem Hochladen den passenden Tag, wie beispielsweise Versicherung, Gesundheit oder Steuerunterlagen. Diesen automatische Zuweisungsalgorithmus kannst du unter Tags im entsprechenden Tag auch deaktivieren oder festlegen, dass der Tag bei bestimmten vorkommenden Worten automatisch gesetzt wird.

Virtual Host Datei für Aufruf ohne Port

Im folgenden habe ich einmal eine Virtual Host Datei für Apache2 zusammengestellt, die dafür sorgt, dass der Dienst ohne Port erreichbar ist.

<VirtualHost *:443>
	ServerAdmin webmaster@domain.tld
	ServerName paperless.domain.tld

	ProxyPass / http://127.0.0.1:8000/
	ProxyPassReverse / http://127.0.0.1:8000/

	ErrorLog ${APACHE_LOG_DIR}/error.log
	CustomLog ${APACHE_LOG_DIR}/access.log combined

	SSLEngine On
	SSLCertificateFile /Pfad/zur/cert.pem
	SSLCertificateKeyFile /Pfad/zur/private.pem
</VirtualHost>

Backup von Paperless-ngx erstellen

Wie bei allen Diensten solltest du dafür sorgen, dass die Daten regelmäßig für den Fall der Fälle gesichert werden. Sollte es zu einem Datenverlust kommen oder du versehentlich etwas löschen, kannst du so deine Dokumente wiederherstellen.

In folgendem findest du ein kleines Bash-Script, welches Docker beendet, das Verzeichnis von Paperless-ngx sichert und Docker wieder startet. Du solltest hierfür noch mit einem Cronjob für eine Automatisierung sorgen und die Datei extern verschieben lassen. Auch solltest du über eine Verschlüsselung des Backups nachdenken. Die Pfade musst du entsprechend anpassen.

#!/bin/bash

docker-compose down
tar -czf /home/paperless/paperless_$(date +%Y-%m-%d).tar.gz -C /home/paperless www
docker-compose up -d

Paperless-ngx aktualisieren

Paperless-ngx erhält regelmäßig Aktualisierungen mit Fehlerbehebungen, weiteren Features und Behebungen von Sicherheitslücken. Daher sollte die Software regelmäßig aktualisiert werden.
Fahre den Container zunächst herunter. Begib dich dazu in das Verzeichnis von Paperless-ngx und verwende diesen Befehl:

docker-compose down

Lade dir jetzt per pull das neueste Docker-Image von Paperless-ngx herunter:

docker-compose pull

Anschließend kann der Container wieder gestartet werden. Er fährt jetzt mit der neuesten Version hoch.

docker-compose up -d

Paperless-ngx Docker-Container komplett löschen

Möchtest du Paperless-ngx samt Daten und alle verknüpften Docker-Komponenten wieder löschen, gehst du wie folgt vor.

Beende zunächst alle zusammenhängenden Container von Paperless-ngx:

docker stop paperless-webserver-1 paperless-db-1 paperless-gotenberg-1 paperless-tika-1

Nachdem die Container gestoppt sind, kannst du sie mit folgendem Befehl entfernen:

docker rm paperless-webserver-1 paperless-db-1 paperless-gotenberg-1 paperless-tika-1

Wenn du auch die zugehörigen Docker-Images entfernen möchtest, kannst du folgende beiden Befehle noch absetzen:

docker rmi ghcr.io/paperless-ngx/paperless-ngx:latest

docker rmi mariadb:10

docker rmi gotenberg/gotenberg:7.8

docker rmi ghcr.io/paperless-ngx/tika:latest

Nun kannst du Docker noch bereinigen, indem du alle nicht verwendeten Container und Images löschst. Container und Images von anderen Anwendungen als Paperless-ngx, die noch unter Docker laufen, sind davon nicht betroffen.

docker system prune -f