Paperless-ngx Docker Upgrade: von 2.20.15 auf 3.0.4

Paperless-ngx 3.0 bringt Breaking Changes. Diese Anleitung zeigt das Upgrade einer Docker-Installation, 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, passiert im Docker-Image automatisch beim Start.
• 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.
• Datenbankmigrationen sind nicht rückwärtskompatibel. Ohne Backup kein Rollback.

Vollständige Liste: github.com/paperless-ngx/paperless-ngx/releases

Schritt 1: Backup

cd /opt/paperless

docker compose stop

# Datenbank (Beispiel PostgreSQL)
docker compose exec -T db pg_dump -U paperless paperless > /opt/backup/paperless-db-$(date +%F).sql

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

# Compose-Files sichern
cp docker-compose.yml /opt/backup/docker-compose.yml.bak
cp docker-compose.env /opt/backup/docker-compose.env.bak

Alternativ den eingebauten Paperless-Exporter nutzen:

docker compose run --rm webserver document_exporter ../export

Schritt 2: Secret Key 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.

openssl rand -base64 64

In docker-compose.env oder direkt in docker-compose.yml unter environment 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 3: Datenbank-Engine explizit setzen

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

# v2 (PostgreSQL wurde aus PAPERLESS_DBHOST abgeleitet)
PAPERLESS_DBHOST: postgres

# v3 (Engine muss explizit gesetzt sein)
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:

PAPERLESS_DB_OPTIONS: "sslmode=require,pool.max_size=20"

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

Schritt 4: Image-Tag auf 3.0.4 setzen

In docker-compose.yml:

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

ändern zu:

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

Wer bisher :latest nutzt: :latest zeigt seit Juli 2026 bereits auf 3.x. Für kontrollierte Major-Upgrades empfiehlt sich grundsätzlich ein fester Versions-Tag statt :latest.

Schritt 5: Neues Image ziehen und Container neu erstellen

docker compose pull
docker compose up -d

Der Suchindex-Rebuild (Whoosh → Tantivy) läuft beim ersten Start automatisch im Container. Bei größeren Archiven dauert das spürbar.

Schritt 6: Logs beobachten

docker compose logs -f webserver

Auf Migrationsfehler, fehlende Env-Variablen oder Reindex-Fortschritt achten.

Schritt 7: 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.
• Containerstatus prüfen: docker compose ps.

Rollback

Bei Problemen:

docker compose down

Alten Image-Tag (2.20.15) in docker-compose.yml zurücksetzen, DB-Dump aus Schritt 1 einspielen, data/ und media/ aus dem Backup zurückkopieren, dann:

docker compose up -d

Bekannte Stolperfallen

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

Quelle: github.com/paperless-ngx/paperless-ngx/releases