Paperless-ngx v3: Update ohne Beta-Test

Endlich war Paperless-ngx in der stabilen Version 3.x verfügbar. Die Beta-Phase hatte ich schon seit Längerem verfolgt – über Artikel, Diskussionen und einige YouTube-Videos. Trotzdem habe ich diesmal bewusst keine Beta installiert. Das ist für mich eher untypisch: Normalerweise teste ich neue Versionen gerne früh und nehme kleinere Ecken und Kanten in Kauf.

Der erste wichtige Moment kam im Gespräch mit Clawvis. Der Bot wollte direkt loslegen und die neuen Images pullen. Ich musste ihn zunächst bremsen, denn meine Sorge war, dass er zu früh direkt auf irgendeine 3.0.x-Version springen könnte, ohne dass wir die Reihenfolge und die Ausgangslage sauber geprüft hatten.

Genau darum geht es bei diesem Update: Clawvis übernimmt die Orchestrierung, die Prüfungen und die Dokumentation. Die Entscheidung, wann welcher Schritt an der Reihe ist und wann die Freigabe für die nächste Änderung erteilt wird, bleibt aber beim Menschen.

Die Ausgangslage

Paperless-ngx läuft bei mir auf einem UGREEN NAS DXP2800 in einer Docker-Compose-Umgebung. Vor dem Update war Paperless-ngx in Version 2.19.6 installiert. Als Datenbank kam PostgreSQL 16 zum Einsatz, für den Cache Redis 7.4.4. Die beiden weiteren Dienste für die Dokumentenverarbeitung waren Gotenberg 8.25.1 und Tika 3.2.3.0.

Der Anlass für das Update war keine Lust auf ein Experiment, sondern die stabile Version 3.x. Die Beta-Phase hatte ich bewusst abgewartet. Erst als die neue Hauptversion stabil verfügbar war, wollte ich den Schritt gehen. Trotzdem sollte das Update nicht einfach aus einem docker compose pull und einem anschließenden Neustart bestehen. Bei Paperless hängen mehrere Dienste zusammen. Ein Fehler bei der Datenbank oder der Dokumentenverarbeitung wäre deutlich unangenehmer als ein paar Minuten zusätzliche Vorbereitung.

Deshalb habe ich zunächst die Daten gesichert. Den PostgreSQL-Dump habe ich direkt aus dem Datenbank-Container erstellt und komprimiert:

docker exec paperless-db-1 pg_dump -U paperless paperless | gzip > backup/paperless-db.sql.gz

Zusätzlich habe ich das Datenverzeichnis und die Medien separat archiviert:

tar czf backup/data.tar.gz -C /volume1/docker/paperless data/
tar czf backup/media.tar.gz -C /volume1/docker/paperless media/

Damit war die wichtigste Grundlage geschaffen: ein sauberes Backup, nachvollziehbare Zwischenschritte und eine definierte Ausgangslage.

Welche Rolle Clawvis beim Update übernommen hat

OpenClaw ist das Gateway-System, auf dem mein KI-Assistent Clawvis läuft. Bei mir läuft OpenClaw auf einem Raspberry Pi 5 und stellt die Verbindung zu den verschiedenen Werkzeugen und Systemen her, die ich für solche Aufgaben nutze.

Clawvis hat beim Update vor allem für Struktur gesorgt. Gemeinsam haben wir die einzelnen Schritte festgelegt: die Ausgangslage prüfen, Backups kontrollieren, Compose- und Env-Dateien durchgehen, Images herunterladen und anschließend jeden Dienst einzeln testen. Änderungen und Prüfergebnisse wurden dokumentiert, damit jederzeit nachvollziehbar blieb, was bereits erledigt war.

Die Entscheidungen und einige wichtige Arbeitsschritte habe ich trotzdem selbst übernommen. Ich habe den ersten Start bewusst gebremst, als Clawvis direkt die neuen Images laden wollte. Außerdem habe ich die Compose-Dateien manuell angepasst, weil ich die Änderungen nicht einfach ungeprüft übernehmen wollte. Den Pull auf Paperless-ngx 2.20.15 habe ich anschließend selbst ausgeführt. Erst nachdem die Zwischenstände und die laufenden Dienste geprüft waren, habe ich die finale Freigabe für die nächsten Schritte erteilt.

