diff --git a/Kapitel 16/Free Rohtext.md b/Kapitel 16/Free Rohtext.md new file mode 100644 index 0000000..a8ca4df --- /dev/null +++ b/Kapitel 16/Free 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@ + ``` + Ersetze `` 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@ +``` + +> [!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://: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://: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** | `` | +| **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 + ``` + Wenn „stopped“ → + ```bash + pct start + ``` +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 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 + ``` + 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. \ No newline at end of file