UGREEN NAS: Paperless-ngx mit deutscher Texterkennung einrichten

Paperless-ngx macht aus der UGREEN NAS ein durchsuchbares Archiv für Rechnungen, Verträge und Briefe. Sie legen einen Scan in einen Eingangsordner, Paperless-ngx erkennt den Text, liest das Datum aus und legt das Dokument ab. Diese Anleitung zeigt eine schlanke Einrichtung mit PostgreSQL und Valkey auf der UGREEN NAS, das erste Konto im Browser, den Test der deutschen Texterkennung mit zwei Scans ohne Textebene und die Sicherung mit dem Exporter.

Getestet auf einer UGREEN DXP4800 Pro mit UGOS Pro 1.21.0.0190 und Docker 29.6.2, mit Paperless-ngx 3.4.1, PostgreSQL 18 und Valkey 9. Unser Testkonto hieß sedv.

Voraussetzungen

• Eine UGREEN NAS mit der App Docker, siehe Teil 63
• SSH-Zugang, siehe Teil 52
• Grundwissen zu Compose, siehe Docker Compose als Grundlage
• Rund 3 GB für die Images, dazu Platz für Ihre Dokumente
• Etwa 30 Minuten

Die allgemeine Einrichtung auf einem Linux-Server mit Tika und Gotenberg für Office-Dateien und E-Mails beschreibt unsere Anleitung Paperless-ngx mit Docker. Hier geht es um die schlanke Variante für PDFs und Bilder auf der UGREEN NAS.

Schritt 1: Ordner und Geheimnisse anlegen

Legen Sie einen Projektordner an und erzeugen Sie zwei zufällige Werte, einen für das Passwort der Datenbank und einen für den geheimen Schlüssel von Paperless-ngx:

sudo mkdir -p /volume2/docker/paperless/consume /volume2/docker/paperless/export
cd /volume2/docker/paperless
openssl rand -hex 24
openssl rand -hex 32

Tragen Sie die Werte mit dem Editor ein, zuerst in db.env:

sudo nano db.env

POSTGRES_PASSWORD=ERSTER_WERT

Dann in paperless.env, mit demselben ersten Wert für die Datenbank:

sudo nano paperless.env

PAPERLESS_DBPASS=ERSTER_WERT
PAPERLESS_SECRET_KEY=ZWEITER_WERT

sudo chmod 600 db.env paperless.env

Der geheime Schlüssel sichert Anmeldungen und Sitzungen. Paperless-ngx 3 hat dafür keinen Standardwert und startet ohne ihn nicht. Steht in einer Vorlage noch der Platzhalter change-me, ersetzen Sie ihn durch Ihren eigenen Wert. Passen Sie volume2 an Ihre NAS an, auf vielen Geräten ist es volume1.

Verifizieren: Die Ausgabe von ls -la zeigt db.env und paperless.env mit -rw-------.

Schritt 2: Die Compose-Datei schreiben

Die offizielle Vorlage docker-compose.postgres.yml dient als Grundlage. Wir haben feste Versionen, Containernamen, die Sprache der Texterkennung und Bind-Mounts statt benannter Volumes eingetragen, damit alle Daten sichtbar im Projektordner liegen:

services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    container_name: paperless-broker
    restart: unless-stopped
    volumes:
      - ./redisdata:/data
    labels:
      - wud.watch=false

  db:
    image: docker.io/library/postgres:18
    container_name: paperless-db
    restart: unless-stopped
    env_file: db.env
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
    volumes:
      - ./pgdata:/var/lib/postgresql
    labels:
      - wud.watch=false

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:3.4.1
    container_name: paperless
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8091:8000"
    env_file: paperless.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql
      PAPERLESS_TIME_ZONE: Europe/Berlin
      PAPERLESS_OCR_LANGUAGE: deu
      PAPERLESS_URL: http://192.168.1.10:8091
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    labels:
      - wud.watch=false

Die wichtigsten Punkte:

• Valkey: Die offizielle Vorlage nutzt Valkey, einen freien Ableger von Redis. Paperless-ngx spricht ihn über PAPERLESS_REDIS an.
• PostgreSQL 18: Ab Version 18 erwartet das Image die Daten unter /var/lib/postgresql statt /var/lib/postgresql/data. Der Pfad in der Vorlage ist darauf schon eingestellt, die Daten landen dann in pgdata/18/docker. Das Passwort aus db.env gilt nur beim ersten Start, eine spätere Änderung in der Datei ändert es in der Datenbank nicht. Eine bestehende Datenbank einer älteren Hauptversion startet unter 18 nicht, dazu mehr bei den typischen Fehlern.
• PAPERLESS_OCR_LANGUAGE: deu für deutsche Dokumente. Für gemischte Bestände geht deu+eng. Im Image waren bei uns Deutsch, Englisch, Französisch, Italienisch und Spanisch enthalten.
• PAPERLESS_URL: die Adresse, unter der Sie Paperless-ngx aufrufen. Tragen Sie statt 192.168.1.10 die Adresse Ihrer NAS ein, hinter einem Reverse Proxy die Domain mit https, jeweils ohne Schrägstrich am Ende.
• wud.watch=false: nimmt die Container von What's Up Docker aus. Wie ein automatisches Update von PostgreSQL eine Datenbank lahmlegt, zeigt Teil 75.

Port 8091 war bei uns frei. Prüfen Sie Ihren Port vorher, keine Ausgabe bedeutet frei:

sudo ss -ltn | grep :8091

Verifizieren: Die Ausgabe von sudo docker compose config --quiet bleibt leer, die Datei ist also gültig.

Schritt 3: Starten und das erste Konto anlegen

sudo docker compose pull
sudo docker compose up -d

Die Images waren bei uns 2,48 GB für Paperless-ngx, 457 MB für PostgreSQL und 45 MB für Valkey groß. Kommt beim Herunterladen von ghcr.io die Meldung toomanyrequests, wiederholen Sie den Befehl nach einigen Minuten. Der erste Start dauert etwas länger, weil Paperless-ngx die Datenbank anlegt. Das Image bringt eine eigene Gesundheitsprüfung mit, die alle 30 Sekunden die Weboberfläche abfragt. Mehr zu Gesundheitsprüfungen steht in Docker Compose absichern.

sudo docker compose ps --format "{{.Name}} {{.Status}}"

paperless Up 2 minutes (healthy)
paperless-broker Up 2 minutes
paperless-db Up 2 minutes

Öffnen Sie dann http://ADRESSE-DER-NAS:8091. Solange es noch kein Konto gibt, leitet Paperless-ngx auf die Seite Registrieren um.

Das erste Konto erhält Administratorrechte. Wer die Seite zuerst aufruft, legt es also an. Richten Sie das Konto deshalb direkt nach dem Start ein und geben Sie Port 8091 nicht ins Internet frei. Danach ist die Registrierung gesperrt, die Seite meldet dann Sign Up Closed. Neue Konten legen Sie als Administrator unter Benutzer & Gruppen an. Für die tägliche Arbeit empfiehlt die Dokumentation ein zweites Konto ohne Administratorrechte.

Verifizieren: Nach dem Registrieren zeigt die Startseite die Meldung Paperless-ngx wurde erfolgreich gestartet.

Schritt 4: Dokumente in den Eingangsordner legen

Für den Test haben wir zwei gescannte Seiten ohne Textebene verwendet, eine Rechnung der Musterfirma GmbH und einen Versicherungsschein der Beispiel Versicherung AG. Paperless-ngx muss den Text also selbst erkennen. Kopieren Sie Ihre PDFs in den Ordner consume, per SSH etwa so:

sudo cp ~/rechnung.pdf /volume2/docker/paperless/consume/

Den Ordner erreichen Sie auch über den Dateimanager von UGOS im freigegebenen Ordner docker. Geben Sie diesen Ordner nur Administratoren frei, dort liegen auch die Geheimnisse und alle Dokumente. Alternativ laden Sie Dateien in der Weboberfläche über Hochladen hoch. Paperless-ngx bemerkt neue Dateien im Ordner consume sofort. Bei uns waren beide Dokumente nach wenigen Sekunden verarbeitet, die Verarbeitung selbst dauerte etwa 4,4 Sekunden je Dokument. Das Protokoll zeigt den Ablauf:

sudo docker logs --tail 20 paperless 2>&1 | grep consumption

Document 2026-11-01 testvertrag consumption finished

