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

# Kapitel 16 – Paperless-ngx (Digitale Dokumentenverwaltung & OCR-Archiv)

## Einleitung

Im UCC spielt eine **zuverlässige Dokumentenverwaltung** eine zentrale Rolle – egal ob du Rechnungen, Verträge, Streaming-Belege oder Notizen sicher ablegen willst.  
**Paperless-ngx** bietet dafür eine datensouveräne Lösung: eine schlanke, lokal gehostete Plattform, die deine Dokumente automatisch erkennt, verschlagwortet und durchsuchbar macht – komplett offline, ohne externe Cloud.

In diesem Kapitel baust du eine eigene **Paperless-ngx-Instanz** auf Basis eines **Debian-12-LXC** auf.  
Du lernst, wie du sie installierst, konfigurierst und über den **Nginx Proxy Manager** sicher in dein UCC integrierst.  
Das Ergebnis ist ein vollwertiges, durchsuchbares Dokumentenarchiv, das sich nahtlos in deine bestehende Infrastruktur einfügt.

👉 **Screenshot geeignet:** UCC-Übersicht mit markiertem Paperless-ngx-Container neben Nextcloud und Netdata

> [!NOTE]  
> Dieses Kapitel richtet sich an **Streamer:innen, Einsteiger:innen und Nerds**,  
> die unabhängig arbeiten und ihre Daten lieber selbst verwalten wollen.  
> Paperless-ngx läuft vollständig lokal – kein Konto, keine Telemetrie, keine Abhängigkeiten von Dritten.

Paperless-ngx kombiniert eine moderne Weboberfläche mit einer performanten **OCR-Erkennung** und klar strukturiertem Tag-System.  
So wird dein UCC nicht nur zum digitalen Archiv, sondern auch zum Werkzeug für schnelle Recherche und revisionssichere Ablage.

👉 **Screenshot geeignet:** Browseransicht mit Paperless-Dashboard (Dokumentenliste, Suchfeld und Tag-Filter sichtbar)

---

## Voraussetzungen & Ressourcen

Paperless-ngx ist ressourcenschonend, benötigt aber eine stabile Umgebung für den dauerhaften Betrieb.  
Da das System mehrere Prozesse (Webserver, Datenbank, OCR-Engine) parallel ausführt, sollte der Container klar definiert dimensioniert sein.

### Container-Ressourcen

* **CPU:** 2 vCPU  
  Erforderlich, um OCR-Jobs und Webzugriffe parallel abarbeiten zu können, ohne dass sich die Erkennung verlangsamt.

* **RAM:** 4 GB  
  Die OCR-Engine (Tesseract) und die Django-basierte Weboberfläche profitieren stark von zusätzlichem Arbeitsspeicher.

* **Speicherplatz:** 30 GB  
  Reicht für das System, Caching, Logs und eine mittlere Dokumentenmenge aus.  
  Bei größerem Archiv kann später ein separater Storage angebunden werden.

* **Netzwerk:** Statische IP-Adresse oder DHCP-Reservierung  
  Notwendig für eine zuverlässige Integration in Proxy-Manager und Backup-Prozesse.

* **Betriebssystem:** Debian 12 (Bookworm)  
  Stabil, leichtgewichtig und in allen bisherigen UCC-Komponenten bewährt.

👉 **Screenshot geeignet:** Ressourcenübersicht beim Erstellen des Paperless-LXC (vCPU 2 | RAM 4 GB | Storage 30 GB | Debian 12 Bookworm)

### Technische Voraussetzungen

Vor der Installation sollte das UCC folgende Bedingungen erfüllen:

* **Proxmox VE** ist eingerichtet und aktiv.  
  Der Container wird direkt über die Proxmox-Oberfläche erstellt und verwaltet.

* **Nginx Proxy Manager (NPM)** ist funktionsfähig.  
  Er stellt später die Weboberfläche von Paperless-ngx über HTTPS bereit.

* **DNS- oder DynDNS-Eintrag** für `paperless.deinedomain.tld` existiert.  
  Dieser ist notwendig, um ein gültiges SSL-Zertifikat ausstellen zu können.

* **Internetverbindung** im Container ist aktiv.  
  Paperless-ngx wird über die offiziellen Repositories installiert und benötigt Internetzugriff beim Setup.

* **SSH-Zugriff** auf den Container ist möglich, zum Beispiel:
  ```bash
  ssh root@<IP-des-Containers>
  ```
  Ersetze `<IP-des-Containers>` durch die tatsächliche Adresse deines Paperless-LXC.

> [!IMPORTANT]  
> Der Paperless-Container sollte auf einem Host mit stabiler Netzwerkanbindung liegen und genügend I/O-Leistung haben.  
> Die OCR-Erkennung erzeugt kurzzeitig hohe CPU- und Festplattenlast.

👉 **Screenshot geeignet:** Proxmox-Interface mit markiertem Paperless-LXC in der Containerliste

