Thomas/Homelab--Bratonein-Kontrollzentrum--Tutorial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
65fc41a456d5442ee4e7215258c99fbcd80292ba
Homelab--Bratonein-Kontroll…/Kapitel 16/Premium Rohtext.md

30 KiB
Raw Blame History

Premium – Paperless-ngx: Automatisierung, Integration & erweiterte OCR-Verarbeitung

Paperless-ngx ist im UCC nicht nur eine Dokumentenablage, sondern die Grundlage für ein vollautomatisiertes Archivsystem.
Im Free-Kapitel wurde die Basiskonfiguration gelegt – ein zentraler Container mit OCR, Benutzerverwaltung und HTTPS-Zugang.
Dieser Premium-Teil erweitert das Setup zu einer intelligenten Dokumentenpipeline, die Dateien automatisch erkennt, verschlagwortet, verteilt und mit anderen Diensten im UCC verknüpft.

Ziel ist ein selbstlernendes Dokumentenarchiv, das ohne manuelle Eingriffe arbeitet:
E-Mails und Cloud-Uploads werden automatisch übernommen, OCR-Ergebnisse mit n8n weiterverarbeitet und fertige Dokumente z. B. in Nextcloud synchronisiert.
Zusätzlich lernst du, wie du die OCR-Engine optimierst und Paperless-ngx so konfigurierst, dass mehrsprachige Dokumente fehlerfrei erkannt werden.

👉 Screenshot geeignet: Architekturdiagramm mit Datenfluss zwischen Paperless-ngx, n8n und Nextcloud

Note

Dieses Kapitel setzt eine vollständig funktionierende Free-Installation voraus.
Stelle sicher, dass dein Paperless-Container läuft, über HTTPS erreichbar ist und Dokumente manuell verarbeitet werden können.

Am Ende dieses Kapitels steht ein vollständig automatisiertes Dokumentensystem, das alle relevanten Quellen selbst erfasst,
automatisch indiziert und nahtlos mit anderen Komponenten des UCC zusammenarbeitet – ohne Cloud-Dienste oder externe APIs.

Erweiterte OCR- und Spracherkennung

Die standardmäßige OCR-Erkennung in Paperless-ngx ist auf eine Sprache begrenzt und verwendet Basisparameter.
Für produktive Umgebungen lohnt sich eine erweiterte Konfiguration, um mehrsprachige Dokumente und bessere Textergebnisse zu erzielen.

👉 Screenshot geeignet: Ausschnitt aus der Weboberfläche mit aktivem OCR-Status und Fortschrittsanzeige

OCR-Sprachen nachinstallieren

Die Engine Tesseract unterstützt mehrere Sprachen gleichzeitig.
Um zusätzliche Sprachpakete zu aktivieren, installiere sie direkt im Container:

apt install -y tesseract-ocr-deu tesseract-ocr-eng tesseract-ocr-fra

Damit erkennt Paperless-ngx deutsche, englische und französische Dokumente parallel.

Note

Du kannst beliebig viele Sprachpakete kombinieren.
Jede zusätzliche Sprache erhöht den Speicherbedarf und verlängert die OCR-Laufzeit – halte die Auswahl also so klein wie möglich.

Verfügbare Sprachpakete (Auswahl)

Sprache Paketname Code
Deutsch tesseract-ocr-deu deu
Englisch tesseract-ocr-eng eng
Französisch tesseract-ocr-fra fra
Italienisch tesseract-ocr-ita ita
Spanisch tesseract-ocr-spa spa
Polnisch tesseract-ocr-pol pol
Niederländisch tesseract-ocr-nld nld
Dänisch tesseract-ocr-dan dan
Schwedisch tesseract-ocr-swe swe
Norwegisch tesseract-ocr-nor nor
Türkisch tesseract-ocr-tur tur
Tschechisch tesseract-ocr-ces ces
Ungarisch tesseract-ocr-hun hun
Kroatisch tesseract-ocr-hrv hrv
Portugiesisch tesseract-ocr-por por
Rumänisch tesseract-ocr-ron ron

Beispiel für zweisprachige Umgebung (Deutsch + Englisch):

apt install -y tesseract-ocr-deu tesseract-ocr-eng

und in der .env:

PAPERLESS_OCR_LANGUAGE=deu+eng

Tip

Wenn du nicht sicher bist, welche Sprachcodes verfügbar sind, kannst du mit

apt search tesseract-ocr-

