Letzte Aktualisierung am 18. April 2025

Paperless-ngx ist eine Lösung für die Digitalisierung deines Papierbüros.
Die Installation in diesem Abschnitt ist so angelegt, dass Paperless-ngx in deinem lokalen Netzwerk funktioniert. Später wird die Installation so erweitert, dass sie über das Internet über eine eigene Subdomain erreichbar ist.

Installation

Ich werde die Installation von Paperless-ngx nicht in aller Ausführlichkeit beschreiben sondern die Schritte etwas zusammenfassender darstellen. Das notwendige Rüstzeug findest du in den vorangegangenen Abschnitten, ich setze es hier zu einer Art Template fürs das Vorgehen zusammen. Los geht’s….

Zunächst richtest du dir in der Gitea-GUI ein neues Repository paperless für die Quellen ein. Die URL dazu kannst du dir gleich notieren, um das Repository in deinen Arbeitsbereich von Visual Studio Code einzubinden. In VSC legst du ein neues Verzeichnis build und darin ein weiteres Unterverzeichnis paperless-ngx an. Im Verzeichnis paperless-ngx erstellst du abschließend die beiden Dateien docker-compose.yml und .env. In diese beiden Dateien kopierst du den Inhalt für docker-compose.yml und .env. Speichern nicht vergessen!
Die Verzeichnisstruktur in deinem Arbeitsbereich sollte dann folgendermaßen aussehen.

services: 
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    container_name: plngx-redis
    volumes:
      - ${DATA_ROOT}/paperless/redis/data:/data
    ports:
      - 6379:6379
    networks:
      - nw-dekayone-plngx

  db: 
    image: docker.io/library/mariadb:10
    container_name: plngx-db 
    restart: unless-stopped 
    volumes: 
      - ${DATA_ROOT}/paperless/db:/var/lib/mysql 
    environment: 
      - MYSQL_ROOT_PASSWORD=${DB_ADMIN_PASSWORD}
      - MYSQL_DATABASE=${DB_DATABASE} 
      - MYSQL_USER=${DB_USER} 
      - MYSQL_PASSWORD=${DB_PASSWORD} 
    networks:
      - nw-dekayone-plngx
      
  paperless: 
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: plngx-app 
    restart: unless-stopped
    depends_on: 
      - db 
      - broker
    ports: 
      - 8000:8000 
    volumes: 
      - ${DATA_ROOT}/paperless/data:/usr/src/paperless/data
      - ${DATA_ROOT}/paperless/media:/usr/src/paperless/media
      - ${DATA_ROOT}/paperless/export:/usr/src/paperless/export
      - ${DATA_ROOT}/paperless/consume:/usr/src/paperless/consume
    environment: 
      - PAPERLESS_REDIS=redis://broker:6379
      - PAPERLESS_DBENGINE=mariadb
      - PAPERLESS_DBHOST=db
      - PAPERLESS_DBUSER=${DB_USER}
      - PAPERLESS_DBPASS=${DB_PASSWORD} 
      - PAPERLESS_DBPORT=3306
      - PAPERLESS_CONSUMER_POLLING=30    
    networks:
      - nw-dekayone-plngx
    labels:
      - com.centurylinklabs.watchtower.enable=true
        
networks:
  nw-dekayone-plngx:
    external: true

# general timezone
TIMEZONE=Europe/Berlin

# mountpoint of persistent data storage on NAS
DATA_ROOT=dein_datenablage_share

# MYSQL settings
DB_ADMIN_PASSWORD=supersecretadminpassword
DB_PASSWORD=secretuserpassword
DB_DATABASE=paperless
DB_USER=paperless

# 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=1002
USERMAP_GID=1000

# 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&suite=buster
# for available languages.

PAPERLESS_OCR_LANGUAGES=deu

###############################################################################
# Paperless-specific settings
###############################################################################

# All settings defined in the paperless.conf.example can be used here. The
# Docker setup does not use the configuration file.
# 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.example.com
# Adjust this key if you plan to make paperless available publicly. It should
# be a very long sequence of random characters. You don't need to remember it.
PAPERLESS_SECRET_KEY=deinsuperlangersupergeheimertokenauszufaelligenzeichen
# Use this variable to set a timezone for the Paperless Docker containers. If not specified, 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

# Set if accessing paperless via a domain subpath e.g. https://domain.com/PATHPREFIX and using a reverse-proxy like traefik or nginx