--- 

## Schritt-für-Schritt-Anleitung

### Schritt 1 – System vorbereiten und aktualisieren

Starte den frisch erstellten Container und öffne die Konsole – direkt in Proxmox oder per SSH.  
Führe anschließend ein vollständiges Systemupdate durch, um alle Pakete auf den neuesten Stand zu bringen:

```bash
apt update && apt upgrade -y
```

Nach Abschluss des Updates den Container neu starten:

```bash
reboot
```

Melde dich nach dem Neustart erneut an:

```bash
ssh root@<IP-des-Containers>
```

> [!NOTE]  
> Das Update ist Pflicht, da Paperless-ngx auf aktuelle Python- und Systembibliotheken angewiesen ist.  
> Alte Pakete können zu Fehlern bei der Installation oder beim Start des Webservers führen.

👉 **Screenshot geeignet:** Proxmox-Konsole mit erfolgreichem Abschluss von `apt upgrade` (keine ausstehenden Pakete)

### Schritt 2 – Basis-Pakete installieren

Paperless-ngx benötigt für seine Installation einige grundlegende Pakete, um HTTPS-Verbindungen, GPG-Schlüssel und Python-Umgebungen zu verwalten.  
Diese werden jetzt installiert:

```bash
apt install -y ca-certificates curl gnupg lsb-release python3 python3-venv python3-pip redis-server
```

Damit sind alle zentralen Komponenten vorhanden, die Paperless-ngx später nutzt:  
- **curl & gnupg:** für Repository- und Paketverwaltung  
- **python3 & venv:** für die Django-basierte Weboberfläche  
- **redis-server:** als Caching- und Warteschlangendienst

> [!TIP]  
> Wenn bei der Installation ein Fehler auftritt, überprüfe zuerst die Internetverbindung des Containers  
> und wiederhole den Befehl. Debian benötigt funktionierende DNS-Auflösung, um alle Abhängigkeiten zu laden.

👉 **Screenshot geeignet:** Terminalausgabe nach erfolgreicher Installation der Grundpakete (`python3`, `redis-server`, `curl`)

### Schritt 3 – Benutzer und Verzeichnisstruktur anlegen

Paperless-ngx läuft sicherer, wenn es nicht als root, sondern unter einem eigenen Systembenutzer betrieben wird.  
Lege daher zunächst den Benutzer und die Standardverzeichnisse an:

```bash
useradd -r -m -d /opt/paperless -s /bin/bash paperless
mkdir -p /opt/paperless/data /opt/paperless/media /opt/paperless/export
chown -R paperless:paperless /opt/paperless
```

Damit sind die grundlegenden Speicherorte angelegt:
- **/opt/paperless/data** – Datenbank, Konfiguration und interne Dateien  
- **/opt/paperless/media** – Dokumente und OCR-Ergebnisse  
- **/opt/paperless/export** – für spätere Backups oder manuelle Exporte

> [!NOTE]  
> Diese Struktur entspricht der Empfehlung des Paperless-Projekts und erleichtert spätere Updates oder Migrationen.  
> Sie trennt Anwendungsdaten klar von Systempfaden.

👉 **Screenshot geeignet:** Terminal mit ausgeführtem `ls -l /opt/paperless` (alle drei Unterordner sichtbar, Eigentümer „paperless“)

### Schritt 4 – Paperless-ngx installieren

Wechsle in das Benutzerverzeichnis und führe die Installation direkt unter dem Benutzer *paperless* aus:

```bash
su - paperless
cd /opt/paperless
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip wheel
pip install paperless-ngx
```

Damit wird die aktuelle stabile Version von Paperless-ngx aus dem offiziellen Python-Repository installiert.  
Die Installation kann – je nach Systemleistung – mehrere Minuten dauern.

> [!NOTE]  
> Paperless-ngx nutzt intern Django, Celery und Redis.  
> Durch die Installation in einer eigenen virtuellen Umgebung (`venv`) bleiben alle Abhängigkeiten sauber getrennt vom Basissystem.

Nach Abschluss der Installation kannst du den Erfolg prüfen:

```bash
paperless-ngx --version
```

Die Ausgabe sollte eine aktuelle Versionsnummer anzeigen, z. B.:
```
paperless-ngx 2.11.2
```

👉 **Screenshot geeignet:** Terminalausgabe mit sichtbarer Paperless-ngx-Versionsnummer nach erfolgreicher Installation

### Schritt 5 – Umgebungsvariablen und Konfiguration einrichten

Paperless-ngx wird über eine `.env`-Datei gesteuert.  
Darin legst du fest, **wo Daten gespeichert werden**, **welche Dienste verwendet werden** und **wie die Instanz erreichbar ist**.  
Diese Datei ist das Herzstück der gesamten Installation – alle späteren Dienste (z. B. OCR, Webserver, Redis) lesen ihre Einstellungen daraus.

Erstelle die Datei im Hauptverzeichnis des Paperless-Benutzers:

