Automatisches Erstellen einer Datenbank

Dieses Kapitel führt Sie durch die notwendigen Schritte zur Erstellung einer neuen Datenbank für ADONIS. Sie können die Datenbank automatisch mithilfe einer Umgebungsvariablen-Datei und eines kurzlebigen Docker-Containers erstellen, der aus dem Applikations-Server-Image gestartet wird. Dieses automatisierte Verfahren führt das Management-Tool amain innerhalb des Containers aus, um Ihre Datenbankstruktur bereitzustellen. Im Anschluss wird der Container automatisch gestoppt und wieder entfernt.

Vorbereitung

Um eine BOC Management Office® Datenbank erstellen, benötigen Sie folgende Dinge:

• Einen Datenbankserver mit einer unterstützten Version von Microsoft SQL Server oder PostgreSQL.

• Einen Linux Rechner, oder das Windows Subsystem for Linux (WSL), mit installierter Docker-Engine (der Docker-Daemon) und Netzwerkzugriff auf den Datenbankserver sowie die BOC OCI Registry.

• Zugangsdaten für den Datenbankserver mit der Berechtigung neue Datenbanken anzulegen.

• Die Lizenzdatei, welche Sie von Ihrem ADONIS-Kundenbetreuer erhalten haben.

• Falls Sie nicht die ADONIS BPMS Anwendungsbibliothek verwenden, die kundenspezifische Anwendungsbibliothek, die Sie von Ihrem ADONIS-Kundenbetreuer erhalten haben.

Hinweis

Hinweis für Kubernetes-Anwender: Dieses Verfahren hat sich in der Praxis bewährt und wird in ähnlicher Form von der BOC Group beim Betrieb von ADONIS in der eigenen SaaS-Umgebung auf Basis von Kubernetes eingesetzt. Wenn Sie in Ihrer Kubernetes-Umgebung Docker nicht direkt zur Verfügung haben oder nutzen möchten, können Sie das unten beschriebene Vorgehen sinngemäß abwandeln (z. B. durch das Bereitstellen eines temporären Kubernetes-Pods oder eines Kubernetes-Jobs mit denselben Umgebungsvariablen und Parametern).

Vorbereiten der Daten

Erstellen Sie auf Ihrem Administrationsrechner ein Verzeichnis für die Daten, die zur Erstellung der Datenbank verwendet werden. In diesem Beispiel erstellen wir das Verzeichnis /opt/data/, und verwenden dieses und untergeordnete Verzeichnisse in den Variablen und Befehlen. Falls Sie ein anderes Verzeichnis verwenden, passen Sie die Variablen in der Umgebungsvariablen-Datei und den Teil des Docker Befehls an, welcher Verzeichnisse in den Container einbindet.

• Legen Sie die Datei license.xxl in das Verzeichnis /opt/data/license/

• Falls Sie eine kundenspezifische Anwendungsbibliothek verwenden, legen Sie die Datei library.axl in das Verzeichnis /opt/data/library/

• Erstellen Sie das Verzeichnis /opt/data/logs/. Da der Container am Ende der Ausführung automatisch entfernt wird, müssen die Log-Dateien in dieses Verzeichnis umgeleitet werden und so erhalten bleiben.

Umgebungsvariablen-Datei

Erstellen Sie zunächst eine Umgebungsvariablen-Datei namens amain.env auf Ihrem Administrationsrechner. Diese Datei enthält alle notwendigen Details zur Verbindung mit dem Datenbankserver sowie die Verzeichnisse der Lizenzdatei und Anwendungsbibliothek.

• Erstellen Sie eine reine Textdatei mit folgender Konfiguration und passen Sie die Werte entsprechend Ihrer Umgebung an:

  DBNAME=<mein-datenbank-name>
  DBTYPE=<SQLServer|PostgreSQL>
  DBADMIN=<mein-datenbank-admin-name>
  DBADMINPW=<mein-datenbank-admin-passwort>
  LICENSE=/opt/data/license/license.xxl
  LIBRARY=/aserver/data/default.axl
  PRIMARYLANG=<primärsprache-code>

