Paperless-ngx mit Docker: Effizientes Dokumentenmanagement

Uncategorized

Paperless-ngx mit Docker: Der Weg zum schlanken Dokumentenmanagement

Wer heute noch über Papierstapel stolpert oder PDFs in Ordnerstrukturen verliert, die an Labyrinthe erinnern, hat ein betriebswirtschaftliches und technisches Problem. Die Lösung heißt nicht „mehr Ordner“, sondern „bessere Systematik“. Hier setzt Paperless-ngx an – eine Open-Source-Dokumentenmanagement-Lösung (DMS), die sich speziell für den schlanken, digitalen Workflow optimiert hat. Und mit Docker wird die Einrichtung zum kontrollierbaren Prozess statt zum Installationsmarathon.

Warum Paperless-ngx? Mehr als nur ein PDF-Grab

Paperless-ngx ist kein Zufallsprodukt. Es entstand als Fork des ursprünglichen Paperless-ng, als dessen Entwicklung ins Stocken geriet. Die Community griff ein, und das Ergebnis ist eine ausgereifte Plattform, die sich auf das Wesentliche konzentriert: Dokumente zuverlässig erfassen, durchsuchbar machen, intelligent organisieren und langfristig archivieren. Der Fokus liegt bewusst auf Einfachheit und Effizienz – kein überladenes Enterprise-DMS mit monatelanger Einführungsphase.

Das Herzstück? Die automatische Texterkennung (OCR) mittels Tesseract. Paperless-ngx durchsucht nicht nur Dateinamen, sondern den gesamten Inhalt Ihrer PDFs, Bilder oder Office-Dokumente. Kombiniert mit einem ausgeklügelten Tagging-System und der Möglichkeit, Dokumententypen (Rechnungen, Verträge, Garantiescheine) mit eigenen Verarbeitungsregeln zu definieren, entsteht eine Suchmaschine für Ihr Papiergedächtnis. Ein interessanter Aspekt: Die intelligente Datumserkennung extrahiert automatisch Fälligkeitstermine aus Rechnungen und zeigt sie im Dashboard an – eine kleine, aber betrieblich wertvolle Funktion.

Docker: Der Türöffner für robusten Betrieb

Warum Docker? Die Antwort liegt in der Natur moderner Software. Paperless-ngx besteht aus mehreren Komponenten: Ein Python-basierter Webapplikations-Server (meist Gunicorn), ein PostgreSQL-Datenbankcontainer für die Metadaten, Redis für Warteschlangen (etwa OCR-Jobs) und optional ein Webserver wie Nginx als Reverse-Proxy. Manuell zu installieren, ist ein fehleranfälliges Unterfangen mit Abhängigkeitskonflikten. Docker containerisiert jede Komponente. Jeder Container läuft in seiner isolierten Umgebung mit exakt den benötigten Bibliotheken und Versionen.

Die Vorteile sind handfest:

  • Reproduzierbarkeit: Die gleiche Konfiguration läuft auf Entwickler-Laptop, Testserver und Produktivsystem.
  • Isolation: Probleme in Paperless-ngx gefährden nicht das Hostsystem oder andere Anwendungen.
  • Updates ohne Drama: Ein neues Image wird gepullt, der alte Container gestoppt, der neue gestartet – oft binnen Sekunden.
  • Ressourcenkontrolle: Speicher- und CPU-Limits pro Container verhindern, dass ein OCR-Job das ganze System ausbremst.
  • Portabilität: Migration auf neue Hardware? Einfach die Docker-Volumes verschieben und neu starten.

Dabei zeigt sich: Gerade für eine Anwendung wie Paperless-ngx, die Langfristigkeit und Verlässlichkeit bei der Dokumentenarchivierung garantieren muss, ist diese Container-Isolation kein Spielzeug, sondern betriebliche Notwendigkeit.

Vor dem Start: Das braucht Ihr System