```bash
nano /opt/paperless/.env
```

Füge folgenden Basisinhalt ein:

```
# Datenbank- und Caching-Backend
PAPERLESS_REDIS=redis://localhost:6379
PAPERLESS_DBENGINE=sqlite
PAPERLESS_DBNAME=/opt/paperless/data/db.sqlite3

# Verzeichnisse
PAPERLESS_CONSUMPTION_DIR=/opt/paperless/consume
PAPERLESS_DATA_DIR=/opt/paperless/data
PAPERLESS_MEDIA_ROOT=/opt/paperless/media
PAPERLESS_EXPORT_DIR=/opt/paperless/export

# Allgemeine Einstellungen
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_PORT=8000

# OCR-Konfiguration
PAPERLESS_OCR_LANGUAGE=deu
PAPERLESS_OCR_CLEAN=clean
PAPERLESS_OCR_MODE=skip

# Sicherheit
PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)
```

Speichern (STRG + O, Enter) und schließen (STRG + X).

---

#### Erklärung der wichtigsten Parameter

| Variable | Bedeutung |
|-----------|------------|
| `PAPERLESS_REDIS` | Adresse des lokalen Redis-Dienstes für Warteschlangen und Caching. |
| `PAPERLESS_DBENGINE` / `PAPERLESS_DBNAME` | Definiert die Datenbank. Im Free-Bereich nutzen wir SQLite (lokale Datei). |
| `PAPERLESS_CONSUMPTION_DIR` | Eingangsverzeichnis für neue Dokumente. Hier überwacht Paperless-ngx ständig auf neue Dateien. |
| `PAPERLESS_DATA_DIR` | System- und Konfigurationsdaten. |
| `PAPERLESS_MEDIA_ROOT` | Ablageort für erkannte, indizierte und verschlagwortete Dokumente. |
| `PAPERLESS_EXPORT_DIR` | Ziel für manuelle oder automatisierte Exporte. |
| `PAPERLESS_TIME_ZONE` | Lokale Zeitzone – wichtig für korrekte Zeitstempel. |
| `PAPERLESS_PORT` | Interner Port, über den die Anwendung erreichbar ist (wird später über NPM veröffentlicht). |
| `PAPERLESS_OCR_LANGUAGE` | Sprache der Texterkennung (ISO 639-3-Code). |
| `PAPERLESS_SECRET_KEY` | Zufallswert für kryptografische Funktionen (Session, Login). Wird einmalig generiert. |

> [!TIP]  
> Der OCR-Modus kann später im Premium-Kapitel erweitert werden, um Scans automatisch zu bereinigen oder mehrsprachig zu verarbeiten.  
> Für den Free-Bereich bleibt er bewusst minimal gehalten, um Ressourcen zu sparen.

Erstelle anschließend das noch fehlende Eingangsverzeichnis und setze korrekte Rechte:

```bash
mkdir /opt/paperless/consume
chown -R paperless:paperless /opt/paperless
```

👉 **Screenshot geeignet:** geöffnete `.env`-Datei im Editor mit hervorgehobenen Abschnitten für Datenbank, OCR und Port

### Schritt 6 – Datenbank initialisieren und Teststart

Mit der Konfigurationsdatei im Platz kannst du Paperless-ngx jetzt zum ersten Mal starten.  
Damit die Anwendung ihre Datenbank und internen Tabellen erstellt, führe folgende Befehle als Benutzer *paperless* aus:

```bash
su - paperless
cd /opt/paperless
source venv/bin/activate
paperless-ngx migrate
```

Dieser Schritt legt automatisch die interne Datenbankstruktur an – Tabellen für Benutzer, Dokumente, Tags und OCR-Daten.  
Sobald der Vorgang abgeschlossen ist, kann die Anwendung testweise gestartet werden:

```bash
paperless-ngx runserver 0.0.0.0:8000
```

Öffne im Browser:

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

Du solltest die Paperless-Anmeldeseite sehen.  
Beim ersten Start ist noch kein Benutzer vorhanden – diesen legst du jetzt an:

```bash
paperless-ngx createsuperuser
```

Folge den Eingabeaufforderungen und wähle einen sicheren Benutzernamen und ein starkes Passwort.

> [!NOTE]  
> Der Teststart läuft im Vordergrund und dient nur zur Überprüfung der erfolgreichen Installation.  
> Im nächsten Schritt wird der Dienst dauerhaft über systemd betrieben.

👉 **Screenshot geeignet:** Browseransicht mit Paperless-Anmeldemaske unter `http://<IP-des-Containers>:8000`

### Schritt 7 – Dienst dauerhaft aktivieren (systemd)

Damit Paperless-ngx automatisch beim Start des Containers geladen wird, legen wir eine eigene systemd-Service-Datei an.  
So läuft der Dienst im Hintergrund und startet nach einem Reboot selbstständig neu.

Erstelle die Datei:

```bash
nano /etc/systemd/system/paperless.service
```

Füge folgenden Inhalt ein:

```
[Unit]
Description=Paperless-ngx Document Management
After=network.target redis-server.service

[Service]
Type=simple
User=paperless
Group=paperless
WorkingDirectory=/opt/paperless
EnvironmentFile=/opt/paperless/.env
ExecStart=/opt/paperless/venv/bin/paperless-ngx runserver 0.0.0.0:8000
Restart=always

[Install]
WantedBy=multi-user.target
```

Speichern (STRG + O, Enter) und schließen (STRG + X).  
Anschließend systemd neu laden und den Dienst aktivieren:

```bash
systemctl daemon-reload
systemctl enable paperless
systemctl start paperless
```

Prüfe, ob alles läuft:

```bash
systemctl status paperless
```

Die Ausgabe sollte **active (running)** anzeigen.

> [!TIP]  
> Wenn du Paperless später updatest, genügt ein einfacher Neustart des Dienstes:
> ```bash
> systemctl restart paperless
> ```

👉 **Screenshot geeignet:** Terminal mit sichtbarem `systemctl status paperless` und aktivem Dienststatus

### Schritt 8 – Integration in Nginx Proxy Manager (NPM)

Damit Paperless-ngx sicher und bequem erreichbar ist, wird der interne Port **8000** jetzt über den **Nginx Proxy Manager** veröffentlicht.  
So erhältst du eine HTTPS-Verbindung mit gültigem SSL-Zertifikat und kannst die Oberfläche direkt über eine Subdomain wie `https://paperless.deinedomain.tld` öffnen.

#### Proxy-Host anlegen

1. Öffne das Dashboard des **Nginx Proxy Manager**.  
2. Klicke auf **Add Proxy Host**.  
3. Trage folgende Werte ein:

| Feld | Wert |
|------|------|
| **Domain Names** | `paperless.deinedomain.tld` |
| **Scheme** | `http` |
| **Forward Hostname / IP** | `<IP-des-Paperless-Containers>` |
| **Forward Port** | `8000` |
| **Block Common Exploits** | aktivieren |
| **Websockets Support** | aktivieren |

Wechsle danach in den Reiter **SSL** und aktiviere:

- **Request a new SSL Certificate**  
- **Force SSL**  
- **HTTP/2 Support**  
- **HSTS Enabled**

Speichere mit **Save**.

> [!NOTE]  
> Der Proxy Manager erstellt automatisch ein gültiges Let’s-Encrypt-Zertifikat.  
> Ab sofort ist Paperless-ngx verschlüsselt über HTTPS erreichbar.

#### Verbindung testen

Öffne im Browser:

```
https://paperless.deinedomain.tld
```

Wenn die Anmeldemaske erscheint und der Browser ein **Schloss-Symbol** anzeigt, funktioniert die Integration.  
Melde dich mit den zuvor erstellten Zugangsdaten an.

> [!TIP]  
> Sollte die Seite nicht laden, überprüfe im NPM-Dashboard IP-Adresse und Port (8000).  
> Ein Neustart des Dienstes hilft häufig:
> ```bash
> systemctl restart paperless
> ```

👉 **Screenshot geeignet:** Browserfenster mit Paperless-Login unter `https://paperless.deinedomain.tld` (Schloss-Symbol sichtbar)

### Schritt 9 – Oberfläche und Grundfunktionen verstehen

Nach erfolgreicher Anmeldung öffnet sich das Dashboard von Paperless-ngx.  
Es zeigt eine übersichtliche Startseite mit deinen Dokumenten, Tags, Korrespondenzpartnern und Filterfunktionen.  
Alle Elemente sind klar strukturiert und intuitiv bedienbar.

👉 **Screenshot geeignet:** Browseransicht mit Paperless-Dashboard (leere Dokumentenliste und Menüleiste sichtbar)

#### Hauptbereiche der Weboberfläche

| Bereich | Beschreibung |
|----------|--------------|
| **Dokumente** | Übersicht aller hochgeladenen und erkannten Dateien. Hier findest du deine Scans, Rechnungen und PDFs. |
| **Tags** | Stichwörter zur thematischen Zuordnung (z. B. „Rechnung“, „Steuer“, „Vertrag“). |
| **Korrespondenzpartner** | Automatisch erkannte oder manuell erstellte Absender, nützlich für Sortierung und Suche. |
| **Korrespondentenregeln** | Automatisierte Zuordnung neuer Dokumente zu bestimmten Partnern oder Tags. |
| **Aufgaben / Warteschlangen** | Zeigt laufende OCR-Prozesse, Uploads und Indexierungen an. |

> [!NOTE]  
> Paperless-ngx aktualisiert die Oberfläche automatisch, sobald ein neuer Upload abgeschlossen ist.  
> Es ist kein manuelles Neuladen notwendig.

#### Upload und OCR

