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

32 KiB
Raw Permalink Blame History

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:

    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:

apt update && apt upgrade -y

Nach Abschluss des Updates den Container neu starten:

reboot

Melde dich nach dem Neustart erneut an:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

systemctl daemon-reload
systemctl enable paperless
systemctl start paperless

Prüfe, ob alles läuft:

systemctl status paperless

Die Ausgabe sollte active (running) anzeigen.

Tip

Wenn du Paperless später updatest, genügt ein einfacher Neustart des Dienstes:

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:

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

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

systemctl status paperless
systemctl status redis-server

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

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:

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:

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: 
    pct status <CTID>
    Wenn „stopped“ → 
    pct start <CTID>
  2. Überprüfe den Dienststatus: 
    systemctl status paperless
    Sollte „inactive“ oder „failed“ angezeigt werden, starte ihn neu: 
    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: 
    systemctl status redis-server
    Falls nicht aktiv → starten: 
    systemctl restart redis-server
  2. Stelle sicher, dass das OCR-Paket installiert ist: 
    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: 
    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: 
    grep CONSUMPTION_DIR /opt/paperless/.env
    Der Pfad muss exakt auf /opt/paperless/consume zeigen.
  2. Kontrolliere die Dateiberechtigungen: 
    ls -l /opt/paperless/consume
    Eigentümer und Gruppe müssen paperless sein.
    Falls nicht: 
    chown -R paperless:paperless /opt/paperless/consume
  3. Prüfe das Log auf Importfehler: 
    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: 
    df -h
    Wenn /opt/paperless zu mehr als 90 % belegt ist, alte oder doppelte Dateien prüfen.
  2. Temporäre Caches löschen: 
    rm -rf /opt/paperless/data/cache/*
  3. Falls regelmäßig große Dokumentenmengen anfallen, Storage vergrößern: 
    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: 
    su - paperless
cd /opt/paperless
source venv/bin/activate
  2. Neues Passwort für den vorhandenen Benutzer setzen: 
    paperless-ngx changepassword <BENUTZERNAME>
    oder bei verlorenem Benutzerkonto ein neues Superuser-Konto erstellen: 
    paperless-ngx createsuperuser
  3. Anschließend den Dienst neu starten: 
    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: 
    journalctl -u paperless -n 50
    oder 
    tail -n 50 /opt/paperless/data/logs/paperless.log
  2. Wenn der Fehler auf Datenbankmigrationen hinweist: 
    su - paperless
cd /opt/paperless
source venv/bin/activate
paperless-ngx migrate
systemctl restart paperless
  3. Bei Abhängigkeitskonflikten virtuelle Umgebung neu erstellen: 
    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.