Automatisierung bedeutet nicht, jede Entscheidung an einen Assistenten abzugeben. Clawvis kann den Ablauf strukturieren, Abhängigkeiten sichtbar machen, Konfigurationen prüfen und die Dokumentation aktuell halten. Ob ein Schritt tatsächlich ausgeführt wird, wann eine Pause sinnvoll ist und ob das Ergebnis akzeptabel ist, bleibt aber meine Verantwortung als Betreiber. Gerade bei einem Upgrade mit Datenbank, Cache und mehreren Dokumentenverarbeitungsdiensten war diese Kombination aus automatisierter Prüfung und manueller Freigabe deutlich beruhigender als ein vollständig unkontrollierter Versionssprung.

Der Zwischenschritt auf Version 2.20.15

Ich habe mich bewusst dagegen entschieden, direkt von Paperless-ngx 2.19.6 auf Version 3.0.5 zu springen. Der Zwischenschritt auf 2.20.15 machte das Update für mich kontrollierbarer. Falls etwas schiefgelaufen wäre, hätte ich den Fehler deutlich leichter einer bestimmten Änderung zuordnen können.

Technisch war der Schritt überschaubar. In der docker-compose.yml habe ich zunächst den Image-Tag angepasst:

image: ghcr.io/paperless-ngx/paperless-ngx:2.20.15

Danach habe ich das neue Image geladen und den Container neu erstellt:

docker compose pull
docker compose up -d

Anschließend kam die Funktionskontrolle. Ich habe die Weboberfläche geöffnet, mich angemeldet und geprüft, ob die vorhandenen Dokumente weiterhin sichtbar waren. Auch die Suche habe ich ausprobiert. Der Zwischenschritt selbst war unspektakulär – genau das war der Vorteil: Paperless-ngx 2.20.15 lief, die Daten waren vorhanden, Login und Suche funktionierten. Damit war eine wichtige Unsicherheit aus dem späteren Sprung auf Version 3.0.5 herausgenommen.

Änderungen an Compose- und Env-Dateien

Bevor ich Paperless-ngx auf Version 3.0.5 aktualisiert habe, standen noch einige Änderungen in der Konfiguration an. Paperless-ngx v3 hat mehrere Umgebungsvariablen geändert oder entfernt. Wer diese Anpassungen übersieht, kann nach dem Update unangenehme Überraschungen erleben.

Die wichtigste Änderung betraf die Datenbank-Engine. In Version 2 wurde die Engine automatisch erkannt, wenn PAPERLESS_DBHOST gesetzt war. In Version 3 muss explizit angegeben werden, welche Datenbank verwendet wird. Ohne diesen Eintrag nimmt Paperless fälschlich SQLite an. Deshalb habe ich in der docker-compose.env folgende Zeile ergänzt:

PAPERLESS_DBENGINE=postgresql

Außerdem habe ich die alte Barcode-Scanner-Einstellung entfernt. In Version 3 wird der Barcode-Scanner nicht mehr über diese Umgebungsvariable gesteuert. ZXing-CPP ist das verwendete Backend, die alte Variable ist inzwischen obsolet:

# Entfernt:
PAPERLESS_CONSUMER_BARCODE_SCANNER=ZXING

Eine weitere Änderung betrifft das Verhalten bei Duplikaten. In Version 3 werden Duplikate standardmäßig erlaubt und nur als Warnung angezeigt. Wer das frühere Verhalten beibehalten möchte, muss eine zusätzliche Variable setzen:

PAPERLESS_CONSUMER_DELETE_DUPLICATES=true

Parallel dazu hat Clawvis die Begleitdienste Tika (3.2.3.0) und Gotenberg (8.25.1) auf Kompatibilität mit Paperless-ngx 3.0.5 geprüft. Das Ergebnis war eindeutig: Beide Versionen waren kompatibel. Ich musste weder Tika noch Gotenberg ändern. Die Prüfung wurde dokumentiert – einschließlich der eingesetzten Versionen und der Begründung, warum keine Anpassung erforderlich war.

Der finale Schritt auf Paperless-ngx 3.0.5

Erst nachdem Paperless-ngx 2.20.15 stabil lief, habe ich den eigentlichen Sprung auf v3 durchgeführt. In der Compose-Datei musste dafür lediglich der Image-Tag angepasst werden:

services:
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:3.0.5

