Paperless-ngx auf Ubuntu: Der pragmatische Weg zur digitalen Dokumentenverwaltung

Uncategorized

Paperless-ngx unter Ubuntu: Der pragmatische Weg zur digitalen Dokumentenfestung

Wer Dokumentenchaos mit Open Source meistern will, landet unweigerlich bei Paperless-ngx. Doch wie bringt man das System sauber auf Ubuntu zum Laufen? Eine Anleitung ohne Beschönigung.

Vom Aktenberg zur Suchmaschine: Warum Paperless-ngx?

Die Realität in vielen Büros gleicht noch immer einem Archivkrimi: Verträge verschwinden in Schrankmäulern, Rechnungen verstauben in Outlook-Ordnern, Belege wandern durch Ablagekörbe. Dabei ist die Lösung längst da – sie heißt nur nicht „Magisches Denken“. Paperless-ngx, der quelloffene Nachfolger von Paperless-ng, bietet eine durchdachte Architektur für Dokumentenerfassung, -klassifizierung und -retrieval. Das System kombiniert OCR, Tagging und eine durchdachte Suchlogik zu einem Werkzeug, das Papier tatsächlich überflüssig macht. Nicht als Hype, sondern als arbeitsalltagstaugliches Backend.

Für IT-Verantwortliche liegt der Reiz in der Docker-basierten Bereitstellung: Paperless-ngx läuft in Containern, kapselt seine Abhängigkeiten sauber und lässt sich mit Docker-Compose orchestrieren. Das macht Migrationen und Updates handhabbar – ein entscheidender Vorteil gegenüber monolithischen DMS-Lösungen. Wer schon mal eine ältere Document-Management-Software über drei Major-Versionen upgegradet hat, weiß warum.

Vor dem Start: Hardware und Ubuntu-Feintuning

Ubuntu LTS (22.04 oder 24.04) bildet das ideale Fundament. Doch Vorsicht: Ein Standard-Setup genügt nicht. Diese Punkte sind vor der Installation zu prüfen:

  • Dateisystem: Btrfs oder ZFS? Ideal für Snapshots! Ext4 geht auch, aber regelmäßige Backups sind dann Pflicht. Kein Experimentierfeld für /var/lib/docker!
  • RAM: 4 GB Minimum, 8 GB empfohlen – vor allem wenn OCR parallel läuft. Paperless‘ Tesseract-Engine ist hungrig.
  • CPU: Moderne Multi-Core-Prozessoren beschleunigen die Texterkennung spürbar. Ein Raspberry Pi 4 schafft das, aber bei Volllast wird’s ungemütlich.
  • Storage: SSD-Pflicht! HDDs ersticken im OCR-Dauerfeuer. Planen Sie mindestens 100 GB für den Einstieg ein – Dokumente wachsen wie Unkraut.
  • Netzwerk: Statische IP oder DNS-Eintrag nicht vergessen. Nichts ist lästiger als wechselnde IPs beim Reverse Proxy.

Ein oft übersehener Schritt: sudo apt update && sudo apt upgrade -y ausführen bevor man Docker installiert. Veraltete Kernel können beim AUFS-Treiber böse Überraschungen bereiten. Auch die Zeitzone sollte via timedatectl korrekt gesetzt sein – falsch interpretierte Zeitstempel in Dokumenten sind später schwer zu korrigieren.

Docker & Docker-Compose: Die Grundlagen schaffen

Ohne Container läuft nichts. Die Installation ist zwar dokumentiert, aber zwei Fallstricke erwarten Unvorbereitete:

sudo apt install apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

Jetzt den aktuellen Nutzer zur Docker-Gruppe hinzufügen (sudo usermod -aG docker $USER), abmelden und neu anmelden – sonst scheitert jeder Docker-Befehl mit Permission-Errors. Docker-Compose holt man sich separat:

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Testen Sie beides mit docker --version und docker-compose --version. Fehlermeldungen hier sind Warnzeichen – bitte nicht ignorieren!

Paperless-ngx: Deployment mit Fingerspitzengefühl

