Nach dem Update auf Paperless-ngx 3.0 unter ZimaOS blieb mein Docker-Container in einer Neustartschleife hängen. Die Ursache war zunächst nicht offensichtlich, denn Redis und MariaDB liefen problemlos.

Erst ein Blick in die Container-Logs brachte die Lösung.

---

Fehlermeldung

Im Docker-Log erschien folgende Meldung:

PAPERLESS_SECRET_KEY is not set or is the default 'change-me' value.

Seit Paperless-ngx 3.0 ist ein eigener PAPERLESS_SECRET_KEY zwingend erforderlich. Ohne diesen startet der Webserver nicht mehr.

---

Schritt 1 – Secret Key erzeugen

Ein sicheres Passwort lässt sich direkt im Terminal erzeugen:

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

Den ausgegebenen Schlüssel anschließend kopieren.

---

Schritt 2 – Docker Compose bearbeiten

Die Compose-Datei befindet sich unter:

/var/lib/casaos/apps/paperless/docker-compose.yml

Öffnen:

sudo nano /var/lib/casaos/apps/paperless/docker-compose.yml

Im Bereich environment: folgende Zeile ergänzen:

PAPERLESS_SECRET_KEY=DEIN_GENERIERTER_SCHLÜSSEL

---

Schritt 3 – Warum trotzdem Version 2.20 gestartet wurde

Obwohl das neue Docker-Image bereits heruntergeladen war, startete ZimaOS weiterhin Version 2.20.

Ein Blick in die Compose-Datei zeigte:

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

Diese Zeile musste auf Version 3.0 geändert werden:

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

---

Schritt 4 – Container neu erstellen

cd /var/lib/casaos/apps/paperless
sudo docker compose up -d --force-recreate

Danach werden automatisch sämtliche Datenbankmigrationen ausgeführt.

Bei mir wurden unter anderem folgende Migrationen installiert:

• documents.0003
• documents.0004
• …
• documents.0015

Anschließend begann Paperless automatisch damit, die SHA-256-Prüfsummen aller Dokumente neu zu berechnen.

Bei meiner Installation waren das 571 Dokumente.

---

Schritt 5 – Status prüfen

Containerstatus:

sudo docker ps

Gewünschte Ausgabe:

Up (healthy)

Version kontrollieren:

sudo docker exec paperless-paperless-1 python manage.py version

---

Zwei gelbe Ausrufezeichen nach dem Update?

Nach dem erfolgreichen Update erschienen bei mir zwei Warnhinweise:

• No classifier training task found
• No sanity tasks found

Das ist zunächst kein Fehler.

No classifier training task found

Der automatische Klassifizierer wurde nach dem Update einfach noch nicht ausgeführt.

No sanity tasks found

Auch der Integritätscheck wurde seit dem Update noch nicht gestartet.

Beide Aufgaben werden normalerweise automatisch ausgeführt.

Wer möchte, kann sie auch manuell starten:

sudo docker exec paperless-paperless-1 python manage.py train_classifier

sudo docker exec paperless-paperless-1 python manage.py document_sanity_checker

---

Fazit

Das eigentliche Update auf Paperless-ngx 3.0 ist unkompliziert – die beiden Stolpersteine sind jedoch:

• fehlender PAPERLESS_SECRET_KEY
• Docker Compose verweist weiterhin auf das alte Image

Sind beide Punkte behoben, läuft Paperless-ngx 3.0 auf ZimaOS stabil und ohne weitere Probleme.