Die Hardware-Anforderungen sind moderat, aber nicht trivial. Entscheidend ist die Art des Datenaufkommens:

  • CPU: OCR frisst Rechenzeit. Ein moderner Multi-Core-Prozessor (4 Kerne+) beschleunigt die Verarbeitung massiv, besonders bei hohem Dokumentenaufkommen oder hochauflösenden Scans.
  • RAM: 4 GB sind absolutes Minimum. 8 GB oder mehr sind empfehlenswert, besonders wenn PostgreSQL und Tesseract parallel arbeiten.
  • Speicher: Hier wird’s individuell. Kalkulieren Sie das Volumen Ihrer zu erfassenden Dokumente plus jährliches Wachstum. Bedenken Sie: Paperless speichert Originale und durchsuchbare PDFs (Archive + Textlayer). Ein RAID oder ZFS mit Snapshots bietet Sicherheit.
  • OS: Linux-Distributionen wie Debian, Ubuntu oder CentOS sind erste Wahl. Docker läuft auch auf Windows/macOS, aber für den Produktivbetrieb ist Linux stabiler und ressourcenschonender.

Software-Grundvoraussetzung ist eine aktuelle Docker-Engine (Version 20.10.7+) und Docker Compose (Version 1.29.2+). Die Installation dieser Tools ist distrospezifisch – die offizielle Docker-Dokumentation ist hier wegweisend. Ein Tipp: Vermeiden Sie ältere Distributionen mit veralteten Kernel-Versionen; sie können zu Inkompatibilitäten mit neueren Docker-Features führen.

Installation: Der docker-compose.yml als Drehbuch

Der Königsweg zur Paperless-ngx-Installation führt über Docker Compose. Eine einzige YAML-Datei (docker-compose.yml) definiert alle Container, ihre Beziehungen, Umgebungsvariablen und Speicherorte. Das ist übersichtlicher als manuelle docker run-Befehle mit ellenlangen Parameterlisten.

Starten wir mit einer Basis-Konfiguration. Erstellen Sie ein Verzeichnis (z.B. ~/paperless) und darin die docker-compose.yml:

version: "3.8"
services:
  broker:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: postgres:15
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=paperless
      - POSTGRES_USER=paperless
      - POSTGRES_PASSWORD=mein_sicheres_passwort  # Ändern!

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"  # Host-Port : Container-Port
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume  # Der "Eingangskorb"
    environment:
      - PAPERLESS_REDIS=redis://broker:6379
      - PAPERLESS_DBHOST=db
      - PAPERLESS_DBNAME=paperless
      - PAPERLESS_DBUSER=paperless
      - PAPERLESS_DBPASS=mein_sicheres_passwort  # Muss zum DB-Service passen!
      - PAPERLESS_SECRET_KEY=ein_langer_zufälliger_string  # Für Sicherheit, z.B. mit `openssl rand -base64 48` generieren
      - PAPERLESS_OCR_LANGUAGE=deu+eng  # Deutsch + Englisch für OCR
      - USERMAP_UID=1000  # User-ID des Host-Users für Dateiberechtigungen
      - USERMAP_GID=1000  # Group-ID des Host-Users

volumes:
  redisdata:
  pgdata:
  data:
  media:

Was passiert hier?

  1. broker: Redis-Container für Aufgaben-Warteschlangen (z.B. OCR-Jobs).
  2. db: PostgreSQL-Datenbankcontainer – das Gehirn für Metadaten (Tags, Typen, Korrespondenten) und Suchindexe.
  3. webserver: Der eigentliche Paperless-ngx Container. Er hängt an db und broker. Port 8000 wird auf den Host exponiert.
  4. Volumes: redisdata und pgdata persistieren die Redis-Daten bzw. die PostgreSQL-Datenbank. data speichert Konfiguration und Indexe von Paperless. media ist das Herz: Hier liegen die Originaldokumente und die archivierten PDFs. Die ./export und ./consume-Ordner auf dem Host sind für Exporte bzw. den automatischen Import neuer Dokumente gedacht.
  5. Umgebungsvariablen: Sie steuern die Konfiguration. Besonders wichtig: Datenbank-Zugang, der SECRET_KEY (für Session-Verschlüsselung!) und die OCR_LANGUAGE. Die USERMAP_UID/GID stellen sicher, dass Dateien im consume-Ordner mit den richtigen Berechtigungen verarbeitet werden.