Die offizielle Dokumentation empfiehlt ein Git-Clone des Repositories. Praktisch, aber riskant: Man bindet sich an Entwicklungszweige. Besser ist ein eigener Ordner für Konfiguration:

mkdir ~/paperless
cd ~/paperless
curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/.env.example

Kopieren Sie nun .env.example zu .env – hier liegt der Schlüssel zur Konfiguration. Diese Variablen sind essenziell:

# Basis-Konfig
PAPERLESS_URL=http://meinserver:8000  # Später durch Domain ersetzen
PAPERLESS_SECRET_KEY=$(openssl rand -base64 48) # Nicht leer lassen!

# Datenbank
PAPERLESS_DBHOST=db
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=ein_sicheres_passwort # Ändern!

# OCR
PAPERLESS_OCR_LANGUAGE=deu+eng  # Deutsch + Englisch
PAPERLESS_OCR_MODE=redo # Dokumente bei Änderungen neu OCR-en

# Pfade (Host-Verzeichnisse anlegen!)
PAPERLESS_DATA=/usr/src/paperless/data
PAPERLESS_MEDIA=/usr/src/paperless/media
PAPERLESS_CONSUME=/usr/src/paperless/consume

Jetzt die Verzeichnisse auf dem Host anlegen und Berechtigungen setzen:

sudo mkdir -p /opt/paperless/{data,media,export,consume}
sudo chown -R 1000:1000 /opt/paperless

Warum 1000:1000? Der Paperless-Container läuft standardmäßig unter diesem User – sonst gibt’s Schreibrechtsprobleme. Passen Sie in docker-compose.yml die Volumes an:

services:
  broker:
    ...
  db:
    ...
  webserver:
    ...
    volumes:
      - /opt/paperless/data:/usr/src/paperless/data
      - /opt/paperless/media:/usr/src/paperless/media
      - /opt/paperless/export:/usr/src/paperless/export
      - /opt/paperless/consume:/usr/src/paperless/consume

Zündfunke: Erster Start und Web-Oberfläche