Dokumente können auf verschiedene Arten hinzugefügt werden:
- Direkt über den **Upload-Button** in der Weboberfläche.  
- Automatisch über das **Consumption-Verzeichnis** (`/opt/paperless/consume`).  
  Jede dort abgelegte Datei wird automatisch erkannt, gelesen und ins Archiv übernommen.

Nach dem Upload durchläuft jedes Dokument den OCR-Prozess (Texterkennung).  
Das dauert je nach Länge und Qualität des Dokuments wenige Sekunden bis Minuten.

> [!TIP]  
> Für optimale Ergebnisse sollten Dokumente in **klarer, gut lesbarer Qualität (300 dpi)** vorliegen.  
> Unscharfe oder stark komprimierte Scans können die Erkennung deutlich verlangsamen.

👉 **Screenshot geeignet:** Upload-Dialog mit aktivem Fortschrittsbalken und anschließendem Dokumenteintrag in der Liste

### Schritt 10 – Ordnerstruktur und Dokumentenfluss

Paperless-ngx arbeitet nach einem klaren Prinzip:  
Dokumente durchlaufen **drei feste Stationen** – vom Eingang bis zur archivierten, verschlagworteten Datei.

1. **Eingang (Consumption)**  
   Hier landen alle neu hinzugefügten Dokumente – manuell oder automatisch.  
   Paperless überwacht dieses Verzeichnis kontinuierlich und importiert neue Dateien selbstständig.

2. **Verarbeitung (OCR & Indexierung)**  
   Die OCR-Engine liest jedes Dokument, extrahiert Textinhalte und erkennt Datum, Absender und Schlüsselwörter.  
   Anschließend wird das Dokument in der internen Datenbank indexiert.

3. **Archiv (Media Root)**  
   Nach erfolgreicher Verarbeitung landet die optimierte, durchsuchbare Version im Archivordner.  
   Sie steht dann dauerhaft über die Weboberfläche zur Verfügung und kann mit Tags, Partnern und Notizen versehen werden.

> [!NOTE]  
> Paperless-ngx speichert die Originaldatei und die verarbeitete Version getrennt.  
> So bleibt das Original unverändert erhalten – ein wichtiger Punkt für Nachvollziehbarkeit und rechtssichere Ablage.

#### Beispielhafter Pfadaufbau

```
/opt/paperless/
├── consume/     # Eingang (automatische Überwachung)
├── data/        # interne Datenbank, Konfiguration
├── media/       # archivierte und OCR-verarbeitete Dokumente
└── export/      # manuelle oder geplante Exporte
```

> [!TIP]  
> Wenn du Dokumente automatisiert in Paperless-ngx importieren möchtest (z. B. aus Nextcloud oder E-Mail-Anhängen),  
> kannst du später n8n oder Cronjobs nutzen, um Dateien direkt ins `consume`-Verzeichnis zu kopieren.

👉 **Screenshot geeignet:** Dateimanageransicht der Ordnerstruktur unter `/opt/paperless` mit markierten Hauptverzeichnissen

### Schritt 11 – Benutzerverwaltung und Zugriffsrechte

Paperless-ngx unterstützt mehrere Benutzerkonten, ideal wenn du das UCC gemeinsam nutzt oder getrennte Bereiche für Streaming, Verwaltung und Privatdokumente anlegen willst.

#### Benutzer anlegen

Melde dich als Administrator in der Weboberfläche an und öffne oben rechts das **Benutzermenü → Administration**.  
Wähle dort **Users** und klicke auf **Add User**.

Trage die gewünschten Daten ein:
- **Username:** Kurzname des Benutzers  
- **Password:** sicheres Kennwort  
- **Staff status:** aktivieren, falls der Benutzer Zugriff auf die Administrationsoberfläche haben soll  
- **Superuser status:** nur aktivieren, wenn volle Rechte benötigt werden

> [!NOTE]  
> Normale Benutzer können Dokumente hochladen, Tags anlegen und suchen.  
> Nur Superuser dürfen Systemeinstellungen, OCR-Optionen und API-Schlüssel verwalten.

#### Gruppen und Berechtigungen

Über den Menüpunkt **Groups** lassen sich gemeinsame Rechte definieren.  
Das ist nützlich, wenn du z. B. mehrere Benutzer mit identischem Zugriff auf bestimmte Dokumentensammlungen brauchst.

Beispiel:
- Gruppe **Finanzen** → Zugriff auf alle Dokumente mit Tag „Rechnung“  
- Gruppe **Streaming** → Zugriff auf Produktionsunterlagen und Verträge

> [!TIP]  
> Gruppenrechte können jederzeit erweitert oder eingeschränkt werden, ohne einzelne Benutzerkonten anzupassen.  
> So bleibt dein UCC auch bei wachsenden Teams übersichtlich und sicher.

👉 **Screenshot geeignet:** Paperless-Adminbereich mit geöffneter Benutzerliste und markiertem Button „Add User“