Danach ist der Ordner consume wieder leer. Paperless-ngx verschiebt die Datei nicht, es legt Original und eine Archivfassung unter media ab und löscht die Datei im Eingang. Die Dateien gehören dem Konto mit der Nummer 1000, diese Nummer nutzt Paperless-ngx ab Werk. Auf unserer NAS war das das Testkonto sedv. Mit id -u prüfen Sie die Nummer Ihres Kontos. Weicht sie ab, setzen Sie USERMAP_UID und USERMAP_GID im Dienst webserver.

Verifizieren: Unter Dokumente stehen beide Dateien mit Vorschaubild, und der Ordner consume ist leer.

Schritt 5: Texterkennung und Datum prüfen

Öffnen Sie ein Dokument und wechseln Sie auf den Reiter Inhalt. Dort steht der erkannte Text, rechts die Vorschau des Originals.

Bei uns stimmte der Text Zeichen für Zeichen mit dem Scan überein, auch Umlaute und ß wie in Beispielstraße. Das Datum hat Paperless-ngx aus dem Text gelesen: bei der Rechnung den 14.10.2026 aus der Zeile Datum, beim Versicherungsschein den 01.11.2026 aus der Zeile Beginn. Es nimmt dabei das erste Datum, das es im Text findet. Steht auf Ihren Dokumenten oben ein anderes Datum, etwa ein Druckdatum, korrigieren Sie es unter Details im Feld Ausstellungsdatum. Taucht ein festes Datum wie Ihr Geburtsdatum regelmäßig auf, schließen Sie es mit PAPERLESS_IGNORE_DATES aus. Die Sprache für die Datumserkennung leitet Paperless-ngx aus PAPERLESS_OCR_LANGUAGE ab.

Den erkannten Text findet die Volltextsuche. Unsere Suche nach Hausrat lieferte genau den Versicherungsschein, obwohl das Wort nur im Text des Scans und nicht im Dateinamen stand.

Verifizieren: Die Suche nach einem Wort, das nur im gescannten Text steht, findet das passende Dokument.

Schritt 6: Ordnung mit Tags, Korrespondenten und Typen

Unter Verwaltung, Attribute legen Sie Tags, Korrespondenten wie Musterfirma GmbH und Dokumenttypen wie Rechnung an. Paperless-ngx ordnet neue Dokumente nach dem Zuweisungsalgorithmus zu, ab Werk mit Auto: Zuweisung automatisch erlernen. Dabei lernt es aus den Dokumenten, die Sie schon zugeordnet haben. Mit nur zwei Dokumenten hat es noch nichts gelernt. Ordnen Sie die ersten Dokumente deshalb von Hand zu, unter Details mit den Feldern Korrespondent und Dokumenttyp, mit jedem weiteren wird die Zuordnung treffsicherer. Für feste Regeln, etwa ein Tag für alle Dokumente mit dem Wort Rechnung, wählen Sie Irgendein Wort oder Exakt.

Verifizieren: Nach dem Zuordnen zeigt die Dokumentenliste den Korrespondenten vor dem Titel, bei uns Musterfirma GmbH: testrechnung, und darunter den Typ Rechnung.

Schritt 7: Sichern mit dem Exporter

Paperless-ngx bringt mit document_exporter ein eigenes Werkzeug mit. Es schreibt alle Dokumente, Vorschaubilder und eine Datei manifest.json mit Tags, Korrespondenten, Konten und Einstellungen in den Ordner export:

cd /volume2/docker/paperless
sudo docker compose exec -T webserver document_exporter ../export

Exporting documents... ━━━━━━━━━━━━━━━━━━━━ 2/2

Bei uns lagen danach je Dokument drei Dateien im Ordner export: das Original, die Archivfassung und das Vorschaubild, dazu manifest.json mit 45 KB. Der Export lässt sich mit document_importer in eine komplett leere Installation mit derselben Version von Paperless-ngx zurückspielen, auch nach einem Wechsel der Hauptversion von PostgreSQL. Ändern Sie dabei keine Pfade und Einstellungen. Der Ordner export enthält alle Dokumente unverschlüsselt, sichern Sie ihn nur auf ein verschlüsseltes Ziel. Mit der Option --passphrase verschlüsselt der Exporter zusätzlich vertrauliche Felder, ohne diese Passphrase lässt sich der Export nicht mehr einspielen. Lassen Sie den Export regelmäßig per Aufgabenplanung laufen, dort mit der Option --no-progress-bar, und sichern Sie den Ordner export mit, wie in Teil 61 beschrieben. Den Ordner pgdata im laufenden Betrieb zu kopieren, ergibt keine verlässliche Sicherung der Datenbank.