Starten Sie das Ganze mit:

docker compose up -d

Nach dem ersten Pull der Images (kann einige Minuten dauern) ist Paperless-ngx unter http://<IhreServerIP>:8000 erreichbar. Die Oberfläche ist klar: Links die Navigation, in der Mitte das Dashboard mit aktuellen Dokumenten und Aufgaben. Der erste Login erfolgt mit Benutzername admin und Passwort admin – ändern Sie das Passwort sofort unter Einstellungen > Benutzer!

Die Konsumierer: Dokumente automatisch einspeisen

Der consume-Ordner ist das Einfallstor. Legen Sie hier eine PDF, JPG, PNG oder sogar EML (E-Mail)-Datei ab, und Paperless-ngx beginnt automatisch mit der Verarbeitung:

  1. Dateierfassung: Der Dateiinhalt wird in das media-Volume kopiert.
  2. OCR: Tesseract extrahiert den Text und fügt ihn bei Bildern/PDFs ohne Textlayer als durchsuchbare Ebene ein.
  3. Metadaten-Extraktion: Paperless versucht, Korrespondent (Absender), Dokumententyp, Datum und Tags aus dem Inhalt oder Dateinamen abzuleiten.
  4. Speicherung & Indexierung: Das verarbeitete Dokument und seine Metadaten landen in der Datenbank und werden für die Suche indexiert.

In der Praxis nutzt man dafür oft:

  • E-Mail-Postfächer: Tools wie fetchmail oder getmail holen E-Mails ab, extrahieren Anhänge und legen sie in consume.
  • Netzwerk-Scanner: Viele Scanner können direkt in einen Netzwerkordner (SMB/FTP) scannen. Mounten Sie consume als solchen Ordner.
  • Mobile Apps: Es gibt Apps, die Fotos von Belegen machen und direkt an Paperless-ngx senden können (oft über die API).

Ein häufiger Stolperstein sind Dateiberechtigungen im consume-Ordner. Stellen Sie sicher, dass der Benutzer oder Dienst, der Dateien ablegt (z.B. der Scanner-Dienst), Schreibrechte hat und die USERMAP_UID/GID in der Compose-Datei zur User-ID/Gruppe-ID dieses Benutzers/Dienstes passen.

Organisation ist alles: Korrespondenten, Typen, Tags & Regeln

Die wahre Stärke von Paperless-ngx entfaltet sich erst mit einer durchdachten Taxonomie. Unorganisiert importierte Dokumente sind schnell wieder unauffindbar. Nutzen Sie:

  • Korrespondenten: Wer hat das Dokument geschickt? (Firmen, Behörden, Personen). Einmal angelegt, kann Paperless neue Dokumente vom selben Absender automatisch zuordnen.
  • Dokumententypen: Was ist es? (Rechnung, Vertrag, Kontoauszug, Garantie, Bedienungsanleitung). Typen können eigene Verarbeitungsregeln auslösen.
  • Tags: Flexible Kategorien (z.B. „Steuerrelevant“, „Projekt Alpha“, „Erledigt“, „Archiv“). Ein Dokument kann mehrere Tags haben.
  • Ablagekörbe: Logische Gruppen für Dokumente, die zusammengehören (z.B. „Mietvertrag Wohnung Hauptstraße“).

Der Clou sind Automatisierungsketten (Matching-Algorithmen). Sie definieren Regeln wie:

WENN (Korrespondent enthält "Stadtwerke" ODER Betreff enthält "Stromrechnung")
UND Dokumententyp ist "Rechnung"
DANN weise Tag "Energiekosten" zu
UND lege Dokument in Ablagekorb "Haushalt/Strom".

Diese Regeln werden bei jedem Import oder manuell ausgelöst auf bestehende Dokumente angewendet. Investieren Sie Zeit in deren Pflege – sie automatisieren den Großteil der Sortierarbeit. Ein interessanter Aspekt: Sie können Regeln auch basierend auf dem Inhalt definieren (z.B. „WENN Text enthält ‚MwSt. 19%'“).

Feintuning: Umgebungsvariablen als Schaltstellen

Die Standard-docker-compose.yml ist nur der Anfang. Paperless-ngx bietet Dutzende Umgebungsvariablen zur Konfiguration. Wichtige Kandidaten:

  • PAPERLESS_OCR_LANGUAGE: Standard ist eng. Für deutschsprachige Dokumente: deu+eng (verbessert Erkennung bei gemischtsprachigen Texten).
  • PAPERLESS_OCR_PAGES: Bei großen PDFs: Wie viele Seiten sollen pro OCR-Job verarbeitet werden? (Standard 10). Anpassung kann Performance bei schwacher CPU verbessern.
  • PAPERLESS_TIME_ZONE: Wichtig für korrekte Datumsanzeige (z.B. Europe/Berlin).
  • PAPERLESS_URL: Die Basis-URL, unter der Paperless erreichbar ist (z.B. https://dokumente.meinefirma.de). Essenziell für korrekte Links in E-Mail-Benachrichtigungen.
  • PAPERLESS_FILENAME_FORMAT: Wie sollen archivierte Dateien benannt werden? Standard ist {correspondent}/{title}. Möglich sind Platzhalter wie {created_year}, {document_type} usw. Beispiel: {created_year}/{created_month}/{correspondent}_{title} erzeugt eine jahres- und monatsbasierte Ordnerstruktur.
  • PAPERLESS_CONSUMER_POLLING: Wie oft (in Sekunden) prüft Paperless den consume-Ordner auf neue Dateien? Standard 10s. Bei hohem Aufkommen ggf. reduzieren.

Diese Variablen fügen Sie einfach unter environment: im webserver-Service Ihrer Compose-Datei hinzu. Nach einem docker compose up -d werden die Änderungen aktiv. Die komplette Liste findet sich im offiziellen Paperless-ngx Config-Dokumentation.

Betriebssicherheit: Updates, Backups & Monitoring

Ein laufendes DMS ist kein „Set-and-Forget“-System. Glücklicherweise macht Docker Wartung einfach:

Updates: Paperless-ngx entwickelt sich schnell. Um auf die neueste Version zu wechseln:

docker compose pull  # Holt die neuesten Images
docker compose down  # Stoppt die Container
docker compose up -d # Startet mit neuen Images neu

Testen Sie größere Updates zunächst in einer Staging-Umgebung! Prüfen Sie vorher die Release Notes auf breaking changes.

Backups: Ihre Dokumente sind wertvoll. Ein Backup-Strategie ist Pflicht. Fokussieren Sie auf:

  1. Daten-Volumes: Das media-Volume enthält Ihre Originale und archivierten PDFs. Das data-Volume Konfig und den Suchindex. Das pgdata-Volume die PostgreSQL-Datenbank.
  2. Datenbank-Dump: Zusätzlich zum Volume-Backup: Regelmäßige PostgreSQL-Dumps bieten eine Ebene der Sicherheit.

Ein einfaches Backup-Skript könnte so aussehen:

#!/bin/bash
# Stoppe Paperless (optional, sicherer für DB-Dump)
docker compose stop

# Backup der Docker-Volumes (z.B. mit rsync oder `docker volume backup`-Tool)
rsync -av /var/lib/docker/volumes/paperless_pgdata /backup/volumes/
rsync -av /var/lib/docker/volumes/paperless_media /backup/volumes/
...

# PostgreSQL-Dump
docker compose exec -T db pg_dump -U paperless paperless > /backup/dumps/paperless_$(date +%Y%m%d).sql

# Starte Paperless wieder
docker compose start

Monitoring: Behalten Sie die Gesundheit im Blick:

  • Docker selbst: docker compose ps zeigt Status der Container. docker compose logs -f zeigt Logs in Echtzeit (gut für Fehlersuche).
  • Systemressourcen: Tools wie htop, docker stats oder Prometheus/Grafana für CPU, RAM, Disk-I/O.
  • Paperless-ngx intern: Das Dashboard zeigt anstehende Aufgaben und Fehler. Die Logs (docker compose logs webserver) sind detailliert.

Ein häufiges Problem: Der OCR-Prozess bleibt hängen. Oft liegt es an defekten PDFs oder Bildern. Prüfen Sie die Logs, isolieren Sie das Dokument und versuchen Sie ggf. eine manuelle Konvertierung vor dem erneuten Import.

Jenseits der Basis: Erweiterungen und Integration

Das Paperless-ngx-Ökosystem bietet Spielraum:

  • Reverse Proxy (Nginx/Apache): Für Produktivbetrieb sollte Paperless nicht direkt auf Port 8000 exponiert sein. Ein Reverse Proxy vor Paperless-ngx (im eigenen Container oder auf dem Host) übernimmt SSL/TLS-Terminierung (HTTPS!), Zugriffsbeschränkungen und Load-Balancing. Eine einfache Nginx-Konfiguration im separaten Container ist schnell eingerichtet.
  • Single Sign-On (SSO): Über OAuth2 oder REMOTE_USER-Authentifizierung lässt sich Paperless in bestehende Identity Provider (Keycloak, Authelia, LDAP/Active Directory) integrieren. Praktisch für Unternehmen.
  • API: Paperless-ngx bietet eine REST-API. Damit lassen sich Dokumente suchen, hochladen, bearbeiten oder externe Workflows anstoßen (z.B. Rechnungsdaten in Buchhaltungssoftware übertragen).
  • Alternative OCR-Engines: Tesseract ist solide, aber es gibt Alternativen wie OCRmyPDF mit speziellen Optimierungen. Der Wechsel erfordert Anpassungen im Paperless-Container (Custom Dockerfile).

Dabei zeigt sich die Stärke der Docker-Architektur: Jede Erweiterung lässt sich oft als eigener, entkoppelter Container realisieren.

Fazit: Digitale Souveränität statt Papierchaos

Paperless-ngx mit Docker zu betreiben, ist kein Selbstzweck, sondern eine pragmatische Antwort auf ein drängendes betriebliches Problem: den Verlust der Kontrolle über Informationen. Es ersetzt keine komplexen ECM-Systeme mit Workflow-Engines im Enterprise-Maßstab. Aber für KMUs, Heimanwender oder Fachabteilungen bietet es genau das richtige Maß an Funktionalität, Automatisierung und – dank Docker – Betriebssicherheit.

Der initiale Aufwand für die Docker-Einrichtung und die Definition der Taxonomie zahlt sich schnell aus. Die Zeit, die Mitarbeiter bisher mit Suchen verbracht haben, wandelt sich in produktive Zeit. Die Angst vor dem Steuerbesuch wegen einer nicht auffindbaren Belegschaft schwindet. Nicht zuletzt ist es ein Schritt hin zur digitalen Souveränität: Sie behalten die Hoheit über Ihre Daten – ohne Vendor-Lock-in bei Cloud-Anbietern.

Die Kombination aus Paperless-ngx und Docker ist kein Silberbullet. Sie erfordert Disziplin beim Scannen und Taggen. Aber sie funktioniert. Und sie bietet etwas, das in der heutigen Informationsflut unbezahlbar ist: Klarheit.