alle installierbaren Pakete anzeigen.
Wähle nur die Sprachen, die du tatsächlich benötigst, um Ressourcen zu sparen.

👉 Screenshot geeignet: Terminalausgabe von apt search tesseract-ocr- mit mehreren Sprachpaketen sichtbar

OCR-Parameter anpassen

Die Qualität der Texterkennung hängt stark von den OCR-Einstellungen ab.
Paperless-ngx nutzt standardmäßig nur die nötigsten Parameter – für die Premium-Version optimieren wir sie gezielt,
damit Dokumente in unterschiedlichen Formaten, Sprachen und Layouts zuverlässig erkannt werden.

Öffne die Konfigurationsdatei:

nano /opt/paperless/.env

Suche den Abschnitt mit den OCR-Einstellungen und passe ihn wie folgt an (oder füge ihn hinzu, falls noch nicht vorhanden):

# Spracheinstellungen
PAPERLESS_OCR_LANGUAGE=deu+eng+fra

# Reinigungs- und Verarbeitungsmodus
PAPERLESS_OCR_CLEAN=clean-final
PAPERLESS_OCR_MODE=skip

# Zusätzliche Tesseract-Parameter
PAPERLESS_OCR_USER_ARGS=--psm 1 --oem 3

Erklärung der Parameter

Variable Beschreibung
PAPERLESS_OCR_LANGUAGE Definiert die verwendeten Sprachen für die Texterkennung. Hier: Deutsch, Englisch, Französisch. Paperless prüft automatisch jede Seite in allen angegebenen Sprachen.
PAPERLESS_OCR_CLEAN Aktiviert eine Nachbearbeitung des Dokuments, um Kontrast, Kanten und Ränder zu optimieren. Der Wert clean-final sorgt für bestmögliche Lesbarkeit, besonders bei Scans.
PAPERLESS_OCR_MODE Steuert, wann OCR ausgeführt wird. skip bedeutet: OCR wird nur bei Bedarf gestartet, wenn keine Textschicht vorhanden ist. So sparst du Ressourcen und beschleunigst den Import.
PAPERLESS_OCR_USER_ARGS Übergibt erweiterte Parameter direkt an Tesseract.
--psm 1 analysiert das gesamte Seitenlayout mit mehreren Textblöcken.
--oem 3 aktiviert die moderne neuronale Texterkennung (LSTM).

Tip

Wenn du häufig gescannte Formulare, Quittungen oder Bildschirmfotos importierst, kann --psm 4 (mehrspaltige Layoutanalyse) oder --psm 6 (einheitlicher Absatz) bessere Ergebnisse liefern.
Diese Werte lassen sich gefahrlos testen – die Änderungen greifen sofort nach einem Neustart des Dienstes.

Speichern (STRG + O, Enter), schließen (STRG + X) und Paperless-ngx neu starten:

systemctl restart paperless

Note

Änderungen in der .env wirken sich nur auf neu importierte Dokumente aus.
Bereits archivierte Dateien behalten ihre ursprünglichen OCR-Daten.
Du kannst ältere Dokumente bei Bedarf manuell neu verarbeiten lassen – das wird im Premium-Kapitel zur Automatisierung behandelt.

👉 Screenshot geeignet: geöffnete .env-Datei mit kommentierten OCR-Parametern und markiertem Abschnitt PAPERLESS_OCR_USER_ARGS

Automatisierte Dokumentenverarbeitung mit n8n

Paperless-ngx kann über n8n automatisiert mit anderen Diensten im UCC interagieren.
Damit lassen sich Dokumente automatisch importieren, sortieren und weiterverarbeiten –
zum Beispiel aus E-Mail-Anhängen, Cloud-Uploads oder gemeinsamen Team-Ordnern.

👉 Screenshot geeignet: Architekturdiagramm mit Datenfluss zwischen E-Mail → n8n → Paperless-ngx → Nextcloud

Ziel der Integration

  • Automatischer Import von E-Mail-Anhängen oder Scan-Uploads in Paperless
  • Automatische Verschlagwortung und Weitergabe nach OCR-Erkennung
  • Übergabe fertiger Dokumente an Nextcloud, Affine oder Kopia
  • Zentrale Protokollierung aller Vorgänge in n8n

Voraussetzungen