Danach habe ich die neue Version geladen und die Container neu gestartet:

docker compose pull
docker compose up -d

Anschließend kontrollierte ich die Logs und das Startverhalten der Container. Dabei war mir besonders wichtig, dass die Datenbankmigrationen sauber durchliefen, der Suchindex neu aufgebaut wurde und die Verbindungen zu PostgreSQL, Redis, Tika und Gotenberg funktionierten.

Der Schritt auf Paperless-ngx 3.0.5 verlief problemlos. Nacharbeiten an der Konfiguration waren nicht erforderlich. Die Meldung no classifier training task found tauchte zwar auf, ist aber kein Fehler. Das Task-System wurde in v3 umgebaut; die Meldung bedeutet lediglich, dass aktuell keine Klassifikator-Trainingsaufgabe vorhanden ist.

Die neue AI-Konfiguration

Paperless-ngx 3 bringt eigene AI-Funktionen mit, die auf einem RAG-Ansatz basieren. Die dafür benötigten Sprachmodelle und Embeddings lassen sich direkt in der Weboberfläche konfigurieren. Die AI kann automatisch Kategorien, Korrespondenten und Dokumententypen vorschlagen sowie Zusammenfassungen erstellen.

Ich habe gpt-4o-mini als LLM und text-embedding-3-small für die Embeddings ausgewählt und die OpenAI-API hinterlegt. Wichtig ist dabei: Diese Einstellungen landen in der Paperless-Datenbank und nicht in meiner docker-compose.env. Die integrierten AI-Funktionen sind außerdem unabhängig von Erweiterungen wie paperless-ai oder paperless-gpt.

Kontrolle nach dem Upgrade

Nach dem Upgrade habe ich die wichtigen Bereiche einzeln geprüft: Weboberfläche und Login, vorhandene Dokumente, Suche, Consumer und OCR. Zusätzlich habe ich kontrolliert, ob Tika, Gotenberg und die neue AI-Konfiguration wie erwartet funktionieren. Das Ergebnis war erfreulich unspektakulär: Es waren keine Nacharbeiten erforderlich. Das gesamte Upgrade hat inklusive Planung, Backup, dem Zwischenschritt über Version 2.20.15, Tests und Dokumentation ungefähr zwei Stunden gedauert.

Das Vorgehen in Kurzform

Vor dem Update habe ich folgende Sicherungen erstellt:

• PostgreSQL-Datenbank mit pg_dump
• Datenverzeichnis als tar.gz
• Medienverzeichnis als tar.gz
• Compose- und Env-Dateien als separate Kopien

Anschließend habe ich die Konfiguration für Paperless-ngx 3 vorbereitet:

PAPERLESS_DBENGINE=postgresql
PAPERLESS_CONSUMER_DELETE_DUPLICATES=true
# Entfernt:
PAPERLESS_CONSUMER_BARCODE_SCANNER=ZXING

Das eigentliche Upgrade habe ich in zwei kontrollierten Schritten durchgeführt:

1. Den Paperless-Image-Tag auf 2.20.15 ändern, das Image mit docker compose pull laden und den Stack mit docker compose up -d neu starten.
2. Weboberfläche, Login, vorhandene Dokumente und Suche prüfen.
3. Den Image-Tag auf 3.0.5 ändern und den Stack erneut aktualisieren.
4. Logs, Datenbankmigrationen und die Verbindungen zu PostgreSQL, Redis, Tika und Gotenberg kontrollieren.
5. Anmeldung, Dokumentzugriff, Suche, Upload, Verarbeitung und AI-Konfiguration testen.

Mein Fazit

Das Upgrade von Paperless-ngx 2.19.6 über 2.20.15 auf 3.0.5 ist sauber verlaufen. Nacharbeiten waren bei mir nicht notwendig. Entscheidend war nicht ein besonders mutiger Versionssprung, sondern die Kombination aus Backup, Zwischenversion und anschließender Funktionsprüfung.

Wer ein sauberes Backup besitzt und das Upgrade kontrolliert plant, sollte den Wechsel auf Paperless-ngx 3 aus meiner Sicht durchführen. Den letzten Schritt hat dabei nicht ein Bot allein erledigt. Das Ergebnis entstand durch klare Rollen: Clawvis orchestriert und prüft, Oliver entscheidet und gibt frei.