Einführung

Das kostenlose Dokumentenmanagement-System paperless-ngx erfreut sich wachsender Beliebtheit. 
Nachdem mittlerweile einige tausend Menschen anhand meiner Videos, Anleitungen hier auf der Seite, Installationshilfen wie dem Konfigurations-Profil oder gar vollumfassenden Kursen wie der Masterclass paperless-ngx erfolgreich installiert haben, ist es mir natürlich sehr wichtig, euch auch für die Zukunft zu wappnen: Stichwort Datenbank-Update von paperless-ngx.

Grundlagen: So bindet paperless-ngx die Datenbank an

Ich habe bereits ein Grundlagen-Video zu paperless-ngx veröffentlicht, in dem ich vor allem auf den technischen Unterbau eingegangen bin. Dieses Video findest du hier: Technische Grundlagen von paperless-ngx.

Kurz und knapp zusammengefasst werden die meisten Installationen so aussehen: Es gibt eine docker-compose-Datei, die beschreibt, welche verschiedenen Docker-Container wie zusammenarbeiten sollen.
Die wichtigsten Docker-Container für eine paperless-ngx-Installation sind:

• paperless-ngx selbst
• Datenbank (Meist Postgres, aber auch MariaDB oder SQLite möglich)
• Redis (ein Schlüssel-Wert-Speicher, wird für Aufgabenverwaltung genutzt)
• optional: Tika / Gotenberg (für die Verarbeitung von ganzen E-Mails als eml sowie Office-Dokumenten)

Die Konfigurationsdatei wird von den Entwicklern von paperless-ngx gepflegt, ich habe sie angepasst, um direkt auf einem Synology-NAS zu funktionieren (incl. der dafür nötigen Ordner-Struktur). Und in dieser docker-compose.yml (die übrigens Teil des Konfigurations-Profils ist und natürlich auch in der Masterlcass enthalten ist) ist für jeden der Docker-Container eine Version hinterlegt (das sogenannte Tag). Dieses Tag steht hinter dem Doppelpunkt hinter dem Containernamen. 

Schauen wir uns einmal einen Ausschnitt einer solchen docker-compose.yml an: 

version: "3.4"
services:
  broker:
    image: docker.io/library/redis:7
    …
  db:
    image: docker.io/library/postgres:13
    …
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest

Man könnte nun meinen, es würde genügen, einfach das Tag / die Version zu ändern und schon hat man die neueste Datenbank am laufen? Leider wird das in einem Fehler ändern und alle Dokumente sind (erstmal) weg. Nicht machen!

Gründe für den Datenbank-Wechsel

Bevor wir uns anschauen, wie so ein Datenbank-Wechsel sicher durchgeführt werden kann, reden wir noch kurz darüber, warum man so etwas überhaupt macht.

Klar, beim Hauptprogramm paperless-ngx selbst kommen neue Features dazu, die man haben möchte, hier kann man das Update auch sehr einfach durchführen. Aber warum sollte man die Datenbank updaten, wenn doch alles funktioniert?

Wechsel des Datenbank-Systems

Ein möglicher Grund ist der Wechsel des Datenbank-Systems. Wer z.B. mit SQLite gestartet ist und nun ein "richtiges" Datenbank-System wie PostgreSQL oder MariaDB nutzen möchte, der kommt um einen solchen Wechsel nicht herum.

Upgrade des Datenbank-Systems: Sicherheit!

Aber auch ein simples Upgrade des Systems hat einen wichtigen Grund: Security.
Wer ein veraltetes Datenbank-System nutzt, kann unter Umständen sein System angreifbar machen, da es nicht mehr weiterentwickelt wird und Sicherheitslücken nicht mehr geschlossen werden. Warum auch immer du wechseln möchtest, schauen wir uns nun an, wie es geht!

Das Problem: Datenbank-Wechsel nicht einfach möglich

Wie weiter oben schon beschrieben, kann man nicht einfach so das Tag (die Version) der Datenbank auf die neueste Version ändern, ein Pull durchführen und alles läuft.

Docker-Compose würde sonst einfach einen neuen Container starten, also z.B. postgres 16 statt postgres 13 und diesen Container mit paperless-ngx verknüpfen. Leider sind neue Versionen aber nicht kompatibel mit älteren, sodass die Datenbanksoftware mit den Datenbank-Daten nichts anfangen kann und alle Dokumente in paperless-ngx erstmal "weg" wären.

Die Lösung lautet: Sauberer Export aus der alten Datenbank und Import in die neue Datenbank.

