Paperless-ngx auf Synology-DiskStations

Paperless-ngx – Ein Sammelthread für ein DMS via Docker auf dem NAS

Aktuelle Version von Paperless-ngx

2.14.7

Features

• Enhancement: require totp code for obtain auth token by @shamoon in #8936

Bug Fixes

• Enhancement: require totp code for obtain auth token by @shamoon in #8936
• Fix: reflect doc links in bulk modify custom fields by @shamoon in #8962
• Fix: also ensure symmetric doc link removal on bulk edit by @shamoon in #8963
  

Was ist Paperless-ngx?

Paperless-ngx ist ein Fork von Paperless-ng, einem Dokumentenmanagementsystem (DMS), welches als Container unter Docker/Container Manager (ab DSM 7.2) läuft. Zusammen mit einem Scanner könnt ihr euer Büro zu Hause papierlos machen und findet über Schlagwörter schnell die Dokumente, die ihr sucht. Eigentlich können gescannte Dokumente auch nummeriert werden, sodass ihr sie auch im Original schnell wiederfindet, wenn ihr sie doch mal brauchen solltet.

Ist Paperless-ngx überhaupt etwas für mich?

Das kann man natürlich immer nur für sich selbst beantworten. Manche Personen greifen lieber direkt auf ihre Dokumente in den Ordnern zu, für diejenigen ist vielleicht synOCR besser geeignet. Wer Paperless-ngx nutzen möchte, sollte die gesamte Verwaltung von dem Programm machen lassen und Änderungen nur über die Oberfläche vornehmen. Die Dateien lassen sich trotzdem ohne große Probleme aus der Ordnerstruktur heraus kopieren oder über die Oberfläche herunterladen.

Wer noch weitere Gedanken zur Entscheidung braucht, dem sei der Thread Paperless-ngx: Ein kurzer Erfahrungsbericht sowie ein erstes Resümee von Tommes empfohlen. Dort wird über viele Fragen diskutiert, die immer mal wieder hier im Forum aufkommen, weil Paperless-ngx schon eine feine Sache, aber nicht für jede Arbeitsweise geeignet ist. Solche Fragen sollte man jedenfalls klären, bevor man die ersten 1000 Dokumente verarbeitet 😉

Wie installiere ich Paperless-ngx?

Wie so oft bei Docker gibt es hier unterschiedliche Herangehensweisen. Man kann für die Verwaltung aller seiner Container andere Containerdienste wie Portainer verwenden oder auch den Container-Manager vom Synology selbst; allerdings verwende ich selbst ausschließlich die Konfigurationsdateien im YML-Format. Deswegen beachtet bitte, dass beispielsweise Anleitungen von Magnus auf seiner Seite Magnus Hosting ein wenig anders aussehen als das, was ihr hier seht.

Ordner und Konfigurationsdatei erstellen

Geht zu Eurem Docker-Ordner (meistens: /volume1/docker) und erstellt einen Unterordner /paperlessngx und innerhalb des Ordners noch die Ordner:

• config
• consume
• data
• export
• exportpostgres
• media
• pgdata
• redis

Hier werden die Daten außerhalb des Containers gespeichert, das ermöglicht Euch, bei Problemen im Zweifelsfalle den ganzen Ordner wieder zu kopieren und nach Eingabe der Befehle unten dort weiterarbeiten zu können.

Dann wenden wir uns der Konfigurationsdatei zu. Die Macher von Paperless-ngx haben dazu auf der GitHub-Seite bereits mehrere Beispiele veröffentlicht. Im Zweifelsfalle nehmt einfach eine der vorhandenen Dateien, man kann diese jederzeit nachträglich an seine Bedürfnisse anpassen. Erstellt werden

• docker-compose.yml
• docker-compose.env

Und zwar im Ordner config. Die env-Datei kann man auch anders benennen, dann muss die entsprechende Zeile in der yml halt anpassen. Für die yml-Datei nutze ich folgende Einstellungen:

version: "3.6"
services:
  broker:
    container_name: redis
    image: redis:latest
    restart: unless-stopped
    volumes:
      - ../redis:/data

  db:
    container_name: postgres
    image: postgres:15
    restart: unless-stopped
    volumes:
      - ../pgdata:/var/lib/postgresql/data
      - /volume1/docker/paperlessngx/exportpostgres:/var/lib/postgresql/data/backup
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless

  webserver:
    container_name: paperlessngx
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - 34343:8000
    healthcheck:
      test: ["CMD", "curl", "-fs", "-S", "--max-time", "2", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 5
    volumes:
      - ../data:/usr/src/paperless/data
      - ../media:/usr/src/paperless/media
      - ../export:/usr/src/paperless/export
      - ../consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db

Sehr wichtig ist es hier, die Version der Datenbank festzuschreiben, wenn ihr Postgres verwendet. Solltet ihr die Version hier nicht festlegen, zumindest auf die Hauptversion, dann wird es bei einem Wechsel auf die nächste Hauptversion, nach meiner Anleitung wäre das Version 16, dazu kommen, dass die Datenbank nicht mehr erreichbar ist. Da müsst ihr wirklich aufpassen. Im schlimmsten Fall zerschießt ihr euch die komplette Datenbank. Und wenn ihr dann keine Sicherung habt, dann könnt ihr die ganze Installation neu aufsetzen. Auch bei Paperless gilt, Backup ist Trumpf!

Einrichtung via Terminal bzw. Aufgabenplaner

Die nächsten Schritte nehmt Ihr im Terminal (macOS) bzw. der Konsole (Windows) vor via SSH (Systemsteuerung → Terminal/SSH, orange) oder ihr nutzt einfach den Aufgabenplaner unter DSM. Den findet Ihr unter Systemsteuerung → Aufgabenplaner, rot. Folgende Befehle bitte dort eingeben, sudo erfordert das Admin-Passwort oder Ihr loggt Euch direkt als root ein. Die Konfiguration habe ich selbst über das Terminal/Konsole gemacht.

1. cd /volume1/docker/paperlessngx/config
2. sudo docker-compose pull
3. sudo docker-compose run --rm webserver createsuperuser
4. sudo docker-compose up -d

Folgendes machen die Befehle dabei:

1. Navigiert in das entsprechende Verzeichnis (cd → «change directory»)
2. „Pullt“ das/die entsprechenden Images, lädt also hier Paperless, redis und PostgreSQL in der festgelegten Version herunter.
3. Erstellt einen Admin – das habe ich nicht über den Aufgabenplaner ausgeführt, da fehlt die entsprechende Eingabemöglichkeit!
4. Startet die Container

Wenn alles geklappt hat, findet Ihr nach der Anleitung oben Paperless unter http://domain:34343. Den Port 34343 könnt Ihr logischerweise anpassen.

Das „leidige“ Thema PostgreSQL-Updates…

Grundsätzliches

Immer wieder wird die Frage gestellt, wie im Zusammenhang mit Paperless-ngx eine Datenbankversion aktualisiert werden kann nach einem Major Update, wenn als Datenbank PostgreSQL zum Einsatz kommt. Da der ganze Vorgang nicht trivial ist und ich bei meinem Update von Version 15 auf 16 die eine oder andere Hürde gefunden habe, für die ich mir diverse Tips hier zusammengesucht habe nunmehr ein Versuch, das ganze in einer ausführlichen Anleitung zusammenzufassen.

Stand 2. Februar 2024 ist die aktuellste Major Version von PostgreSQL v16, unterstützt und weiter mit Updates versorgt werden noch v12–v15. v11 hat im November 2023 das letzte Update erhalten. Folgende Versionen von PostgreSQL sind innerhalb ihrer Major Version derzeit aktuell:

• 9. November 2023: 16.1, 15.5, 14.10, 13.13, 12.17 und 11.22 ( EOL)

Anbei ein Bild, wo ihr, egal welcher Tag gesetzt wurde, seht, welche Version Eure Datenbank gerade verwendet.

Auch wenn Updates immer eine sinnvolle Sache sind, so sei an dieser Stelle zunächst auch erwähnt, dass ein Update der Datenbank-Version keinerlei Vorteile im Betrieb von Paperless-ngx mit sich bringt. Neue Funktionen gibt es mit dem Update des Webservers, solange eine alte Version nicht zu Problemen führt, kann diese auch weiterverwendet werden.

Wer erst mit Paperless-ngx startet, dem sei auch empfohlen, von Beginn an auf MariaDB als Datenbank zu setzen; wer bisher PostgreSQL einsetzt und gerne auf MariaDB wechseln möchte, dem sei diese Anleitung von @Adama ans Herz gelegt: Paperless-ngx: Migration Postgresql zu MariaDB. Bei großen Versionsupdates der MariaDB sind hier im Forum bisher keine Probleme bekannt und das im Vergleich umständliche Prozedere unten entfällt.

Grundlagen

Bevor ich beginne, möchte ich ein paar Begriffe klären, damit es nachher nicht zu Missverständnissen kommt bzw. ihr wisst, was ihr wo mit eventuell anderen Bezeichnungen ersetzen müsst.

• Verwende ich PGDBNAME, so ist der Name eures PostgreSQL-Containers gemeint. Verwendet ihr paperless-ngx-db, nutzt ihr also diesen Namen.
• Verwende ich PGUSER, ist der Name gemeint, der in Eurer Installation für die Anmeldung an der PostgreSQL-Datenbank verwendet wird. Standardmäßig ist das in der yaml-Beispielsdatei paperless

Dann möchte ich grundsätzlich anmerken, dass ich die ganzen Befehle in der Regel über mein Terminal absetze, weil ich dort sofort das Ergebnis sehe. Die ganzen Befehle können aber selbstverständlich auch über den Aufgabenplaner eingegeben werden, dann erhaltet ihr je nach eurer Einstellung die Antwort per Mail. Das erschwert bei Problemen aber im Zweifelsfall die Ursachenfindung.

Anleitung

Vor solchen Arbeiten solltet ihr sicherstellen, dass hier ein aktuelles und funktionierendes Back-up eurer Installation habt. Kein Backup → kein Mitleid

1. Stoppt die Container des Webservers und des Brokers (redis), um zu verhindern, dass weitere Daten in die Datenbank geschrieben werden können (der PostgreSQL-Container muss weiterlaufen, weil sonst kein „Dump“ erstellt werden kann)
2. Erstellt einen so genannten „Dump“, also eine Sicherung der Datenbank mit folgendem Befehl: docker exec PGDBNAME bash -c "psql -U PGUSER > /var/lib/postgresql/data/backup/backup.dump"
3. Stoppt den PostgreSQL-Container und benennt den bisherigen Ordner (z. B. /pgdata) um, der Einfachheit halber etwa pgdatav15 für die alte Version und erstellt /pgdata neu. Der Ordner muss (!) leer sein!
4. Passt in der Konfiguration (yaml) die Version von PostgreSQL an (z. B. auf postgres:16) (*1)
5. Startet zunächst nur die Datenbank neu, in dem ihr in den Ordner navigiert cd /volume1/docker/paperless/oder/so und dann folgenden Befehl ausführt docker-compose up -d db
6. Kopiert den Backup-Ordner mit dem Dump in /pgdata
7. Führt folgenden Befehl aus docker exec PGDBNAME bash -c "psql -U PGUSER < /var/lib/postgresql/data/backup/backup.dump", danach seht ihr im Terminal, wie die Daten eingelesen werden
8. Wenn der Befehl ohne Fehler durchgelaufen ist, startet Webserver und Broker erneut: docker-compose up -d

Danach solltet ihr euch mit den bekannten Anmeldedaten wieder anmelden können. Wird die Anmeldeseite geladen, funktioniert das Anmelden aber nicht mit Verweis auf falsche Anmeldedaten, dann hat das zurückspielen der Datenbank nicht funktioniert.

Zusätzliche Links

Folgende zusätzliche Links können euch helfen, wenn ihr doch mal an Probleme kommt, die ihr so nicht klären könnt:

• MariusHosting (Marius Bogdan Lixandru): How to Install Paperless NGX on Your Synology NAS
• Digitalisierung mit Kopf (Stefan Lachner)
  • Paperless-ngx: Automatische Texterkennung (OCR) in Scans mit Synology NAS / Raspberry Pi
  • Paperless-ngx auf Synology-NAS installieren: Schritt-für-Schritt-Anleitung (papierloses Büro)
  • HTTPS: Paperless-ngx aus dem Internet erreichbar machen mit Synology NAS