### Schritt 12 – Such- und Filterfunktionen nutzen

Sobald erste Dokumente importiert und verarbeitet sind, kannst du die Suchfunktion von Paperless-ngx einsetzen.  
Sie basiert auf einem Volltextindex und ist extrem schnell – ideal, um Rechnungen, Verträge oder Seriennummern in Sekunden zu finden.

#### Freitextsuche

Oben im Dashboard findest du das zentrale Suchfeld.  
Hier kannst du Begriffe, Namen, Datumsangaben oder Schlagwörter eingeben.  
Paperless durchsucht automatisch den OCR-Text, Dateinamen, Tags und Notizen.

Beispiele:
```
Stromrechnung
Vertrag 2023
Amazon
```

> [!NOTE]  
> Die Suche ist **nicht case-sensitive** und erkennt auch Wortfragmente.  
> Eine Eingabe wie „rechn“ findet z. B. alle Dokumente mit dem Wort „Rechnung“.

#### Filterleiste

Links im Dashboard steht eine Filterleiste für gezieltere Abfragen.  
Hier kannst du kombinieren nach:
- Tag (z. B. „Steuer“, „Privat“, „Versicherung“)  
- Korrespondenzpartner  
- Datum (Upload oder Dokumentendatum)  
- Dateityp  

Mehrere Filter lassen sich beliebig kombinieren.  
So kannst du z. B. alle Dokumente von *Telekom* aus dem Jahr *2024* anzeigen lassen.

> [!TIP]  
> Wenn du regelmäßig dieselben Filter nutzt, kannst du gespeicherte Ansichten anlegen.  
> Diese erscheinen in der Seitenleiste und lassen sich mit einem Klick öffnen.

👉 **Screenshot geeignet:** Browseransicht mit aktivem Filter (Tag + Jahr) und angezeigter Trefferliste

### Schritt 13 – Backups und Datensicherung

Damit deine Dokumente und Metadaten dauerhaft erhalten bleiben, solltest du regelmäßige Backups einplanen.  
Paperless-ngx speichert alle wichtigen Daten lokal im Container – ideal für automatisierte Sicherungen über Kopia oder ein zentrales Backup-System.

#### Relevante Pfade

| Pfad | Inhalt | Sicherung notwendig |
|------|---------|--------------------|
| `/opt/paperless/data/` | Datenbank und Konfiguration | ✅ |
| `/opt/paperless/media/` | OCR-verarbeitete Dokumente | ✅ |
| `/opt/paperless/export/` | optionale Exporte | optional |
| `/opt/paperless/.env` | Umgebungsvariablen (wichtige Schlüssel) | ✅ |

> [!NOTE]  
> Das Verzeichnis `/opt/paperless/consume` muss **nicht** gesichert werden.  
> Es dient nur als temporärer Eingang und wird automatisch geleert, sobald Dokumente verarbeitet sind.

#### Beispiel-Backup mit tar

```bash
tar -czf /srv/backup/paperless-$(date +%F).tar.gz /opt/paperless/data /opt/paperless/media /opt/paperless/.env
```

Dieser Befehl erstellt ein komprimiertes Backup mit Datumsangabe.  
Die Datei kann anschließend automatisiert in Kopia, Nextcloud oder ein externes NAS übertragen werden.

> [!TIP]  
> Im UCC bietet sich an, das Paperless-Backup direkt in den zentralen Kopia-Container einzubinden.  
> So läuft die Sicherung zusammen mit Nextcloud und Vaultwarden nach demselben Plan.

👉 **Screenshot geeignet:** Terminalausgabe nach erfolgreicher Archiv-Erstellung (`paperless-YYYY-MM-DD.tar.gz` sichtbar)

### Schritt 14 – Systemprüfung und Wartung

Nach der vollständigen Einrichtung sollte das System einmal überprüft werden, um sicherzustellen, dass alle Komponenten korrekt laufen und dauerhaft stabil bleiben.

#### Dienststatus prüfen

```bash
systemctl status paperless
systemctl status redis-server
```

Beide Dienste sollten mit **active (running)** angezeigt werden.  
Wenn einer davon nicht läuft, starte ihn neu:

```bash
systemctl restart paperless
systemctl restart redis-server
```

> [!NOTE]  
> Redis ist essenziell für Hintergrundaufgaben und OCR-Verarbeitung.  
> Läuft dieser Dienst nicht, werden keine neuen Dokumente erkannt oder verarbeitet.

#### Logdateien kontrollieren

Paperless legt seine Logdateien im Datenverzeichnis ab.  
Eine schnelle Kontrolle auf Fehler ist mit folgendem Befehl möglich:

```bash
tail -n 50 /opt/paperless/data/logs/paperless.log
```

> [!TIP]  
> Fehlermeldungen zu „OCR timeout“ oder „Redis connection“ deuten auf zu geringe Systemressourcen oder Netzwerkprobleme hin.  
> In diesem Fall hilft meist ein Neustart oder eine moderate Erhöhung der CPU-Zuteilung.