#PAPERLESS_FORCE_SCRIPT_NAME=/PATHPREFIX
#PAPERLESS_STATIC_URL=/PATHPREFIX/static/ # trailing slash required
PAPERLESS_CONSUMER_POLLING=30

PAPERLESS_CONSUMER_ASN_BARCODE_PREFIX=ASN
PAPERLESS_CONSUMER_ENABLE_ASN_BARCODE=true
PAPERLESS_CONSUMER_ENABLE_BARCODES=true
PAPERLESS_CONSUMER_BARCODE_SCANNER=ZXING

Noch schnell in der Ansicht „Quellcodeverwaltung“ in VSC die Änderungen inkl. Nachricht per „Commit und Push“ ins Repository übertragen. Und dann bist du hier bereits fertig.

Weiter geht’s im Portainer…

Bevor du den Stack für Paperless-ngx erstellt, definierst du noch kurz das notwendige neue Netzwerk nw-dekayone-plngx (bzw. den Namen, den du ggf. in docker-compose.yml geändert hast) ohne spezielle Parameter.

Dann kann es auch schon weitergehen mit dem Anlegen des Stacks über die Liste deiner bereits angelegten Stacks. Dem neuen Stack gibst du einen Namen wie z.B. paperless-ngx und wählst die Option „Repository“. Für dein Repository aktivierst du die Option „Authentication“ und gibst die Credentials für deinen Gitea-Nutzer ein. Als „Repository URL“ verwendest du die oben gemerkte URL zum neuen Repository paperless-ngx, das Feld „Repository reference“ bleibt wie es ist und im Feld „Compose path“ trägst du build/paperless-ngx/docker-compose.yml ein.

Nun folgt eine Besonderheit bei der Installation aus einem Repository: wenn du deine Umgebungsvariablen wie hier geschehen in einer Datei .env im selben Verzeichnis wie die docker-compose.yml anlegst, musst du keinerlei Eintragungen bei den Umgebungsvariablen für deinen Stack vornehmen. Portainer nutzt automatisch die vorhandene Datei .env.

Den fertig definierten Stack startest du über die Schaltfläche „Deploy the stack“ und wenn nach einiger Wartezeit (Portainer lädt u.a. die notwendigen Images aus dem Internet) alles funktioniert hat, siehst du deinen neuen Stack paperless-ngx. Wenn du den Stacknamen anklickst, solltest du die Stackdetails ähnlich wie in der folgenden Abbildung sehen.

Nutzung

Die GUI von Paperless ngx ist nach obiger Installation über die IP-Adresse deines Pi und den Port 8000 erreichbar. Nach Eingabe der Adresse landest du auf der Anmeldeseite.

Für die weitere Nutzung empfehle ich dir zunächst beide Artikel in der c’t (siehe Quellen und Links) und nicht zuletzt gilt in diesem Fall: einfach ausprobieren und die Online-Quellen für Paperless-ngx durchstöbern.

Dokumente löschen

Ich hatte nach der initialen Installation Probleme beim Löschen von Dokumenten, was immer mit einer Fehlermeldung Error deleting document: (1406, "Data too long for column 'transaction_id' at row 1") abgebrochen ist.

Nach Recherche im Interner habe ich hier die schnelle Lösung gefunden:
Du stellst eine SSH-Verbindung mit deinem Pi her und listet mit docker ps die laufenden Docker-Container auf. Wenn du keine Änderung am obigen docker-compose.yml vorgenommen hast, findest du in der Liste einen Container mit Namen plngx-app.

In der Konsole führst du nun nachfolgendes Kommando aus, wobei du plngx-app ggf. durch den Container-Namen ersetzt, den du verwendest.

sudo docker exec -it plngx-app python3 manage.py convert_mariadb_uuid

Nach erfolgreicher Ausführung siehst du die Ausgabe Successfully converted documents.Document transaction_id field to UUID type. in der Konsole.

Jetzt kannst du in der Paperless-GUI ohne Fehlermeldung löschen.

Einrichten Netzwerk-Share für consume-Ordner

Ich habe zusammen mit meinem LaserJet MFP M479dw eine Scan-Station eingerichtet, mit der ich meine Papierkorrespondenz einlese und im consume-Ordner von Paperless-ngx ablege. Paperless-ngx ist über die obige Konfiguration bereits so eingerichtet, dass es in regelmäßigen Abständen den consume-Ordner auf neue Dokument prüft und diese automatisch importiert.

