Paperless-ngx HowTo: Paperless-ngx an MariaDB und phpMyAdmin binden

[Tommes]

Die Standardinstallation von Paperless-ngx beinhaltet neben dem Schlüssel-Werte-Datenbanksystem Redis auch das relationale Datenbanksystem PostgreSQL (kurz Postgres). Alternativ dazu kann als relationales Datenbanksystem auch MariaDB ab Version 10.4 oder höher genutzt werden, worauf sich die nachfolgende Anleitung bezieht. Dabei wird MariaDB zusammen mit phpMyAdmin, einer Webanwendung zur Verwaltung von MariaDB, in einem separaten Docker-Compose-File bzw. Portainer-Stack, unabhängig von Paperless-ngx eingerichtet. Unter anderem ermöglicht das Abkoppeln des Datenbanksystems von Paperless-ngx, dass sich im späteren Verlauf weitere datenbankgestützte Anwendungen mit der zentral eingerichteten MariaDB-Datenbank verbinden und durch phpMyAdmin benutzerfreundlich administriert werden können.

- Einrichtung von MariaDB und phpMyAdmin​

• Melde dich als Administrator am DSM deines Synology NAS an.
• Öffne die File Station und navigiere zum Ordner /docker
• Erstelle im Docker-Ordner einen neuen Ordner mit dem Namen /mariadb
  (Achte darauf, nur Kleinbuchstaben und keine Großbuchstaben zu verwenden)
  
• Wechsel im Portainer nach Enviroment - Stacks und klicke auf die Schaltfläche + Add stack, um einen neuen Stack anzulegen.
• Gib dem Stack einen eindeutigen Namen wie z.B. mariadb
  (Achte darauf, nur Kleinbuchstaben und keine Großbuchstaben zu verwenden)
• Passe den nachfolgenden Stack ggf. an (beachte dazu auch die nachfolgenden Erläuterungen)
  

  version: "3.0"
  services:
    mariadb:
      image: mariadb:11.3
      container_name: MariaDB
      restart: unless-stopped
      healthcheck:
        test: ["CMD", "healthcheck.sh", "--su-mysql", "--connect", "--innodb_initialized"]
        interval: 30s
        timeout: 30s
        retries: 3
      volumes:
        - /volume1/docker/mariadb:/var/lib/mysql:rw
      environment:
        - MYSQL_ROOT_PASSWORD=123456
        - TZ=Europe/Berlin
        - PUID=1026 # User ID of your Synology NAS Docker administrator
        - PGID=100 # Group ID of your Synology NAS Docker administrator
      ports:
        - 3306:3306
  
    phpmyadmin:
      image: phpmyadmin:latest
      container_name: phpMyAdmin
      restart: unless-stopped
      environment:
        - PMA_PORT=3306
        - PMA_HOST=MariaDB # Name of the MariaDB container
      ports:
  - 2500:80

Erläuterungen zu MariaDB:​

• Passe unter services:mariadb: volumes: ggf. den Pfad zum persistenten MariaDB Verzeichnis an.
• Passe unter services:mariadb: enviroment: das root Passwort [ MYSQL_ROOT_PASSWORD ] an.
• Passe unter services: mariadb: enviroment: ggf. die Timezone [ TZ ] an.
• Passe unter services: mariadb: enviroment: ggf. die Benutzer-ID [ PUID ] sowie die Gruppen-ID [ PGID ] deines Administrators an, welcher Zugriff auf Docker hat.
  Zur Ermittlung der [ PUID ] und [ PGID ] meldet man sich als Administrator über ein Terminal an seinem Synology NAS an und gibt den Befehl id ein
  

  tommes@Synology-NAS:~$ id
  uid=1026(tommes) gid=100(users) groups=100(users),101(administrators)

Erläuterungen zu phpMyAdmin:​

• Passe unter services: phpmyadmin: enviroment: ggf. den Namen [ PMA_HOST ] des MariaDB Container-Namens an, wie unter services: mariadb: [ container_name ] angegeben.
• Öffne nun einen Browser und gib http://synology-nas-ip:2500 ein. Log dich mit dem Benutzernamen root und dem MariaDB Passwort ein.

- Einrichtung von Paperless-ngx​

