Paperless-ngx Update: So aktualisierst du dein digitales Büro ohne Datenverlust

📌 Hinweis: Dieser Artikel ist Teil meiner großen Anleitungsserie zum digitalen Büro. Den kompletten Leitfaden findest du in der Übersicht: Paperless-ngx einrichten: Die ultimative Tutorial-Serie.

Dein papierloses Büro mit Paperless-ngx läuft seit einiger Zeit stabil, alle Dokumente sind digitalisiert und die Metadaten sauber gepflegt. Doch irgendwann steht es an: das erste große Update. Neue Funktionen, Sicherheits-Patches und Bugfixes machen eine Aktualisierung unumgänglich.

Viele Nutzer haben dabei die Sorge: Ist danach alles weg? Die klare Antwort lautet: Nein, wenn du es richtig anstellst. In dieser Anleitung zeige ich dir Schritt für Schritt, wie du dein Paperless-ngx Update (am Beispiel einer Synology NAS im Container-Manager) absolut sicher durchführst, sodass Dokumente, Tags und Einstellungen vollständig erhalten bleiben.

💡Du bist im Paperless-ngx noch nicht sattelfest und benötigst Hilfe bei der initialen Einrichtung? Dann schau mal in diesen Beitrag: Paperless-ngx einrichten: Womit anfangen? Der perfekte Start nach der Installation

Die Grundlage: Wo liegen deine Daten?

Bevor es an das Update geht, ist ein grundlegendes Verständnis der Docker-Struktur wichtig. Paperless-ngx läuft in einem Container. Ein Update bedeutet im Prinzip, dass der alte Container weggeworfen und ein neuer mit der aktuellen Version erstellt wird.

Damit dabei keine Daten verloren gehen, müssen deine Ordner als persistente (dauerhafte) Volumes außerhalb des Containers auf deinem Host-System (z. B. der Synology NAS) liegen. Relevant sind hier vor allem:

• /data: Enthält die interne Konfiguration und den Migrationsstatus.
• /media: Hier liegen all deine Originaldokumente und Vorschaubilder.
• /consume: Der Import-Ordner für neue Dokumente.
• /export: Der Standardordner für integrierte Backups.

Nur wenn diese Verzeichnisse in deiner docker-compose.yml korrekt auf lokale Ordner gemappt sind, ist ein Update ohne Datenverlust möglich.

Schritt 1: Die Update-Vorbereitung (GitHub & Breaking Changes)

Ein Update startet man niemals blind. Gehe zuerst auf die GitHub-Seite von Paperless-ngx in die Sektion Releases und prüfe die Änderungshistorie von deiner aktuellen Version (z. B. v2.19.6) bis zur gewünschten Zielversion (z. B. v2.20.10).

📄 Link zu den Release Seiten von Paperless-ngx

Halte gezielt Ausschau nach dem Begriff „Breaking Changes“. Das sind tiefgreifende Änderungen, die manuelle Anpassungen erfordern.

💡 Beispiel: In Version 2.20.7 wurden die Dateinamens-Variablen aus Sicherheitsgründen restriktiver gestaltet. Wer hier eigene, nicht standardisierte Pfade verbaut hat, muss vorab nachbessern. Gibt es keine Breaking Changes oder betreffen sie dein Setup nicht, kannst du beruhigt fortfahren.

Schritt 2: Die doppelte Sicherheitsstufe (Backup & Snapshot)

Bevor wir den Container anfassen, sichern wir das System ab:

1. Backup erstellen: Nutze den integrierten document_exporter für eine aktuelle Datensicherung (wie im separaten Blogbeitrag beschrieben).
2. Snapshot erstellen (Optional, aber empfohlen): Wenn du eine Synology NAS nutzt, öffne die App Snapshot Replication. Erstelle einen manuellen Schnappschuss deines docker-Gemeinsamen Ordners unter dem Namen vor_update. Sollte gleich etwas schiefgehen, hast du in Sekundenschnelle ein perfektes Fallback-Szenario.

💡Wie du im Paperless-ngx ein sauberes Backup erstellst damit alle deine Daten erhalten bleiben habe ich in diesem Beitrag dargelegt:

Stoppe nun den Paperless-ngx Container im Container-Manager (Exit Code 0).

Schritt 3: Versionsnummer anpassen und Image neu erstellen

Warum du „latest“-Tags vermeiden solltest

Ein wichtiger Profi-Tipp für deine Konfiguration: Nutze feste Versionsnummern (z. B. version: 2.20.10) anstelle des :latest-Tags. Das gilt besonders für die verwendete Datenbank (Redis, PostgreSQL oder MariaDB). Ein unbeabsichtigtes Major-Update einer Datenbank im Hintergrund zerschießt ohne die notwendigen Migrationsschritte fast immer deine Tabellenstrukturen!

Das eigentliche Update durchführen:

1. Öffne deine docker-compose.yml (oder die Projekt-Umgebung im Synology Container-Manager).
2. Suche die Zeile des Webservers (z. B. image: ghcr.io/paperless-ngx/paperless-ngx:2.19.6) und ändere die Versionsnummer auf den neuesten Stand (z. B. 2.20.10).
3. Speichere die Datei.
4. Wähle bei Synology die Aktion Bereinigen (dadurch werden die alten Container sauber entfernt).
5. Klicke auf Neu erstellen (bzw. docker compose up -d auf der CLI). Docker lädt nun die neuen Images herunter und baut das Projekt frisch auf.

Hinweis: Der erste Start nach einem Update kann gut 2–3 Minuten dauern, da Paperless im Hintergrund oft Datenbank-Migrationen durchführt. Hab etwas Geduld und wirf im Zweifel einen Blick in die Protokolle (Logs).

Meine Hardware

Paperless-ngx läuft bei mir seit mittlerweile mehr als einem Jahr als Container Anwendung auf einem Synology NAS. Die Einrichtung im Container Manager auf Synology DSM ist denkbar einfach und geht relativ schnell von der Hand. Ob Dein Synology NAS kompatibel ist um Paperless-ngx im Container Manager laufen zu lassen kannst Du unter folgendem Link prüfen: 🔗Synology Support

Hinweis: Die mit Sternchen (*) gekennzeichneten Links sind sogenannte Affiliate-Links. Wenn du auf so einen Link klickst und über diesen einkaufst, bekomme ich von dem betreffenden Online-Shop eine Provision. Für dich verändert sich der Preis nicht, aber mit deinem Kauf über diese Links unterstützt du direkt diesen Blog – Danke dir! 🫶

Check nach dem Update & typische Fehlerquellen

Sobald das System läuft, logge dich ein und scrolle ganz nach unten. Dort sollte nun stolz die neue Versionsnummer stehen. Überprüfe kurz, ob alle Dokumente, Korrespondenten, Tags und dein Posteingang intakt sind.

Typische Fehler in der Praxis:

• Fehlende Volumes: Wenn Daten fälschlicherweise im Container statt auf der NAS lagen, sind sie nach dem Löschen weg.
• Datenbank nicht erreichbar: Nutzt du eine externe Datenbank und diese startet nicht schnell genug mit, bricht Paperless den Start ab.
• Fehlerhafte Umgebungsvariablen: Manchmal ändern sich mit neuen Versionen die Bezeichnungen für OCR- oder Redis-Parameter. Ein Blick in die offizielle Dokumentation hilft hier schnell weiter.

Fazit: Keine Angst vor Updates

Ein Paperless-ngx Update ist keine Raketentechnik. Mit einer kurzen Prüfung der Release-Notes auf GitHub, festen Versionsnummern in der Konfiguration und einem frischen Snapshot an deiner Seite verliert das Update jeglichen Schrecken und dein digitales Büro bleibt immer sicher und modern.

Welche Erfahrungen hast du mit Updates bei Paperless-ngx gemacht? Gab es schon mal Probleme? Schreib es mir gerne in die Kommentare!

📹 Das vollständige Video kannst du dir hier anschauen: 🔗Video

❗Gerne darfst du natürllich auch meinen YouTube Kanal ➡️ „Haus und Technik“ besuchen. Dort findest Du weitere spannende Inhalte. Ich würde mich freuen! 😊