Dazu habe ich zunächst auf meinem QNAP-NAS über die Systemsteuerung eine neue Freigabe über die den Punkt „Freigabeordner“ eingerichtet und mit entsprechenden Zugriffsrechten meiner NAS-Nutzer vergeben.

Neben der Vergabe der Zugangsrechte ist es wichtig den Pfad manuell auszuwählen, den du im docker-compose.yml für den consume-Ordner verwendet hast

Einrichten HP LaserJet als Scanstation

Anschließend habe ich über den HP-Druckerassitenten unter Windows des LaserJets ein neues Netzwerk-Scan-Ziel in die zuvor angelegte Freigabe eingerichtet. Bei dieser Einrichtung ist zu beachten, dass

• der Druckerassistent von HP u.U. Administrator-Rechte unter Windows anfordert
• ein Präfix für den Dateinamen zwingend angegeben werden muss; ich verwenden „pdf“
• ein Nutzer angegeben werden muss, der für die zuvor eingerichtete Freigabe Schreibrechte besitzt.

Im Druckerassistenten wählst du im Bereich „Scannen“ die Option „An Netzwerkordnerassistenten scannen“ und gelangst damit in die Liste der angelegten Netzwerkordnerprofile.

Über die Schaltfläche neu wirst du durch die Einrichtung eines Netzwerkordners geführt, die mit der Eingabe der Netzfreigabe beginnt. Hier trägst du deine zuvor eingerichtete Freigabe auf dem NAS ein. Dabei die beiden führenden „\“ nicht vergessen!

Nach einem Klick auf „Weiter“ musst du die Anmeldeinfornationen für einen Nutzer des NAS angeben, den du bei der Einrichtung der Freigabe mit Schreibrechten versehen hast. Wenn du keinen zentralen Anmeldeserver (LDAP o.ä.) verwendest, werden die Informationen der NAS-Benutzer auf deinem NAS gespeichert. Daher musst du in diesem Fall den Benutzername in der Form <deinnas>\<nasbenutzer> zusammen mit dem passenden Kennwort eingeben.

Im nächsten Schritt geht es an die Konfiguration der erzeugten Datei. Die dargestellte Konfiguration zeigt die Einrichtung eines PDF-Dokuments in Farbe, dessen Dateiname mit dem Präfix „pdf“ versehen wird. Der Druckerassistent lässt an dieser Stelle keinen leeren Präfix zu, du musst ihn zwangsweise angeben.

Ein Klick auf „Weiter“ bringt dich zur Zusammenfassung der Einrichtung, die du nun „Speichern“ bzw. „Speichern und testen“ kannst. Mit Auswahl von „Speichern und testen“ wird u.a. die Verbindung zum angegebenen Netzwerkpfad mit den konfigurierten Anmeldeinformationen getestet.

Ist die Einrichtung fehlerfrei abgeschlossen, landest du wieder in der Liste der Netzwerkordnerprofile und siehst dort deine eingerichtete Verbindung unter dem Namen „Paperless“.

Wenn du nun am HP LaserJet unter dem Punkt „Scannen“ die Option „Netzwerkordner“ auswählst, siehst in der Liste das eingerichtete Profil „Paperless“. Damit kannst du nun deinen Scan durchführen, der nach Abschluss automatisch als PDF in der eingerichteten NAS-Freigabe und damit im consume-Ordner von Paperless-ngx abgelegt wird. Von dort wird Paperless-ngx die PDF-Datei automatisch einlesen.

Neben der Nutzung beim Scannen von Dokumenten am LaserJet kann die NAS-Freigabe natürlich auch an einem Rechner verwendet werden, um darin alle Art von Dokumenten wie z.B. Mail-Anhänge abzulegen zum automatischen Import durch Paperless-ngx.

Weiteres

Ich nutze die NAS-Freigabe ebenfalls auf meinem iPhone und iPad über die in iOS verfügbare Dateien-App. Dazu muss die Qfile Pro-App von QNAP auf dem iPhone bzw. iPad installiert sein. Qfile Pro integriert sich als Speicherort in die Dateien-App auf dem iPhone bzw. iPad, sodass darüber die Freigabe angesprochen werden kann. Ich diese Möglichkeit nur zu Hause in meinem lokalen Netzwerk, da ich keinen Fernzugriff auf mein QNAP-NAS eingerichtet habe.

Darüber hinaus gibt es für Mobilgeräte verschiedene Apps für die Nutzung von Paperless, die du in den App-Stores findest. Ich selber nutze auf meinem iPhone und iPad die App Swift Paperless von Paul Gessinger.