Mit docker-compose up -d starten die Container im Hintergrund. Logs verfolgt man mit docker-compose logs -f. Typische Starthürden:

  • DB-Connection-Fehler: Läuft die PostgreSQL? docker-compose ps zeigt’s. Oft ist eine falsche .env-Variable schuld.
  • Permission denied: Vergessen, die Host-Verzeichnisse mit chown zu versehen? Prüfen mit ls -ld /opt/paperless/*.
  • Port-Konflikte: Läuft schon etwas auf Port 8000? In docker-compose.yml unter „webserver“ den Port ändern (z.B. „8000:8000“ → „8080:8000“).

Nach erfolgreichem Start: Im Browser http://<server-ip>:8000 aufrufen. Es erscheint der Setup-Assistent:

  1. Admin-Benutzernamen und Passwort vergeben (nicht „admin/admin“!)
  2. Sprache auf Deutsch stellen
  3. Dokumentenklassen und Tags später anlegen – erstmal überspringen

Ein häufiges Missverständnis: Paperless ist nach dem ersten Login leer. Die eigentliche Arbeit beginnt jetzt erst.

Dokumentenimport: Mehrere Wege führen ins Archiv

Paperless bietet vier Importpfade – jeder mit eigenen Use Cases:

1. Der Consume-Ordner

Legt man ein PDF in /opt/paperless/consume, wird es automatisch importiert. Ideal für Skripte oder Dateimanager-Drag-and-Drop. Aber Vorsicht: Die Datei wird verschoben, nicht kopiert! Für Testläufe also immer mit Kopien arbeiten.

2. E-Mail-Postfach

Paperless kann IMAP-Postfächer abfragen. In der Admin-Oberfläche unter „Einstellungen → Mail-Account“ konfigurieren. Wichtig:

  • Separates Postfach nutzen (nicht das Hauptpostfach des Admins!)
  • „Nach Verarbeitung löschen“ aktivieren – sonst wächst das Postfach unkontrolliert
  • Regeln für automatische Klassifizierung nutzen (z.B. alle Mails von „rechnungen@lieferant.de“ als Typ „Rechnung“ taggen)

3. API-Zugriff

Die REST-API ermöglicht Integration in eigene Tools. Beispiel mit curl:

curl -X POST -H "Content-Type: multipart/form-data" -H "Authorization: Token IhrToken" -F "document=@rechnung.pdf" http://paperless/api/documents/post_document/

Der Token wird unter „Einstellungen → API“ generiert. Perfekt für Scanner-Skripte oder Drittsysteme.

4. Manueller Upload im Web-Interface

Der klassische Weg: Per Drag-and-Drop PDFs in den Browser ziehen. Praktisch für Ad-hoc-Dokumente, aber bei Massenimport unpraktisch.

Organisationskonzept: Wie Paperless Dokumente versteht

Der Kern von Paperless sind drei Ordnungsebenen:

  • Dokumententypen: Grobe Kategorien wie „Rechnung“, „Vertrag“, „Lieferschein“. Definiert, was ein Dokument ist.
  • Tags: Schlagwörter wie „Steuerrelevant“, „Archiv“, „Projekt X“. Beschreiben Eigenschaften.
  • Korrespondenten: Absender/Empfänger wie „Finanzamt“, „Lieferant Y“, „Kunde Z“.

Ein typisches Dokument könnte so klassifiziert sein:

Typ: Rechnung | Korrespondent: Bürobedarf GmbH | Tags: Steuerrelevant, Büromaterial, Bezahlt

Die wahre Stärke entfaltet Paperless durch Automatische Klassifizierung (AUTOIS). Nach einiger Trainingseingabe lernt das System:

  • Anhand von Absenderdomains Korrespondenten vorzuschlagen
  • Anhand von Schlüsselwörtern („Rechnung“, „Invoice“) den Dokumententyp zu erkennen
  • Tags zuzuordnen basierend auf Textmustern (z.B. „Steuernummer 123“ → Tag „Steuer“)

Ein Tipp: Nicht zu früh automatisieren! Erst 50-100 Dokumente manuell korrekt taggen – dann übernimmt AUTOIS zuverlässig.

Betriebssicherheit: Backup-Strategien und Updates

Ohne Backup kein Mitleid. Paperless speichert Metadaten in PostgreSQL, Dokumente und Indizes im Dateisystem. Ein vollständiges Backup umfasst:

  1. Datenbank-Dump: docker-compose exec db pg_dump -U paperless > paperless_db_backup.sql
  2. Dateisicherung von /opt/paperless (media, data, export)

Skripten Sie das! Beispiel-Cron-Job für nächtliches Backup:

0 2 * * * cd /opt/paperless && docker-compose exec -T db pg_dump -U paperless > /backup/paperless_db_$(date +\%Y\%m\%d).sql && rsync -av /opt/paperless /backup/

Updates sollten regelmäßig eingespielt werden. Vorgehen:

  1. Backup erstellen (siehe oben)
  2. Container stoppen: docker-compose down
  3. Images aktualisieren: docker-compose pull
  4. Datenbankmigration: docker-compose run --rm webserver migrate
  5. Statische Dateien aktualisieren: docker-compose run --rm webserver collectstatic
  6. Neustart: docker-compose up -d

Testen Sie Updates zunächst in einer Staging-Umgebung! Datenbankmigrationen sind meist reversibel, aber warum riskieren?

Sicherheit: Mehr als nur ein Login-Formular

Das Web-Interface ist die größte Angriffsfläche. Grundlegende Härtung:

  • Reverse Proxy: Nginx oder Apache vor Paperless setzen. Ermöglicht SSL, Rate Limiting und HTTP-Auth.
  • SSL: Let’s Encrypt via Certbot integrieren. Unverschlüsselte Dokumente? Ein No-Go.
  • Zwei-Faktor-Auth: In den Benutzereinstellungen aktivierbar. Besonders für Admins Pflicht.
  • Netzwerkisolation: Paperless im eigenen Docker-Netzwerk laufen lassen. Ports nur am Proxy exponieren.

In der .env nicht vergessen:

# Cross-Site-Request-Forgery-Schutz
PAPERLESS_CSRF_TRUSTED_ORIGINS=https://meine-domain.de

# Sicherheit durch Header
PAPERLESS_SECURE_SSL_REDIRECT=True
PAPERLESS_SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,https

Regelmäßige Audits mit docker-compose logs und docker scan (für Image-Schwachstellen) sollten selbstverständlich sein.

Betriebliche Integration: Vom Tool zur Routine

Technisch läuft Paperless? Glückwunsch – jetzt beginnt die eigentliche Herausforderung: Die Einbindung in Geschäftsprozesse. Erfahrungsgemäß scheitern DMS-Projekte an drei Stellen:

  1. Scan-Disziplin: Papierdokumente müssen sofort nach Eingang gescannt werden. Ein „Später“-Stapel wird zum Berg.
  2. Benennungskonventionen: Wie heißen die Dokumententypen? Wer vergibt Tags? Hierarchische Tags („Projekt.Abrechnung“) können helfen.
  3. Löschregeln: Nicht alles muss ewig bleiben. Aufbewahrungsfristen in Tags kodieren (z.B. „Loesch-2029“) und per Skript automatisch bereinigen.

Ein Praxis-Tipp: Starten Sie mit einer Pilotabteilung (z.B. Buchhaltung). Sammeln Sie Feedback, bevor Sie firmenweit rollen. Und: Benennen Sie Paperless-Botschafter in jeder Abteilung – sie sind die ersten Ansprechpartner bei Fragen.

Skalierung: Wenn aus Prototypen Ernst wird

Anfangs läuft Paperless auf minimaler Hardware. Doch was tun, wenn 10.000+ Dokumente die Performance killen?

  • Redis für Caching: In docker-compose.yml den Redis-Service aktivieren und in .env PAPERLESS_REDIS=redis://redis:6379 setzen. Beschleunigt Suchanfragen spürbar.
  • Separater OCR-Worker: Standardmäßig macht der Webserver OCR. Bei Last trennen: Extra worker-Service in docker-compose aktivieren und PAPERLESS_OCR_MODE=--queue setzen. Dann landet OCR in einer Warteschlange.
  • Database Tuning: PostgreSQL-Parameter anpassen (shared_buffers, work_mem). Tools wie pgTune helfen bei der Konfiguration.
  • Storage-Entkopplung: Media-Ordner auf schnelles NAS oder Object Storage (S3 kompatibel) auslagern. Paperless unterstützt S3 über PAPERLESS_STORAGE_BACKEND=s3.

Bei extremen Mengen: Überlegen Sie, ältere Dokumente zu exportieren („Cold Storage“). Paperless kann Dokumente als verschlüsselte ZIPs exportieren und aus dem Live-System entfernen – bei Bedarf reimportieren.

Fazit: Keine Zauberei, aber ein Quantensprung

Paperless-ngx ist kein Allheilmittel gegen Dokumentenchaos. Es braucht Disziplin bei der Erfassung und Klassifizierung. Die Ubuntu-Installation erfordert Linux-Grundwissen – besonders bei Docker und Netzwerkkonfiguration.

Doch der Aufwand lohnt: Wer Paperless einmal mit lebenden Dokumenten gefüttert hat, wird Suchfunktionen wie „Rechnung Lieferant X zwischen 300€ und 500€ vom letzten Quartal“ nicht mehr missen wollen. Die Kombination aus OCR, durchdachter Taxonomie und Offenlegung aller Komponenten macht es zum idealen Werkzeug für Organisationen, die Unabhängigkeit von Herstellerbindung schätzen.

Ein letzter Rat: Starten Sie klein. Ein Docker-Compose-File und ein Ubuntu-Server sind schnell aufgesetzt. Aber der wahre Erfolg liegt im betrieblichen Wandel – von der Papierablage zur durchsuchbaren Wissensdatenbank. Das braucht Zeit. Und genau dafür bietet Paperless-ngx das Fundament.