Damit n8n und Paperless zuverlässig miteinander kommunizieren können, müssen beide Systeme korrekt eingerichtet und erreichbar sein.

  1. n8n-Container ist eingerichtet und über HTTPS erreichbar
    Test im Browser:

    https://n8n.deinedomain.tld

    Wenn das Dashboard angezeigt wird, funktioniert die Verbindung.
    Alternativ im Terminal prüfen:

    curl -k https://n8n.deinedomain.tld

    Die Ausgabe sollte HTML enthalten.

  2. Paperless-Container läuft stabil
    Prüfe den Status in Proxmox oder direkt in der Konsole:

    pct status <CTID>

    Wenn „stopped“ → starten:

    pct start <CTID>

    Anschließend sicherstellen, dass der Dienst aktiv ist:

    systemctl status paperless

    Die Ausgabe muss active (running) anzeigen.

  3. Paperless REST-API aktiv und erreichbar
    Die REST-API wird automatisch mit dem Dienst gestartet und läuft standardmäßig auf Port 8000.
    Prüfe die Erreichbarkeit:

    ss -tulpen | grep 8000

    Eine Zeile mit 0.0.0.0:8000 oder [::]:8000 zeigt, dass der Port offen ist.
    Falls keine Ausgabe erfolgt, starte den Dienst neu:

    systemctl restart paperless

    Danach Browser-Test:

    http://<IP-des-Containers>:8000/api/

    Wenn eine JSON-Ausgabe erscheint (z. B. { "count": 0, "next": null, ... }), ist die REST-API korrekt aktiv.

  4. API-Token erstellen
    Melde dich in der Weboberfläche von Paperless-ngx als Administrator an.
    Gehe zu Einstellungen → API Tokens → Neues Token anlegen.
    Vergib einen aussagekräftigen Namen, z. B. n8n-automation, und kopiere den generierten Token.
    Er wird später im Workflow verwendet.

Note

Jeder Benutzer kann eigene Tokens anlegen. Für Automatisierungen empfiehlt sich ein dedizierter technischer Account mit eingeschränkten Rechten.

👉 Screenshot geeignet: Paperless-API-Token-Übersicht mit markiertem Token n8n-automation

Workflow in n8n erstellen

Öffne dein n8n-Dashboard und lege einen neuen Workflow an.

Node 1 – IMAP Email (Trigger)

Zweck: Liest neue E-Mails ein und extrahiert Anhänge zur Weiterverarbeitung in Paperless-ngx.

Node-Typ: IMAP Email
Name: Eingang – Rechnungsimport

Parameter:

  • Email Protocol: IMAP
  • Host: imap.<dein-mailanbieter>.tld
  • Port: 993
  • SSL/TLS: aktiviert
  • User: <deine@mailadresse>
  • Password: <anwendungsspezifisches Passwort>

Note

Einige Mailanbieter (z. B. Google, Outlook, GMX, Web.de) blockieren den direkten Login mit dem Hauptpasswort.
Erstelle ein anwendungsspezifisches Passwort, das nur für n8n gilt.
Anleitung findest du in der Dokumentation deines Anbieters unter „App-Passwörter“ oder „Zugriff durch Drittanbieter“.

Optionen:

  • Download Attachments: aktiviert
  • Attachment Prefix: /data/mail-imports/
  • Mark Email As Read: aktiviert

👉 Screenshot geeignet: n8n-Node „IMAP Email“ mit aktivem Attachment-Download

Node 2 – HTTP Request → Upload zu Paperless

Zweck: Sendet die empfangenen Anhänge automatisch über die REST-API an Paperless-ngx.

Node-Typ: HTTP Request
Name: Upload → Paperless API

Parameter:

  • Method: POST
  • URL: 
    https://paperless.deinedomain.tld/api/documents/post_document/
  • Authentication: Header
  • Header Parameter:
    • Authorization: Token <DEIN_API_TOKEN>
    • Content-Type: multipart/form-data
  • Body Parameters:
    • document: {{$binary.data}}
    • title: {{$json["subject"]}}
    • correspondent: "Mailimport"

Note