#### Updates durchführen

Aktualisiere Paperless-ngx regelmäßig, um Sicherheits- und Funktionsupdates einzuspielen:

```bash
su - paperless
cd /opt/paperless
source venv/bin/activate
pip install --upgrade paperless-ngx
systemctl restart paperless
```

👉 **Screenshot geeignet:** Terminal mit Ausgabe von `pip install --upgrade paperless-ngx` (neue Version installiert)

---

## Troubleshooting & Tipps

Auch wenn Paperless-ngx im Alltag stabil läuft, können während Installation oder Betrieb gelegentlich Fehler auftreten.  
Die folgenden Punkte helfen, typische Probleme schnell einzugrenzen und zu beheben.

👉 **Screenshot geeignet:** Übersicht im UCC-Dashboard mit markiertem Paperless-Container

### Problem: Weboberfläche nicht erreichbar

**Symptome:**  
Die Seite `https://paperless.deinedomain.tld` lädt nicht oder zeigt einen Proxy-Fehler.

**Lösungen:**
1. Prüfe, ob der Container aktiv ist:  
   ```bash
   pct status <CTID>
   ```
   Wenn „stopped“ →  
   ```bash
   pct start <CTID>
   ```
2. Überprüfe den Dienststatus:  
   ```bash
   systemctl status paperless
   ```
   Sollte „inactive“ oder „failed“ angezeigt werden, starte ihn neu:  
   ```bash
   systemctl restart paperless
   ```
3. Kontrolliere den Nginx Proxy Manager-Eintrag.  
   IP-Adresse, Port (8000) und SSL-Zertifikat müssen korrekt hinterlegt sein.

> [!TIP]  
> Nach Änderungen am Proxy-Host kann es bis zu einer Minute dauern, bis die SSL-Konfiguration aktiv wird.

👉 **Screenshot geeignet:** NPM-Dashboard mit aktivem Proxy-Host `paperless.deinedomain.tld`

### Problem: OCR-Verarbeitung startet nicht

**Symptome:**  
Dokumente erscheinen im Dashboard, aber der Text wird nicht erkannt.

**Lösungen:**
1. Prüfe, ob der Redis-Dienst läuft:  
   ```bash
   systemctl status redis-server
   ```
   Falls nicht aktiv → starten:  
   ```bash
   systemctl restart redis-server
   ```
2. Stelle sicher, dass das OCR-Paket installiert ist:  
   ```bash
   apt install tesseract-ocr tesseract-ocr-deu -y
   ```
3. In der `.env`-Datei prüfen, ob `PAPERLESS_OCR_LANGUAGE=deu` gesetzt ist.  
   Änderungen übernehmen durch Neustart:
   ```bash
   systemctl restart paperless
   ```

> [!NOTE]  
> Bei sehr großen PDFs kann die Verarbeitung einige Minuten dauern.  
> Währenddessen bleibt der Status auf „pending“.

👉 **Screenshot geeignet:** Paperless-Taskliste mit sichtbarer OCR-Warteschlange

### Problem: Keine neuen Dokumente im Dashboard

**Symptome:**  
Dateien werden in das `consume`-Verzeichnis kopiert, erscheinen aber nicht in der Weboberfläche.

**Lösungen:**
1. Prüfe, ob das Verzeichnis korrekt angegeben und erreichbar ist:  
   ```bash
   grep CONSUMPTION_DIR /opt/paperless/.env
   ```
   Der Pfad muss exakt auf `/opt/paperless/consume` zeigen.
2. Kontrolliere die Dateiberechtigungen:  
   ```bash
   ls -l /opt/paperless/consume
   ```
   Eigentümer und Gruppe müssen **paperless** sein.  
   Falls nicht:
   ```bash
   chown -R paperless:paperless /opt/paperless/consume
   ```
3. Prüfe das Log auf Importfehler:  
   ```bash
   tail -n 50 /opt/paperless/data/logs/paperless.log
   ```
   Häufige Ursachen sind defekte PDF-Dateien oder fehlerhafte OCR-Einstellungen.

> [!TIP]  
> Wenn du Dokumente automatisiert über ein Skript einfügst, achte darauf, dass sie mit Schreibrechten für den Benutzer *paperless* kopiert werden.

👉 **Screenshot geeignet:** Terminalansicht mit korrektem Eigentümer (`paperless`) für alle Dateien im `consume`-Ordner


### Problem: Speicherplatz läuft voll

**Symptome:**  
OCR-Prozesse stoppen, der Container reagiert träge oder das Dashboard zeigt Fehler bei Uploads.

**Lösungen:**
1. Speicherbelegung prüfen:  
   ```bash
   df -h
   ```
   Wenn `/opt/paperless` zu mehr als 90 % belegt ist, alte oder doppelte Dateien prüfen.