• Melde dich als Administrator am DSM deines Synology NAS an.
• Öffne die File Station und navigiere zum Ordner /docker
• Erstelle im Docker-Ordner einen neuen Ordner mit dem Namen /paperless-ngx
  (Achte darauf, nur Kleinbuchstaben und keine Großbuchstaben zu verwenden)
• Erstelle innerhalb des Ordners /paperless-ngx sechs weitere Unterordner mit den Namen /config , /consume , /data , /export , /media sowie /redis (siehe Screenshot)
  
• Verbinde dich mit phpMyAdmin (http://synology-nas-ip:2500) und leg ein neues Benutzerkonto mit dem Namen paperless an und vergib ein Passwort.
  Hake des Weiteren unter dem Punkt Datenbank für Benutzerkonto die beiden Kontrollkästchen an (siehe Screenshot)
  
• Klicke anschließend am Ende der Seite auf Okay.
• Wechsel im Portainer nach Enviroment - Stacks und klicke auf die Schaltfläche + Add stack, um einen neuen Stack anzulegen.
• Gib dem Stack einen eindeutigen Namen wie z.B. paperless-ngx
  (Achte darauf, nur Kleinbuchstaben und keine Großbuchstaben zu verwenden)
• Passe den nachfolgenden Stack ggf. an (beachte dazu auch die nachfolgenden Erläuterungen)
  

  version: "3.0"
  services:
    broker:
      image: docker.io/library/redis:7
      container_name: Paperless-ngx-Redis
      restart: unless-stopped
      healthcheck:
        test: ["CMD", "redis-cli", "ping"]
        interval: 30s
        timeout: 10s
        retries: 5
      volumes:
        - /volume1/docker/paperless-ngx/redis:/data
  
    webserver:
      image: ghcr.io/paperless-ngx/paperless-ngx:latest
      container_name: Paperless-ngx
      restart: unless-stopped
      depends_on:
        - broker
      ports:
        - 8100:8000
      healthcheck:
        test: ["CMD", "curl", "-f", "http://localhost:8000"]
        interval: 30s
        timeout: 10s
        retries: 5
      volumes:
        - /volume1/docker/paperless-ngx/data:/usr/src/paperless/data
        - /volume1/docker/paperless-ngx/export:/usr/src/paperless/export
        - /volume1/docker/paperless-ngx/media:/usr/src/paperless/media
        - /volume1/docker/paperless-ngx/consume:/usr/src/paperless/consume
      environment:
        # User settings
        USERMAP_UID: 1026
        USERMAP_GID: 100
        PAPERLESS_ADMIN_USER: tommes
        PAPERLESS_ADMIN_PASSWORD: abcdef
        # Redis settings
        PAPERLESS_REDIS: redis://broker:6379
        # Database settings
        PAPERLESS_DBENGINE: mariadb
        PAPERLESS_DBHOST: 192.168.178.10 # IP address of the Synology NAS
        PAPERLESS_DBNAME: paperless
        PAPERLESS_DBUSER: paperless
        PAPERLESS_DBPASS: 123456
        PAPERLESS_DBPORT: 3306
        # OCR language
        PAPERLESS_OCR_LANGUAGE: deu+eng
        # OCR standard filename format
        PAPERLESS_FILENAME_FORMAT: '{correspondent}/{document_type}/{title}'
        # OCR processing digitally signed PDF documents
        PAPERLESS_OCR_USER_ARGS: '{"invalidate_digital_signatures": true,"continue_on_soft_render_error": true}'

Erläuterungen zu Paperless-ngx:​

• Passe unter services: broker: volumes: ggf. den Pfad zum persistenten Redis Verzeichnis an.
• Passe unter services: webserver: volumes: ggf. die Pfade zu den persitenten Paperless-NGX Verzeichnissen an.
• Passe unter services: webserver: enviroment: ggf. die Benutzer-ID [ PUID ] sowie die Gruppen-ID [ PGID ] deines Administrators an, welcher Zugriff auf Docker hat.
• Passe unter services: webserver: enviroment: den Namen des Datenbank-Benutzers [ PAPERLESS-DBUSER ] sowie das Passwort [ PAPERLESS_DBPASS ] und ggf. den Namen [ PAPERLESS_DBNAME ] der Datenbank an.
• Passe unter services: webserver: enviroment: den Namen [ PAPERLESS_ADMIN_USER ] sowie das Passwort [ PAPERLESS_ADMIN_PASSWORD ] an.
• Passe unter services: webserver: enviroment: ggf. die Timezone [ PAPERLESS_TIME_ZONE ] an.
• Passe unter services: webserver: enviroment: die zu verwendende OCR Sprache [ PAPERLESS_OCR_LANGUAGE ] an.
• Verbinde dich mit Paperless-ngx (http://synology-nas-ip:8100) und meld dich mit deinem Benutzernamen [ PAPERLESS_ADMIN_USER ] sowie dem zugehörigen Passwort [ PAPERLESS_ADMIN_PASSWORD ] an.

- Paperless-ngx Datenbank sichern, wiederherstellen und Speicherort aufräumen​

• Datenbank-Dump der Paperless-ngx Datenbank erstellen​

  #!/bin/bash
  # Datenbank-Dump-File der Paperless-ngx Datenbank erstellen
  # Syntax :
  # docker exec [MARIADB_CONTAINER_NAME] mariadb-dump --user=[PAPERLESS_DBUSER] --password=[PAPERLESS_DBPASS] [DATABASE] > /[DUMPFILE_PATH]/$(date +%Y-%m-%d_%H-%M)_[FILENAME].sql
  
  # Beispiel :
  docker exec MariaDB mariadb-dump --user=paperless --password=abcdef paperless > /volume1/docker/paperless-ngx/export/$(date +%Y-%m-%d_%H-%M)_Paperless-ngx-Dump.sql

• Datenbank-Dump der Paperless-ngx Datenbank wiederherstellen​

  Hinweis: Der Benutzer (paperless) sowie die Datenbank (paperless) müssen bereits im Vorfeld über phpMyAdmin erstellt worden sein.
  

  #!/bin/bash
  # Datenbank-Dump-File der Paperless-ngx Datenbank wiederherstellen
  # Syntax :
  # docker exec -i [MARIADB-CONTAINER-NAME] mariadb --user=[PAPERLESS_DBUSER] --password=[PAPERLESS_DBPASS] [DATABASE] < /[DUMPFILE_PATH]/$(date +%Y-%m-%d_%H-%M)_[FILENAME].sql
  
  # Beispiel :
  docker exec -i MariaDB mariadb --user=paperless --password=abcdef paperless < /volume1/docker/paperless-ngx/export/2024-06-01_19-00_Paperless-NGX_MariaDB_Dump.sql

• Gespeicherte Datenbank-Dump-Files löschen, die älter als x Tage sind​

  #!/bin/bash
  # Gespeicherte Datenbank-Dump-Files löschen, die älter als x Tage sind
  # Syntax :
  # find /[DUMPFILE_PATH]/ -name "*.sql" -mtime +[DAYS] -exec rm {} ;
  
  # Beispiel :
  find /volume1/docker/paperless-ngx/export/ -name "*.sql" -mtime +7 -exec rm {} ;

  
  

  Erläuterungen zum den Scripten:​

  • Ersetzte den Wert [MARIADB_CONTAINER_NAME] mit dem Namen deines MariaDB Containers.
  • Ersetzte den Wert [PAPERLESS_DBUSER] mit dem Benutzernamen deines Paperless-ngx Datenbankbenutzers.
  • Ersetzte den Wert [PAPERLESS_DBPASS] mit dem Passwort deines Paperless-ngx Datenbankbenutzer.
  • Ersetzte den Wert [DUMPFILE_PATH] mit dem Pfad, wo das Dump-File gespeichert werden soll.
  • Ersetzte den Wert [FILENAME] mit dem Dateinamen des Dump-Files.
  • Ersetzte den Wert [DAYS] mit einem Zahlenwert in Tagen, ab wann ältere Dump-Files automatisch gelöscht werden sollen.

Viel Spaß damit

Tommes

 

[Tommes]

Update des Eingangs-Thread!​

Ich habe am Ende dieses HowTo den Abschnitt "Paperless-ngx Datenbank sichern, wiederherstellen und Speicherort aufräumen" hinzugefügt!

Weiterhin viel Spaß mit diesem HowTo

Tommes