Die Lösung: So gelingt der Datenbank-Wechsel

Wir wollen also einmal unsere alte Datenbank exportieren und in unsere neue Datenbank importieren.

Wichtig! Zwischen Export und Import bitte kein Update von paperless-ngx durchführen!

1. Vorbereitungen

Wenn du paperless-ngx auf deinem Synology-NAS anhand meiner Anleitungen oder auch der Masterclass installiert hast, dann musst du nichts weiter tun außer über SSH in den Ordner zu wechseln, in dem auch die docker-compose.yml liegt:

cd /volume1/docker/paperless-ngx/config

2. Export der alten Datenbank

Zum Glück bringt paperless-ngx ein eigenes Werkzeug für den Im- und Export der Datenbank mit. Für den Export führen wir den folgenden Befehl über SSH aus:

sudo docker-compose exec webserver document_exporter ../export

3. Backup durchführen

Ganz wichtig an dieser Stelle: Führe ein Backup durch und nehme die exportieren Daten gleich in dein Backup auf. Die offizielle docker-compose der paperless-ngx-Entwickler eignet sich leider nicht besonders gut für Backups, da die Datenbank nicht in übliche Backups mit eingeschlossen ist. Das Profil, das in der Masterclass enthalten ist, löst dieses Problem, indem die Datenbank direkt im freigegebenen Ordner gespeichert wird und dadurch bei jedem Backup mit erfasst wird.

4. Paperless-ngx stoppen

Nachdem das Backup erfolgreich durchgeführt wurde, können wir paperless-ngx stoppen, um die nächsten Schritte vorzubereiten:

sudo docker-compose down

5. Löschen der alten Datenbank

Als nächstes müssen wir die alte Datenbank und die alten Medien (die eigentlichen PDFs) löschen.

Kunden der paperless-ngx Masterclass haben es hier wieder leicht, ihr löscht einfach die Inhalte der folgenden Ordner im docker-Verzeichnis "paperless-ngx":

• data
• pgdata
• media

Wer von anderen Anleitungen kommt (oder auch das normale Konfigurationsprofil aus dem Shop nutzt), der hat keinen Ordner "pgdata", sondern muss die Datenbank anders löschen:

Herausfinden, welche Docker-Volumes vorhanden sind:

sudo docker volume ls

local     paperless_pgdata

sudo docker volume rm paperless_pgdata

6. Ändern der Versionsnummer

Um Docker-Compose mitzuteilen, dass wir nun eine andere Datenbank-Version nutzen wollen, ändern wir nun in der docker-compose.yml den Eintrag für die neue Datenbank:

db:
   image: docker.io/library/postgres:15

7. Start von paperless-ngx mit der neuen (leeren) Datenbank

sudo docker-compose up

sudo docker-compose down 

sudo docker-compose up -d

Jetzt geben wir dem System nochmal ca. eine Minute, bis paperless im Hintergrund gestartet ist, dann können wir schon den Import durchführen:

8. Import der Datenbank

Paperless-ngx läuft schon, jetzt müssen wir nur noch die alten Datenbank-Daten importieren. Wichtig dabei: die aktuelle paperless-Instanz muss absolut frisch sein, keine Benutzer angelegt, keine Dokumente importiert, sondern genau wie hier beschrieben neu aufgesetzt.

Dann nutzen wir den Importer von paperless-ngx mit:

sudo docker-compose exec webserver document_importer ../export

Der Befehl ist also 1:1 der gleiche wie beim Export, nur dass statt des document_exporters nun der document_importer aufgerufen wird.

Sollten hier Fehlermeldungen auftreten, hast du vermutlich einen der folgenden Ordner nicht wie beschrieben gelöscht:

• media
• data
• pgdata (bzw. das entsprechende Volume, siehe oben)

Weiterführende Hilfe und Diskussion

Wie lief das Upgrade bei dir? Hier geht es zur Diskussion.

Wenn du paperless-ngx wirklich von Grund auf verstehen willst und außerdem sicherstellen willst, dass Backups vollkommen automatisiert und sicher durchgeführt werden, kann ich dir außerdem noch den Videokurs (paperless-ngx Masterclass) ans Herz legen. Dort erkläre ich dir Schritt für Schritt in über drei Stunden, wie du paperless-ngx auf deinem Synology-NAS installierst, alles einrichtest (incl. des Netzwerkscanners) und die Funktionen nutzt.

Hier geht es zur Masterclass!