Hier ist eine Erklärung der erforderlichen Variablen innerhalb der Datei:

• DBNAME: Der Identifikator für die Datenbankverbindung. Bei PostgreSQL- und MSSQL-Bereitstellungen muss dieser im Format Hostname:Datenbankname (z. B. db-server:adonisdb) angegeben werden.

• DBTYPE: Der Typ Ihres Datenbankverwaltungssystems. Unterstützte Werte sind PostgreSQL oder SQLServer.

• DBADMIN: Der Benutzername Ihres Datenbankadministrators, der über ausreichende Berechtigungen zum Ändern des Anwendungs-Datenbankschemas verfügt.

• DBADMINPW: Das Passwort des angegebenen Datenbankadministrator-Benutzers.

• LICENSE: Verzeichnis und Dateiname der Lizenzdatei, welche Sie von Ihrem ADONIS-Kundenbetreuer erhalten haben.

• LIBRARY: Die ADONIS BPMS Anwendungsbibliothek ist bereits im BOC Container Image enthalten. Diese liegt im Verzeichnis /aserver/data/default.axl, Sie müssen daher diesen Pfad nicht anpassen. Falls Sie eine kundenspezifische Anwendungsbibliothek verwenden, ändern Sie die Variable auf /opt/data/library/library.axl

• PRIMARYLANG: Der Sprachcode für die Primärsprache für die Erfassung von Modellen und Objekten. Die Primärsprache dient sowohl als Standard- als auch als Ersatzsprache, wenn ein Text nicht in anderen Sprachen verfügbar ist. Gängige Werte sind je nach Bibliothek und Lizenz en (Englisch), de (Deutsch), fr (Französisch) usw.

Wichtig

Die Verzeichnisse, welche in den o.a. Variablen angegeben werden, sind Verzeichnisse innerhalb des Containers, nicht am Administrationsrechner. In unserem Beispiel verwenden wir der Einfachheit halber die selben Verzeichnisnamen, erstellen also /opt/data/ auf dem Administrationsrechner und binden das Verzeichnis als /opt/data in den Container ein. Dadurch vermeiden wir Probleme durch das Verwechseln von Verzeichnissen innerhalb und außerhalb des Containers.

Anmelden an der BOC OCI Container Registry

Um sich an der BOC OCI Container Registry anmelden zu können, benötigen Sie die Zugangsdaten, welche Sie von Ihrem ADONIS-Kundenbetreuer erhalten haben. Für den Zugriff auf das Image für den temporären Container zur Erstellung der Datenbank ist ein Login erforderlich.

Der einfachste Weg ist über folgenden Standard Docker-Befehl: docker login <boc-registry>. Sie werden nacheinander aufgefordert Ihre Access ID ("Benutzername") und Ihr Access Token ("Passwort") einzugeben.

Achtung

Dieser Befehl speichert die Zugangsdaten im Klartext in der Docker Konfigurationsdatei (Standard: ~/.docker/config.json). Falls Sie die Datenbank für ein neues Deployment ADONIS erstellt haben, können Sie diese Datei verwenden für die Anmeldung von Helm an der BOC OCI Registry und das Erstellen eines ImagePullSecret. Bitte stellen Sie aber sicher, dass diese Datei anschließend sicher gelöscht wird.

Hinweis

Bitte verwenden Sie Zugangsdaten nicht als Parameter im Befehl; die Bash-Historie speichert eine Liste an zuletzt eingegebenen Befehlen und würde damit indirekt die Zugangsdaten im Klartext anzeigen, wenn man die History aufruft..

Ausführen des Befehls zur Datenbankerstellung

Stellen Sie sicher, dass sich die zuvor erstellte Datei amain.env in Ihrem aktuellen Arbeitsverzeichnis befindet. Führen Sie je nach Betriebssystem Ihres Administrationsrechners einen der folgenden Befehle in Ihrem Terminal aus. Falls Sie andere Verzeichnisse als in diesem Beispiel verwenden, passen Sie die Parameter entsprechend an.