Verifizieren: Im Ordner export stehen manifest.json und je Dokument drei Dateien: das Original, die Archivfassung als PDF und ein Vorschaubild im Format webp.

Typische Fehler

• Datenbank startet nach einem Update nicht: PostgreSQL wurde auf eine neue Hauptversion gehoben, die alten Daten passen nicht. Festes Tag wie postgres:18 und wud.watch=false setzen. Für einen geplanten Wechsel exportieren, die neue Datenbank leer aufsetzen und mit derselben Version von Paperless-ngx importieren.
• Dateien bleiben im Ordner consume liegen: Die Rechte passen nicht zur Nummer 1000. USERMAP_UID und USERMAP_GID setzen oder die Rechte des Ordners anpassen.
• Text voller Fehler bei Umlauten: PAPERLESS_OCR_LANGUAGE fehlt, dann erkennt Paperless-ngx Englisch. Auf deu setzen und das Dokument unter Aktionen, Erneut verarbeiten neu einlesen.
• CSRF-Fehler beim Anmelden hinter einem Reverse Proxy: PAPERLESS_URL fehlt oder enthält nicht genau die Adresse aus dem Browser, mit https, Domain und gegebenenfalls Port, ohne Schrägstrich am Ende. Wert anpassen und den Container mit sudo docker compose up -d neu erstellen.
• toomanyrequests beim Herunterladen: ghcr.io begrenzt anonyme Abrufe. Später wiederholen.

Häufige Fragen

Wie viel Arbeitsspeicher braucht Paperless-ngx?

Bei uns belegten die Container nach der Verarbeitung zusammen rund 690 MiB: Paperless-ngx 634 MiB, PostgreSQL 49 MiB und Valkey 8 MiB.

Lässt sich direkt vom Scanner in Paperless-ngx scannen?

Ja, wenn der Scanner auf eine Netzwerkfreigabe speichern kann. Ersetzen Sie dafür unter volumes die Zeile ./consume:/usr/src/paperless/consume durch einen freigegebenen Ordner der NAS, etwa /volume2/Scans:/usr/src/paperless/consume, und lassen Sie den Scanner dorthin speichern. Der Ordner muss für das Konto mit der Nummer 1000 beschreibbar sein. Wer in diesen Ordner schreiben darf, kann Dokumente einschleusen, geben Sie ihn nur dem Scanner und Ihnen frei.

Wie aktualisieren Sie Paperless-ngx?

Lesen Sie die Versionshinweise, erstellen Sie einen Export, ändern Sie das Tag in der Compose-Datei, etwa auf die nächste Version, und starten Sie neu:

sudo docker compose pull
sudo docker compose up -d

Paperless-ngx passt die Datenbank beim Start selbst an.

Wie greifen Sie von unterwegs zu?

Über einen Reverse Proxy mit HTTPS oder über VPN. Tragen Sie dann die Domain mit https bei PAPERLESS_URL ein. Paperless-ngx enthält Ihre Verträge und Rechnungen, schalten Sie unter Mein Profil, Zwei-Faktor-Authentifizierung zusätzlich einen zweiten Faktor ein.

Fazit

Paperless-ngx läuft auf der UGREEN NAS mit drei Containern und rund 690 MiB Arbeitsspeicher. Mit PAPERLESS_OCR_LANGUAGE=deu erkannte es unsere gescannten Testdokumente fehlerfrei, las das Datum aus dem Text und fand sie über die Volltextsuche. Wichtig sind ein eigener geheimer Schlüssel, das erste Konto direkt nach dem Start, feste Versionen ohne automatische Updates und ein regelmäßiger Export.

Weiterführende Anleitungen und Quellen

• Paperless-ngx mit Docker mit Tika und Gotenberg
• Teil 64: Compose-Projekt anlegen
• Teil 76: Nextcloud
• Paperless-ngx: Installation
• Paperless-ngx: Konfiguration
• Paperless-ngx: Exporter und Importer