Paperless-ngx Upgrade: von 2.20.15 auf 3.0.4 (Debian-VM auf Proxmox)

Paperless-ngx 3.0 bringt Breaking Changes. Diese Anleitung zeigt das Bare-Metal-Upgrade auf einer Debian-VM unter Proxmox, Schritt für Schritt.

Voraussetzung: Ausgangsversion muss 2.20.15 sein. Nur von dort aus ist der Sprung auf 3.0 offiziell unterstützt. Ältere Versionen zuerst auf 2.20.15 bringen.

Was sich in 3.0 ändert

• Suchindex wechselt von Whoosh zu Tantivy (Rust). Volltextindex muss neu aufgebaut werden.
• PAPERLESS_SECRET_KEY ist jetzt Pflicht.
• PAPERLESS_DBENGINE ist bei PostgreSQL/MariaDB jetzt Pflicht (vorher aus PAPERLESS_DBHOST abgeleitet).
• Diverse SSL-/Timeout-/Pooling-Variablen der DB entfallen zugunsten von PAPERLESS_DB_OPTIONS.
• API-Version 1 fällt weg.
• Dokument-Prüfsummen wechseln auf SHA-256.
• Consumer-/OCR-Variablen teils umbenannt, OCR_MODE=skip-Verhalten ändert sich.
• Datenbankmigrationen sind nicht rückwärtskompatibel. Ohne Backup kein Rollback.

Schritt 1: Snapshot der Proxmox-VM

Vor allem anderen: VM-Snapshot in Proxmox erstellen. Das ist der schnellste Rollback-Weg, unabhängig vom Applikations-Backup. Backup wichtig! Es kann immer was schief laufen!

qm snapshot <VMID> pre-paperless-3-0-4

Schritt 2: Anwendungs-Backup

Zusätzlich zum Snapshot ein Paperless-eigenes Backup, da die DB-Migration nicht reversibel ist.

sudo systemctl stop paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue

# Datenbank (Beispiel PostgreSQL)
sudo -u postgres pg_dump paperless > /opt/backup/paperless-db-$(date +%F).sql

# Daten- und Medienverzeichnisse
sudo tar -czf /opt/backup/paperless-media-$(date +%F).tar.gz /opt/paperless/media
sudo tar -czf /opt/backup/paperless-data-$(date +%F).tar.gz /opt/paperless/data

# Konfiguration
sudo cp /opt/paperless/paperless.conf /opt/backup/paperless.conf.bak

Bei SQLite genügt eine Kopie der .sqlite3-Datei aus dem Datenverzeichnis.

Schritt 3: Version prüfen

cd /opt/paperless
sudo -Hu paperless git describe --tags

Muss v2.20.15 zeigen. Falls nicht: erst dorthin updaten, dann weiter.

Schritt 4: Secret Key sichern/setzen

Falls bisher kein PAPERLESS_SECRET_KEY gesetzt war, lief 2.x mit einem eingebauten Default-Key. Für 3.0 wird ein expliziter Key Pflicht.

python3 -c "import secrets; print(secrets.token_urlsafe(64))"

Wert in paperless.conf eintragen:

PAPERLESS_SECRET_KEY=<generierter-wert>

Wichtig: Wird ein neuer, zufälliger Key gesetzt statt des alten Default-Keys, werden bestehende Sessions und API-Tokens ungültig. Nutzer müssen sich neu anmelden.

Schritt 5: Datenbank-Engine explizit setzen

Nur bei PostgreSQL oder MariaDB nötig, nicht bei SQLite.

PAPERLESS_DBENGINE=postgresql
PAPERLESS_DBHOST=postgres

Zulässige Werte: postgresql oder mariadb. Bisherige einzelne SSL-/Timeout-/Pooling-Variablen durch PAPERLESS_DB_OPTIONS ersetzen, falls verwendet, z. B.:

PAPERLESS_DB_OPTIONS=sslmode=require,pool.max_size=20

Alte Variablen funktionieren übergangsweise weiter, loggen aber eine Deprecation-Warnung beim Start.

Schritt 6: Systemabhängigkeiten aktualisieren

sudo apt update
sudo apt install --only-upgrade python3 python3-pip python3-dev imagemagick fonts-liberation \
  gnupg libpq-dev default-libmysqlclient-dev pkg-config libmagic-dev mime-support \
  libzbar0 poppler-utils unpaper ghostscript icc-profiles-free qpdf liblept5 \
  libxml2 pngquant zlib1g tesseract-ocr

Ergänzend benötigte OCR-Sprachpakete (tesseract-ocr-deu etc.) prüfen, falls sich Sprachvorgaben geändert haben.

Schritt 7: Dienste stoppen

Falls Schritt 2 nicht schon erledigt:

sudo systemctl stop paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue

Schritt 8: Quellcode auf 3.0.4 bringen

cd /opt/paperless
sudo -Hu paperless git fetch --all --tags
sudo -Hu paperless git checkout tags/v3.0.4

Schritt 9: Python-Abhängigkeiten aktualisieren

Venv aktivieren und Requirements neu installieren:

sudo -Hu paperless bash -c '
  source /opt/paperless/venv/bin/activate
  pip install --upgrade pip
  pip install -r requirements.txt
'

Danach die installierten Pakete gegen die neue requirements.txt abgleichen und nicht mehr benötigte Pakete entfernen, um Konflikte zu vermeiden.

Schritt 10: Datenbankmigration

cd /opt/paperless/src
sudo -Hu paperless ../venv/bin/python3 manage.py migrate

Schritt 11: Statische Dateien und Suchindex

sudo -Hu paperless ../venv/bin/python3 manage.py collectstatic --clear --no-input
sudo -Hu paperless ../venv/bin/python3 manage.py document_index reindex --if-needed

Der --if-needed-Flag prüft Schema-Version und Sprach-Sentinels und baut den Tantivy-Index nur neu, wenn nötig. Bei größeren Archiven (mehrere zehntausend Dokumente) dauert das spürbar; Fortschritt im Log beobachten.

Schritt 12: Dienste starten

sudo systemctl start paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue
sudo systemctl status paperless-webserver

Schritt 13: Verifikation

• Version in der Weboberfläche prüfen (Systemstatus zeigt 3.0.4).
• Volltextsuche testen, auch nach Umlauten und mehreren Suchbegriffen (Tantivy verknüpft Begriffe standardmäßig mit OR statt AND wie zuvor Whoosh).
• Ein Testdokument einscannen/konsumieren lassen, OCR-Ergebnis prüfen.
• Download und Vorschau eines bestehenden Dokuments prüfen.
• Login/API-Token testen, falls der Secret Key neu gesetzt wurde.
• Log auf Fehler prüfen: journalctl -u paperless-webserver -n 200.

Rollback

Bei Problemen: Dienste stoppen, VM-Snapshot aus Schritt 1 zurückspielen. Alternativ Git-Checkout auf v2.20.15, DB-Dump aus Schritt 2 einspielen, altes paperless.conf zurückkopieren, Venv-Requirements der 2.20.15 neu installieren.

Bekannte Stolperfallen

• Fehlender PAPERLESS_SECRET_KEY bricht den Start ab.
• PAPERLESS_DBENGINE vergessen bei PostgreSQL/MariaDB führt zu Verbindungsfehlern.
• Veraltete Syntax in globalen Dateinamensvorlagen kann nach dem Upgrade Fehler werfen.
• Zusätzliche, nicht mehr benötigte Container/Prozesse aus älteren Setups können mit dem neuen Consumer kollidieren.