docker run -it --rm --entrypoint "" --env-file amain.env -v <logdateipfad>:/aserver/logs -v <datenverzeichnis>:/opt/data <boc-registry>/ADONIS/aserver:19.0.0 sh -c '/aserver/amain --mode install -db "$DBNAME" -dt "$DBTYPE" -dbadmin "$DBADMIN" -dbadminpw "$DBADMINPW" -lic "$LICENSE" -lib "$LIBRARY" -prlang "$PRIMARYLANG"'

docker run -it --rm \
  --entrypoint "" \
  --env-file amain.env \
  -v <logdateipfad>:/aserver/logs \
  -v <datenverzeichnis>:/opt/data \
  <boc-registry>/ADONIS/aserver:19.0.0 \
  sh -c '/aserver/amain \
    --mode install \
    -db "$DBNAME" \
    -dt "$DBTYPE" \
    -dbadmin "$DBADMIN" \
    -dbadminpw "$DBADMINPW" \
    -lic "$LICENSE" \
    -lib "$LIBRARY" \
    -prlang "$PRIMARYLANG"'

Info

Für Microsoft SQL Server verwendet amain standardmäßig verschlüsselte Datenbankverbindungen entsprechend dem Standardverhalten von Microsoft ODBC Driver 18 for SQL Server. Wenn Ihr SQL Server keine verschlüsselten Verbindungen verwendet, geben Sie zusätzlich --encrypt "optional" an. Wenn Ihr SQL Server verschlüsselte Verbindungen mit einem vom Client nicht als vertrauenswürdig eingestuften Serverzertifikat verwendet, müssen Sie gegebenenfalls zusätzlich --trustservercertificate "yes" angeben. Für PostgreSQL sind diese Parameter nicht erforderlich.

Falls das Upgrade aufgrund eines SSL- oder Zertifikatsvalidierungsfehlers fehlschlägt, überprüfen Sie die SQL Server-Verschlüsselungseinstellungen und passen Sie diese Parameter entsprechend an.

Hinweis

ADONIS 19.0 unterstützt keine Windows-Authentifizierung für Microsoft SQL Server-Datenbanken. Bitte verwenden Sie stattdessen die SQL Server-Authentifizierung.

Hier ist eine Erklärung der Platzhalter im Befehl:

• <logdateipfad>: Das Verzeichnis, das Sie für die Logdateien auf dem Administrationsrechner erstellt haben, in unserem Beispiel /opt/data/logs

• <datenverzeichnis>: Das Verzeichnis, welches die Lizenzdatei und die kundenspezifische Anwendungsbibliothek enthält, in unserem Beispiel /opt/data

• <boc-registry>: Die BOC OCI Registry, von welcher Docker das Container Image herunterladen kann.

Dieser Befehl lädt das Container Image aus der BOC OCI Registry herunter, startet einen kurzlebigen Docker-Container und führt den Befehl zum Erstellen der Datenbank aus. Sobald der Befehl abgeschlossen ist, wird der Container automatisch gestoppt und entfernt.

Wichtig

Das Management Tool schreibt Logdateien standardmäßig in das Verzeichnis /aserver/logs im Container. Da dieses Verzeichnis nach dem Beenden des Containers nicht mehr existiert, binden wir das für die Logdateien erstellte Verzeichnis /opt/data/logs auf dem Administrationsrechner und binden es an der Stelle /aserver/logs im Docker-Container ein. Auf diese Weise landen die Logdateien auf dem Administrationsrechner und bleiben nach dem Beenden des Containers erhalten.

Die Datenbank ist nun erstellt und steht für die Verwendung bereit. Sie können für die Erstellung der Datenbank verwendete Dateien, die Sie nicht länger benötigen, nun löschen.

Standardbenutzer

Beim Erstellen der Datenbank wird automatisch ein Benutzer erstellt: Der Benutzer Admin (zu Beginn mit dem Passwort password) ist ein Super-Benutzer zur Administration von ADONIS.