Homelab--Bratonein-Kontrollzentrum--Tutorial/Kapitel 16/Premium Rohtext.md

# 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:

```bash
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):

```bash
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  
> ```bash
> 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:

```bash
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. <br> `--psm 1` analysiert das gesamte Seitenlayout mit mehreren Textblöcken. <br> `--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:

```bash
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:
   ```bash
   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:
   ```bash
   pct status <CTID>
   ```
   Wenn „stopped“ → starten:
   ```bash
   pct start <CTID>
   ```
   Anschließend sicherstellen, dass der Dienst aktiv ist:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:**  
  ```json
  {
    "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:**  
  ```json
  {
    "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

```bash
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:  
   ```bash
   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
   bash <(curl -Ss https://my-netdata.io/kickstart.sh) --stable-channel --disable-telemetry
   ```
3. Öffne die Streaming-Konfiguration:
   ```bash
   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:
   ```bash
   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.