Kapitel 16/Free Rohtext.md hinzugefügt

2025-10-18 21:06:26 +00:00
parent 680a2e6f00
commit 4427985e8a
1 changed files with 864 additions and 0 deletions
--- a/Rohtext.md
+++ b/Rohtext.md
@@ -0,0 +1,864 @@
 # 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.