2. Temporäre Caches löschen:  
   ```bash
   rm -rf /opt/paperless/data/cache/*
   ```
3. Falls regelmäßig große Dokumentenmengen anfallen, Storage vergrößern:  
   ```bash
   pct resize <CTID> rootfs +10G
   ```

> [!NOTE]  
> Paperless speichert Originale und OCR-Versionen separat.  
> Wer Platz sparen möchte, kann die Originale nach erfolgreicher Verarbeitung in regelmäßigen Abständen exportieren und extern archivieren.

👉 **Screenshot geeignet:** Terminalausgabe von `df -h` mit markiertem Paperless-LXC

### Problem: Login oder Passwort vergessen

**Symptome:**  
Kein Zugriff mehr auf das Administrator-Konto in der Weboberfläche.

**Lösungen:**
1. Anmelden im Container als Benutzer *paperless*:
   ```bash
   su - paperless
   cd /opt/paperless
   source venv/bin/activate
   ```
2. Neues Passwort für den vorhandenen Benutzer setzen:
   ```bash
   paperless-ngx changepassword <BENUTZERNAME>
   ```
   oder bei verlorenem Benutzerkonto ein neues Superuser-Konto erstellen:
   ```bash
   paperless-ngx createsuperuser
   ```
3. Anschließend den Dienst neu starten:
   ```bash
   systemctl restart paperless
   ```

> [!TIP]  
> Wenn mehrere Administratoren aktiv sind, kann jeder Superuser Passwörter anderer Nutzer zurücksetzen.  
> Bei Einzelbetrieb ist der Weg über `createsuperuser` der schnellste.

👉 **Screenshot geeignet:** Terminalausgabe nach erfolgreichem Passwort-Reset (`Password changed successfully` sichtbar)


### Problem: Paperless startet nicht nach Update

**Symptome:**  
Nach einem Upgrade bleibt der Dienst beim Start hängen oder bricht mit Fehlern ab.

**Lösungen:**
1. Logdateien prüfen:
   ```bash
   journalctl -u paperless -n 50
   ```
   oder
   ```bash
   tail -n 50 /opt/paperless/data/logs/paperless.log
   ```
2. Wenn der Fehler auf Datenbankmigrationen hinweist:
   ```bash
   su - paperless
   cd /opt/paperless
   source venv/bin/activate
   paperless-ngx migrate
   systemctl restart paperless
   ```
3. Bei Abhängigkeitskonflikten virtuelle Umgebung neu erstellen:
   ```bash
   rm -rf /opt/paperless/venv
   python3 -m venv /opt/paperless/venv
   source /opt/paperless/venv/bin/activate
   pip install --upgrade pip wheel
   pip install paperless-ngx
   systemctl restart paperless
   ```

> [!NOTE]  
> Nach größeren Versionssprüngen von Paperless-ngx sind Migrationen normal.  
> Ein manueller Datenbankabgleich löst die meisten Startprobleme.

👉 **Screenshot geeignet:** Terminalausgabe mit erfolgreicher Migration und aktivem Dienststatus

---

## Ergebnis

Nach Abschluss dieses Kapitels läuft Paperless-ngx als **vollständig integrierte Dokumentenverwaltung** im UCC.  
Alle wichtigen Dokumente werden automatisch erkannt, indiziert und zentral abgelegt – unabhängig von externen Cloud-Diensten.

Dein aktuelles Setup umfasst:

- **Paperless-ngx-Container** – für Dokumentenmanagement, OCR und Weboberfläche  
- **Redis-Server** – für Caching und Aufgabenverteilung  
- **Nginx Proxy Manager** – für sichere HTTPS-Bereitstellung über `https://paperless.deinedomain.tld`  
- **Automatische Struktur** für Eingang, Archiv und Export  
- **Integration** in das bestehende Backup-System (z. B. Kopia)

👉 **Screenshot geeignet:** Paperless-Dashboard mit sichtbaren Dokumenteinträgen, Tag-Leiste und aktivem Suchfeld

Damit bietet dein UCC nun:
- eine durchsuchbare Ablage für Rechnungen, Verträge und Unterlagen,  
- automatisierte Texterkennung (OCR) für PDF- und Bilddateien,  
- Mehrbenutzerfähigkeit mit differenzierten Berechtigungen,  
- und eine saubere Integration in das zentrale Kontrollsystem.

> [!TIP]  
> Wer weitergehen möchte, kann im **Premium-Kapitel** lernen, wie Paperless-ngx mit  
> **Nextcloud, n8n und automatisierten Importregeln** verbunden wird.  
> Damit lassen sich Dokumente direkt aus Cloud-Uploads oder E-Mails einlesen,  
> automatisch taggen und archivieren – ganz ohne manuelle Schritte.

Paperless-ngx erweitert das UCC um eine der wichtigsten Funktionen überhaupt:  
**digitale Souveränität über alle eigenen Dokumente** – sicher, automatisiert und vollständig unter deiner Kontrolle.