Paperless akzeptiert Uploads nur mit gültigem API-Token.
Prüfe Domain, Port und Protokoll (https://), sonst antwortet der Server mit 403 oder 401.

👉 Screenshot geeignet: n8n-Workflow mit HTTP Request-Node „Upload → Paperless API“

Node 3 – HTTP Request → Nextcloud Export

Zweck: Exportiert fertig verarbeitete Dokumente aus Paperless direkt in Nextcloud zur zentralen Ablage.

Node-Typ: HTTP Request
Name: Export → Nextcloud

Parameter:

  • Method: PUT
  • URL: 
    https://nextcloud.deinedomain.tld/remote.php/dav/files/<BENUTZERNAME>/Archiv/{{ $json["title"] }}.pdf
  • Authentication: Header
  • Header Parameter:
    • Authorization: Basic <base64-encoded user:pass>
    • Content-Type: application/pdf
  • Body:
    • {{$binary.document.data}}

Tip

Diese Integration ermöglicht einen vollständigen Dokumentenfluss vom Mail-Eingang über OCR bis zum archivierten PDF in Nextcloud.
Alternativ kann der Export auch in Kopia oder einen dedizierten Backup-Ordner geleitet werden.

👉 Screenshot geeignet: n8n-Workflow mit allen drei Nodes (IMAP → Paperless Upload → Nextcloud Export)

Workflow-Aufbau

Der Workflow besteht aus drei Haupt-Nodes, die direkt miteinander verbunden sind:

  1. Node 1 (IMAP Email) → Node 2 (HTTP Request → Paperless API)

    • Überträgt jede empfangene E-Mail samt Anhang an Paperless-ngx.

  2. Node 2 (HTTP Request → Paperless API) → Node 3 (HTTP Request → Nextcloud Export)

    • Wenn der Upload erfolgreich war (status == 200), wird das resultierende Dokument automatisch in Nextcloud gespeichert.

Damit ergibt sich eine lineare Abfolge:

IMAP Email  →  Upload Paperless  →  Export Nextcloud

Optional kann zwischen Node 2 und 3 ein IF-Node eingefügt werden,
der nur bei erfolgreichem Upload (HTTP 200 OK) den Export ausführt.

👉 Screenshot geeignet: n8n-Canvas mit verbundenen Nodes (1 → 2 → 3)

Automatisches Tagging & Sortierlogik

Dieser Abschnitt erweitert den bestehenden Workflow aus Kapitel Premium – Paperless-ngx.
Du setzt also direkt dort an, wo die Dokumente nach dem Upload bereits in Paperless angekommen sind.
Ziel ist, die erkannten oder importierten Dokumente automatisch zu klassifizieren – zum Beispiel anhand des E-Mail-Betreffs oder Dateinamens.

👉 Screenshot geeignet: n8n-Canvas mit kompletter Verbindung IMAP → Paperless → Nextcloud → Tagging

Erweiterung des bestehenden Workflows

Der bisherige Ablauf endet nach dem erfolgreichen Export in Nextcloud:

IMAP Email  →  Upload Paperless  →  Export Nextcloud

Daran anschließend folgen nun drei zusätzliche Nodes, die über die Main-Connection mit Node 3 (Export Nextcloud) verbunden werden.
Damit wird der Ablauf linear fortgeführt:

IMAP Email  →  Upload Paperless  →  Export Nextcloud  →  IF Bedingung  →  Tag Create  →  Tag Assign

Node 4 – IF (Bedingung: enthält Schlagwort)

Zweck: Prüft, ob der E-Mail-Betreff oder der Dateiname ein bestimmtes Schlüsselwort enthält, z. B. „Rechnung“, „Vertrag“ oder „Steuer“.

Node-Typ: IF
Name: Bedingung – Enthält Schlagwort

Verbindung:
Eingang von Node 3 – Export Nextcloud
TRUE-Ausgang geht an Node 5 – Tag Create, FALSE-Ausgang beendet den Workflow.

Parameter:

  • Parameter 1: {{$json["subject"]}}
  • Operation: Contains
  • Value: "Rechnung"

👉 Screenshot geeignet: IF-Node mit Bedingung subject contains Rechnung

Tip

Du kannst mehrere dieser IF-Nodes in Reihe oder parallel verwenden, um verschiedene Kategorien zu erkennen –
etwa für unterschiedliche Absender, Betreffzeilen oder Dokumenttypen.

Node 5 – HTTP Request → Tag erstellen

Zweck: Erstellt in Paperless-ngx automatisch das passende Tag, falls es noch nicht existiert.
Wird das Tag bereits gefunden, liefert die API den bestehenden Datensatz zurück.

Node-Typ: HTTP Request
Name: Tag Create → Paperless API

Verbindung:
Eingang von Node 4 – IF Bedingung (TRUE-Pfad)
Ausgang an Node 6 – Tag zuweisen

Parameter:

  • Method: POST
  • URL: 
    https://paperless.deinedomain.tld/api/tags/
  • Authentication: Header
  • Header Parameter:

    • Authorization: Token <DEIN_API_TOKEN>

      Note

      Verwende hier denselben API-Token, den du bereits im Free-Kapitel beim Test der REST-API erzeugt hast.
      Paperless erlaubt mehrere gleichzeitige Tokens pro Benutzer – du kannst denselben Key auch in n8n einsetzen,
      solange der Benutzer dieselben Zugriffsrechte behält.

    • Content-Type: application/json

  • Body: 
    {
  "name": "Rechnung"
}

👉 Screenshot geeignet: HTTP Request-Node „Tag Create → Paperless API“

Note

Paperless behandelt diesen Vorgang idempotent – das bedeutet, das Tag wird nur einmal angelegt,
doppelte Requests sind unkritisch.

Node 6 – HTTP Request → Tag dem Dokument zuweisen

Zweck: Verknüpft das zuvor angelegte oder vorhandene Tag mit dem zuletzt hochgeladenen Dokument in Paperless.

Node-Typ: HTTP Request
Name: Tag Assign → Dokument

Verbindung:
Eingang von Node 5 – Tag Create
Keine weiteren Ausgänge erforderlich.

Parameter:

  • Method: PATCH
  • URL: 
    https://paperless.deinedomain.tld/api/documents/{{ $json["id"] }}/
  • Authentication: Header
  • Header Parameter:

    • Authorization: Token <DEIN_API_TOKEN>

      Note

      Verwende hier denselben API-Token, den du bereits im Free-Kapitel beim Test der REST-API erzeugt hast.
      Paperless erlaubt mehrere gleichzeitige Tokens pro Benutzer – du kannst denselben Key auch in n8n einsetzen,
      solange der Benutzer dieselben Zugriffsrechte behält.

    • Content-Type: application/json

  • Body: 
    {
  "tags": ["/api/tags/1/"]
}

👉 Screenshot geeignet: HTTP Request-Node „Tag Assign → Dokument“

Tip

Die Tag-ID /api/tags/1/ kann dynamisch aus dem vorherigen Request übernommen werden,
z. B. mit einem „Set“-Node oder per JavaScript-Ausdruck {{$json["id"]}}.

Ergebnis

Damit ist dein Workflow vollständig automatisiert:
Jede eingehende E-Mail wird verarbeitet, hochgeladen, archiviert, und anschließend intelligent getaggt.

IMAP Email  →  Upload Paperless  →  Export Nextcloud  →  IF Schlagwort  →  Tag Create  →  Tag Assign

Das Ergebnis ist eine vollständig automatisierte Dokumentenpipeline –
von der Eingangsmail bis zur verschlagworteten, archivierten PDF-Datei im UCC-System.

Integration mit anderen UCC-Diensten

Paperless-ngx fügt sich direkt in die Infrastruktur des UCC ein.
Dokumente werden automatisch kategorisiert, in Nextcloud archiviert, über Kopia gesichert und durch Vaultwarden abgesichert.
In diesem Abschnitt konzentrieren wir uns auf die automatische Kategorisierung und Ablage in Nextcloud.

👉 Screenshot geeignet: Diagramm mit Datenfluss Paperless → n8n → Nextcloud

Nextcloud – Automatische Ablage und Kategorisierung

Nach erfolgreicher OCR-Verarbeitung und Tagging sollen die Dokumente automatisch in Nextcloud abgelegt werden.
Die Zuordnung erfolgt über einen Switch-Node, der anhand der erkannten Tags entscheidet,
und einen Merge-Node, der alle Kategorien wieder zu einem gemeinsamen Strang zusammenführt,
bevor ein einzelner Upload-Node die Datei in Nextcloud schreibt.

Der vollständige Ablauf:

IMAP Email → Upload Paperless → Switch Kategorie → Merge Kategorien → Upload Nextcloud

Node 7 – Switch (Kategoriewahl)

Zweck:
Analysiert die im JSON enthaltenen Tags und ordnet sie einer definierten Kategorie zu.

Node-Typ: Switch
Name: Kategorie bestimmen

Verbindung:
Eingang von Node 2 – Upload Paperless

Parameter (Community-Version):

  • Mode: Rules
  • Property Name: {{$json["tags"]}}
  • Routing Rules:
    # Data Type Operation Value Beschreibung
    1 String contains Rechnung Ausgang 1
    2 String contains Vertrag Ausgang 2
    3 String contains Versicherung Ausgang 3

Tip

Jede weitere Regel im Switch erzeugt automatisch einen neuen Ausgang.
So bleibt die Workflow-Struktur klar und skalierbar.

👉 Screenshot geeignet: Switch-Node mit drei Ausgängen (Rechnung, Vertrag, Versicherung)

Node 8 – Merge (Kategorien zusammenführen)

Zweck:
Führt die verschiedenen Ausgänge des Switch wieder zu einem einheitlichen Datenstrom zusammen,
damit der Upload zentral ausgeführt werden kann.

Node-Typ: Merge
Name: Kategorien zusammenführen

Verbindung:
Eingänge von allen Ausgängen des Switch-Nodes (Rechnung, Vertrag, Versicherung)

Parameter:

  • Mode: Merge By Position

Note

Der Merge-Node sorgt dafür, dass alle Dokumente unabhängig von ihrer Kategorie
gesammelt an den Upload-Node übergeben werden.

👉 Screenshot geeignet: Merge-Node mit drei Eingängen, verbunden mit Switch-Ausgängen

Node 9 – HTTP Request (Upload zu Nextcloud)

Zweck:
Lädt das zusammengeführte Dokument in den zentralen Nextcloud-Ordner hoch.
Der Ordnerpfad kann optional dynamisch aus dem Tag abgeleitet werden.

Node-Typ: HTTP Request
Name: Upload → Nextcloud

Verbindung:
Eingang von Node 8 – Merge Kategorien

Parameter (Community-Version):

  • Method: PUT
  • URL: 
    https://nextcloud.deinedomain.tld/remote.php/dav/files/<BENUTZERNAME>/Archiv/{{$json["tags"][0]}}/{{$json["title"]}}.pdf
  • Authentication: Basic Auth
  • User: <NEXTCLOUD_USER>
  • Password: <NEXTCLOUD_PASS> (empfohlen: aus Vaultwarden-Secret)
  • Send Binary Data: aktiviert
  • Binary Property: document

Tip

Durch die Variable {{$json["tags"][0]}} wählt n8n automatisch den ersten erkannten Tag
als Ordnername. Damit entfällt die manuelle Zuweisung im Switch.

👉 Screenshot geeignet: HTTP-Node mit dynamischer URL und aktivem Binary-Upload

Ergebnis

Der Workflow arbeitet nun vollständig dynamisch:

  1. Paperless erkennt und taggt Dokumente.
  2. n8n liest die Tags aus.
  3. Der Switch verteilt sie logisch.
  4. Der Merge fasst alle Ströme wieder zusammen.
  5. Ein einzelner HTTP-Request lädt die Datei in den passenden Nextcloud-Ordner.

Das Ergebnis ist ein sauberer, wartungsfreier Datenfluss –
flexibel erweiterbar und perfekt in das UCC-System integriert.

Kopia – Automatische Sicherung der Paperless-Daten

Damit deine verarbeiteten Dokumente und OCR-Ergebnisse dauerhaft erhalten bleiben,
müssen die wichtigsten Paperless-Verzeichnisse regelmäßig gesichert werden.
Dafür kommt im UCC wie gewohnt Kopia zum Einsatz.

👉 Screenshot geeignet: Kopia-Webinterface mit aktivem Backup-Job „Paperless“

Zu sichernde Verzeichnisse

Verzeichnis Beschreibung
/opt/paperless/data/ Enthält alle Dokumente (PDFs, OCR-Dateien, Previews)
/opt/paperless/media/ Temporäre Uploads und eingehende Dateien
/etc/paperless/ System- und OCR-Konfiguration

Diese Verzeichnisse sollten täglich oder wöchentlich gesichert werden – je nach Änderungsfrequenz.

Snapshot manuell testen

kopia snapshot create /opt/paperless/data

Wenn der Befehl erfolgreich ist, erscheint in der Übersicht ein neuer Eintrag „paperless-data“.
Danach lässt sich das Backup über den Webclient oder den Zeitplan automatisieren.

Note

Wenn du bereits eine globale UCC-Sicherungsstrategie hast, in der alle Container-Verzeichnisse erfasst werden,
brauchst du Paperless nicht separat hinzufügen.
Prüfe aber, ob die data- und media-Ordner wirklich enthalten sind.

👉 Screenshot geeignet: Terminalausgabe von kopia snapshot create /opt/paperless/data (erfolgreicher Lauf)

Automatisierte Sicherung per n8n (optional)

Falls du Kopia-Backups direkt aus dem Workflow starten möchtest,
kannst du über einen HTTP Request oder Execute Command Node den Kopia-CLI-Aufruf anstoßen.

Beispiel über Execute Command Node:

Node-Typ: Execute Command
Name: Kopia Snapshot starten

Verbindung:
Eingang vom letzten Node des Workflows (Upload Nextcloud oder Merge Kategorien)

Parameter:

  • Command: 
    kopia snapshot create /opt/paperless/data

Tip

Dieser Schritt ist optional, aber praktisch, wenn du Dokumentenverarbeitung und Sicherung koppeln möchtest.
So kannst du nach jedem Upload automatisch ein Snapshot-Update auslösen.

👉 Screenshot geeignet: Execute Command Node „Kopia Snapshot starten“ mit Command-Feld

Vaultwarden – Sichere Verwaltung sensibler Zugangsdaten

Für die sichere Speicherung von Zugangsdaten, Tokens und Passwörtern nutzt du Vaultwarden.
So stellst du sicher, dass n8n keine sensiblen Daten im Klartext enthält.

Vorgehensweise

  1. Öffne die Vaultwarden-Weboberfläche.
  2. Erstelle einen neuen Eintrag vom Typ „API Key“.
  3. Vergib den Namen Paperless_API_Token.
  4. Trage dort den im Free-Kapitel erstellten Paperless-Token ein.
  5. Optional: Lege auch Nextcloud- und SMTP-Logins als separate Secrets an.
  6. Exportiere die Secrets als Umgebungsvariablen für n8n: 
    export PAPERLESS_API_TOKEN=<TOKEN>
export NEXTCLOUD_PASS=<PASSWORT>
  7. In n8n kannst du dann auf diese Werte zugreifen, z. B.: 
    {{$env.PAPERLESS_API_TOKEN}}

Note

Diese Methode schützt alle sensiblen Daten zuverlässig,
da sie nicht in exportierten Workflows oder Logs auftauchen.

👉 Screenshot geeignet: Vaultwarden-Eintrag „Paperless_API_Token“ mit ausgeblendeten Werten

Mit dieser Integration ist das System komplett:

  • Paperless verarbeitet und erkennt Dokumente,
  • n8n organisiert sie automatisch,
  • Nextcloud speichert sie zentral,
  • Kopia sichert sie regelmäßig,
  • Vaultwarden schützt alle Anmeldeinformationen.

Damit ist dein UCC vollständig automatisiert, sicher und transparent dokumentiert.

Überwachung & Health-Checks mit Netdata

Damit Paperless-ngx im Dauerbetrieb stabil läuft, sollte die Instanz über Netdata überwacht werden.
So erkennst du Engpässe, ungewöhnliche CPU-Last durch OCR-Verarbeitung oder verzögerte Uploads frühzeitig.
Die Integration erfolgt wie bei allen anderen Containern über das Netdata-Streaming-System.

👉 Screenshot geeignet: Netdata-Dashboard mit aktiver Paperless-Instanz (CPU-Last und I/O-Aktivität sichtbar)

Paperless-Container als Child hinzufügen

  1. Öffne die Konsole deines Paperless-Containers.
  2. Installiere den Netdata-Agent (falls noch nicht vorhanden): 
    bash <(curl -Ss https://my-netdata.io/kickstart.sh) --stable-channel --disable-telemetry
  3. Öffne die Streaming-Konfiguration: 
    nano /etc/netdata/stream.conf
  4. Ergänze oder ändere die folgenden Zeilen: 
    [stream]
    enabled = yes
    destination = <IP-des-Netdata-Parents>:19999
    api key = paperless-ngx
    hostname = Paperless
  5. Dienst neu starten: 
    systemctl restart netdata

Note

Der Parent-Container ist deine zentrale Netdata-Instanz aus Kapitel 15.
Stelle sicher, dass Port 19999 intern erreichbar ist.

👉 Screenshot geeignet: stream.conf mit konfiguriertem destination-Eintrag

Relevante Metriken

Nach dem Neustart erscheint der Paperless-Container automatisch im Netdata-Dashboard.
Wichtige Kennzahlen:

Bereich Beschreibung
CPU usage Belastung durch OCR-Prozesse (tesseract oder celery)
Disk I/O Schreibaktivität in /opt/paperless/data/
Network Upload-Volumen zu Nextcloud
Processes Laufende Worker- und Gunicorn-Prozesse
Memory Puffer- und Cacheverbrauch während OCR-Phasen

Tip

Dauerhafte CPU-Last über 80 % deutet oft auf parallel laufende OCR-Jobs hin.
In diesem Fall kann ein Neustart des Containers oder eine Erhöhung der CPU-Zuteilung sinnvoll sein.

👉 Screenshot geeignet: Paperless-Dashboard mit CPU- und Disk-I/O-Diagrammen

Alarmierung (optional)

Wenn du bereits das Premium-Netdata-Kapitel umgesetzt hast,
kannst du dortige Alarmregeln wiederverwenden, um bei hoher CPU-Last oder Fehlern im OCR-Dienst benachrichtigt zu werden.

Beispielregel in /etc/netdata/health.d/paperless.conf:

alarm: paperless_cpu_high
on: system.cpu
lookup: average -1m unaligned of user + system
units: %
every: 30s
warn: $this > 80
crit: $this > 95
to: sysadmin
info: Paperless CPU usage is too high

Note

Die Regel nutzt den gleichen Benachrichtigungskanal wie deine bestehenden Alerts (Discord, Mail oder n8n-Webhook).
Du kannst auch spezifische Health-Checks nur für Paperless aktivieren.

👉 Screenshot geeignet: Health-Tab in Netdata mit aktiviertem Alarm „paperless_cpu_high“

Damit ist Paperless-ngx in dein bestehendes Monitoring eingebunden.
Alle wichtigen Metriken erscheinen zentral in Netdata,
und Störungen können sofort erkannt oder automatisch weitergeleitet werden.

Ergebnis

Nach Abschluss dieses Premium-Kapitels ist Paperless-ngx vollständig in das UCC integriert –
nicht nur als Dokumentenarchiv, sondern als intelligentes, automatisiertes Verwaltungssystem,
das sich nahtlos in Nextcloud, Netdata, Kopia und Vaultwarden einfügt.

Deine UCC-Struktur arbeitet jetzt folgendermaßen:

Dienst Aufgabe Automatisierung
Paperless-ngx Zentrale Dokumentenverarbeitung (OCR, Tagging, Indexierung) verarbeitet E-Mails und Uploads automatisch
n8n Workflow-Automatisierung verteilt, verschiebt und kategorisiert Dokumente in Nextcloud
Nextcloud Speicherung und gemeinsame Nutzung erhält automatisch sortierte Dateien
Kopia Sicherung erstellt Snapshots der relevanten Verzeichnisse
Vaultwarden Zugriffsschutz verwaltet Tokens und Zugangsdaten verschlüsselt
Netdata Überwachung kontrolliert Ressourcenauslastung, OCR-Last und Systemzustand

👉 Screenshot geeignet: Gesamtübersicht des UCC mit Paperless, n8n, Nextcloud, Netdata, Kopia und Vaultwarden

Vorteile des erweiterten Paperless-Setups

  • Vollautomatischer Dokumentenfluss:
    E-Mails und Scans werden automatisch erkannt, verarbeitet und abgelegt – ohne manuelles Eingreifen.

  • Kategorisierung über Tags:
    Intelligente Klassifikation in Nextcloud-Ordner auf Basis von Tags oder OCR-Inhalten.

  • Zentrale Sicherung:
    Kopia erstellt eigenständig Snapshots der Paperless-Daten und OCR-Cache-Dateien.

  • Transparente Systemüberwachung:
    Netdata überwacht die Ressourcennutzung, erkennt Engpässe und alarmiert bei Überlastung.

  • Sichere Zugangsdaten:
    Vaultwarden hält alle API-Tokens und Passwörter zentral unter Kontrolle.

Tip

Dieses Setup ist modular erweiterbar:
Du kannst später PDF-Kompression, Texterkennung für zusätzliche Sprachen oder direkte Uploads aus mobilen Apps ergänzen.
Alles fügt sich sauber in die bestehende Struktur ein.

Zusammenfassung der Architektur

📧 Eingang → Paperless-ngx (OCR, Tagging)
     ↓
🔁 n8n → (Switch → Merge → Upload → Nextcloud)
     ↓
💾 Kopia → Sicherung der Daten
     ↓
🧠 Vaultwarden → Schlüsselverwaltung
     ↓
📊 Netdata → Monitoring & Alerts

👉 Screenshot geeignet: Architekturdiagramm mit allen Datenflüssen zwischen Paperless, n8n, Nextcloud, Kopia, Vaultwarden und Netdata

Damit ist dein Dokumenten-Workflow im UCC vollständig automatisiert,
datensicher, erweiterbar und zentral überwacht –
ein System, das für Streamer, Kreative und Technikinteressierte gleichermaßen praxistauglich ist.