Zum Hauptinhalt springen
Version: 19.0

Upgrade von ADONIS 16.0 – 16.7 oder 17.0 – 17.4 auf ADONIS 19.0

Dieses Kapitel beschreibt, wie Sie eine bestehende ADONIS-Installation von 16.0 – 16.7 oder 17.0 – 17.4 auf 19.0 aktualisieren.

Der Upgrade-Prozess unterscheidet sich erheblich von früheren ADONIS-Versionen. In früheren Versionen wurde der Applikations-Server unter Windows betrieben, während der Web-Server auf verschiedenen Plattformen bereitgestellt werden konnte. Ab ADONIS 19.0 werden sowohl der Applikations-Server als auch der Web-Server als containerisierte Services in einer Kubernetes-Umgebung bereitgestellt.

Zur Vereinfachung des Migrationsprozesses stellt ADONIS 19.0 das Management-Tool aupgrade_product bereit. Dieses Werkzeug aktualisiert eine bestehende Datenbank auf die neue Version und führt automatisch die erforderlichen Migrationsschritte aus, einschließlich der Aktualisierung des Datenbankschemas, des Updates der Anwendungsbibliothek, der Ausführung von Migrationsskripten sowie der Sicherung und Wiederherstellung von Komponenteneinstellungen.

Der Migrationsprozess umfasst folgende grundlegenden Schritte:

  1. Stoppen der bestehenden ADONIS-Dienste.

  2. Sichern der deploymentspezifischen Konfigurationsdateien.

  3. Aktualisieren der Datenbank mithilfe von aupgrade_product.

  4. Bereitstellen von ADONIS 19.0 in Kubernetes mithilfe der gesicherten Konfiguration.

  5. Überprüfen der Bereitstellung und Entfernen der alten Installation.

Voraussetzungen​

Bevor Sie ADONIS auf die Version 19.0 aktualisieren, stellen Sie sicher, dass folgende Voraussetzungen erfüllt sind:

  • Sie verwenden ADONIS 16.0 – 16.7 oder 17.0 – 17.4.

  • Ihre Datenbank wird auf einer unterstützten Version von Microsoft SQL Server oder PostgreSQL betrieben.

  • Sie verfügen über Zugriff auf einen Linux-Rechner oder das Windows Subsystem for Linux (WSL), auf dem Docker Engine installiert ist und der Netzwerkzugriff auf den Datenbankserver sowie die BOC OCI Registry hat.

  • Sie verfügen über die erforderlichen Zugangsdaten für den Datenbankserver und über gültige Zugangsdaten für die BOC OCI Registry.

  • Sie verfügen über Zugriff auf eine Kubernetes-Umgebung sowie die erforderlichen Administrationswerkzeuge, einschließlich kubectl und helm.

  • Die Zielumgebung erfüllt die Hardware-/Software-Anforderungen für ADONIS 19.0.

  • Sie kennen das Passwort des ADONIS-Benutzers Admin.

Anwendungsbibliothek für ADONIS 19.0​

Sie können sofort loslegen, wenn Sie die Standardbibliothek verwenden, die mit ADONIS ausgeliefert wird (die ADONIS BPMS Anwendungsbibliothek). Benutzerdefinierte Metamodelländerungen, die auf der Seite Eigenschaften in der ADONIS Administration vorgenommen wurden, beeinflussen das Update nicht – diese Änderungen bleiben erhalten.

Falls Sie eine gecustomizte Anwendungsbibliothek verwenden, beschaffen Sie vor Beginn des Upgrades die entsprechende aktualisierte Version von Ihrem ADONIS-Kundenbetreuer.

Info

Dieses Migrationsverfahren richtet sich an Systemadministratoren mit Zugriff auf die bestehende ADONIS-Installation, die Datenbank und die Ziel-Kubernetes-Umgebung.

Achtung

Erstellen Sie vor Beginn der Migration eine vollständige Sicherung Ihrer Datenbank. Nach erfolgreichem Abschluss des Datenbank-Upgrades kann die aktualisierte Datenbank nicht mehr mit ADONIS 16.0 – 16.7 oder 17.0 – 17.4 verwendet werden.

Dienste stoppen​

Beenden Sie alle laufenden ADONIS-Dienste (Applikations-Server und Web-Server) und stellen Sie sicher, dass keine Benutzer mehr in ADONIS angemeldet sind.

So stoppen Sie die Dienste (in Windows):

  • Öffnen Sie Dienste. Drücken Sie <Windows> + < R>, um das Feld Ausführen zu öffnen, geben Sie services.msc ein, und klicken Sie dann OK.

  • Stoppen Sie den ADONIS Applikations-Server (Service-Name z.B. "ADONISServer17.0Service") und den Apache Tomcat Web-Server (Service-Name z. B. "Tomcat10").

Deploymentspezifische Konfiguration sichern​

Bevor Sie die Datenbank aktualisieren, sichern Sie die deploymentspezifischen Konfigurationsdateien Ihrer bestehenden ADONIS-Installation.

Frühere Versionen von ADONIS speicherten deploymentspezifische Einstellungen in verschiedenen Konfigurationsdateien. In ADONIS 19.0 werden diese Einstellungen nicht mehr in lokalen Konfigurationsdateien verwaltet. Stattdessen werden sie während der Bereitstellung als Konfigurationswerte bereitgestellt.

Die gesicherten Konfigurationsdateien werden daher später bei der Konfiguration der neuen ADONIS 19.0-Bereitstellung benötigt.

ADONIS Applikations-Server Konfiguration​

  • <ADONIS 16.x/17.x Applikations-Server>/conf/server.conf (enthält den Datenbanknamen, und Ports für Applikations-Server oder aworker-Prozesse).

  • <ADONIS 16.x/17.x Applikations-Server>/conf/adoxx.conf (optional, wenn der Standardwert von Parametern geändert wurde)

  • <ADONIS 16.x/17.x Applikations-Server>/conf/log.conf (optional, wenn der Standardwert von Parametern geändert wurde)

Apache Tomcat Konfiguration​
  • <Tomcat>/webapps/ADONIS16|7_x/adoxx_web.properties (enthält die IP-Adresse des Applikations-Servers und die Definition der aworker-Prozesse)
Info

Ändern Sie die gesicherten Dateien nicht. Sie dienen später als Referenz für die Übertragung deploymentspezifischer Einstellungen auf die ADONIS 19.0-Bereitstellung.

Datenbank aktualisieren​

Damit Sie Ihre bestehende Datenbank weiterhin mit ADONIS 19.0 verwenden können, müssen Sie sie mit dem Management-Tool aupgrade_product aktualisieren. Das Tool wird in einem kurzlebigen Docker-Container ausgeführt, der das Applikations-Server-Image von ADONIS verwendet.

Während des Upgrades führt aupgrade_product automatisch alle erforderlichen Migrationsschritte aus. Dazu gehören die Aktualisierung des Datenbankschemas, die Aktualisierung der Anwendungsbibliothek, die Ausführung der erforderlichen Migrationsskripte sowie die Sicherung und Wiederherstellung von Komponenteneinstellungen.

Bevor Sie das Upgrade ausführen, bereiten Sie das Arbeitsverzeichnis vor, stellen Sie die erforderliche Anwendungsbibliothek bereit und erstellen Sie die Konfigurationsdateien, wie in den folgenden Abschnitten beschrieben.

Arbeitsverzeichnis vorbereiten​

Erstellen Sie auf dem Linux-Rechner oder in der WSL-Umgebung, von der aus Sie das Datenbank-Upgrade durchführen, ein Arbeitsverzeichnis. Dieses Verzeichnis enthält die für das Upgrade erforderlichen Konfigurationsdateien sowie die während des Upgrades erzeugten Log-Dateien.

Das folgende Beispiel erstellt das Arbeitsverzeichnis /opt/data/config sowie ein Verzeichnis für die erzeugten Log-Dateien:

mkdir -p /opt/data/config
mkdir -p /opt/data/logs
Hinweis

Die Beispiele in diesem Leitfaden gehen davon aus, dass sich das Arbeitsverzeichnis unter /opt/data/config befindet und die Log-Dateien unter /opt/data/config gespeichert werden. Bei Bedarf können Sie andere Verzeichnisse verwenden.

Anwendungsbibliothek vorbereiten​

Für das Datenbank-Upgrade ist eine Anwendungsbibliothek für ADONIS 19.0 erforderlich. Während des Upgrades aktualisiert aupgrade_product die Anwendungsbibliothek in der Datenbank mithilfe der angegebenen Bibliotheksdatei.

Verwendung der Standardbibliothek​

Wenn Sie die Standardbibliothek (= die ADONIS BPMS Anwendungsbibliothek) verwenden, sind keine weiteren Vorbereitungen erforderlich. Die Bibliotheksdatei ist bereits im Applikations-Server-Image von ADONIS enthalten und befindet sich unter /aserver/data/default.axl.

Verwendung einer gecustomizten Anwendungsbibliothek​

Wenn Sie eine gecustomizte Anwendungsbibliothek verwenden, kopieren Sie die Bibliotheksdatei, die Sie von Ihrem ADONIS-Kundenbetreuer erhalten haben, in das im vorherigen Abschnitt erstellte Verzeichnis /opt/data/config.

Hinweis

Die Beispiele in diesem Leitfaden gehen davon aus, dass sich eine gecustomizte Bibliotheksdatei unter /opt/data/config befindet.

config.json erstellen​

Die Datei config.json steuert die von aupgrade_product durchgeführten Upgrade-Vorgänge. Sie legt fest, ob das Datenbankschema aktualisiert wird, ob Komponenteneinstellungen beibehalten werden und welche Anwendungsbibliothek in die aktualisierte Datenbank importiert wird.

Erstellen Sie die Datei config.json im Verzeichnis /opt/data/config mit folgendem Inhalt:

{
  "skipDbScripts": false,
  "beforePreprocessingScripts": [],
  "preprocessingScripts": [],
  "metamodelScripts": [],
  "migrateCompSettings": true,
  "applicationLibrary": "<bibliotheks-datei-name>",
  "additionalComponentSettings": [],
  "postprocessingScripts": []
}

Die wichtigsten Konfigurationsparameter sind:

  • skipDbScripts: Belassen Sie diesen Wert auf false, damit das Datenbankschema aktualisiert wird.

  • migrateCompSettings: Belassen Sie diesen Wert auf true, damit die Komponenteneinstellungen vor dem Upgrade automatisch exportiert und anschließend wieder importiert werden. Dadurch bleiben Ihre Anpassungen an bibliotheksspezifischen Funktionen erhalten.

  • applicationLibrary: Geben Sie die Anwendungsbibliothek an, die für das Datenbank-Upgrade verwendet werden soll. Wenn Sie die die Standardbibliothek (= die ADONIS BPMS Anwendungsbibliothek) verwenden, geben Sie /aserver/data/default.axl an. Wenn Sie eine gecustomizte Anwendungsbibliothek verwenden, geben Sie deren Dateinamen im Verzeichnis /opt/data/config an, zum Beispiel custom.axl.

Hinweis

Sofern Sie von Ihrem ADONIS-Kundenbetreuer nicht anders angewiesen werden, belassen Sie alle übrigen Konfigurationsparameter unverändert.

aupgrade.env erstellen​

Die Datei aupgrade.env stellt die von aupgrade_product benötigten Umgebungsvariablen bereit. Diese Variablen legen die Quellversion, die Datenbankverbindung, die für das Upgrade erforderlichen Zugangsdaten sowie den Speicherort der Konfigurationsdateien für das Upgrade fest.

Erstellen Sie die Datei aupgrade.env im Verzeichnis /opt/data/config mit folgendem Inhalt und passen Sie die Werte an Ihre Umgebung an:

```
SOURCEVER=<16.x|17.x>
HOST=<datenbank-server>
DBNAME=<datenbank-name>
DBTYPE=<SQLServer|PostgreSQL>
DBPORT=<datenbank-port>
DBADMIN=<datenbank-admin-name>
DBADMINPW=<datenbank-admin-passwort>
ADMINPW=<Admin-passwort>
PARENTPROJCONFFOLDER=/opt/data
```

Die erforderlichen Umgebungsvariablen sind:

  • SOURCEVER: Geben Sie die vollständige Version Ihrer bestehenden ADONIS-Installation einschließlich Major- und Minor-Version an.

  • HOST: Der Hostname Ihres Datenbank-Servers.

  • DBNAME: Der Name der zu aktualisierenden Datenbank.

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

  • DBPORT: Bei Standardinstallationen müssen Sie den Datenbank-Port nicht explizit angeben. ADONIS verwendet automatisch den Standard-Port 5432 für PostgreSQL bzw. 1433 für SQL Server-Standardinstanzen. Geben Sie diese Variable nur an, wenn Ihr Datenbank-Server einen benutzerdefinierten Port oder eine SQL Server-Instanz mit Namen verwendet.

  • DBADMIN: Der Benutzername eines Datenbankadministrators mit ausreichenden Berechtigungen zur Aktualisierung des Datenbankschemas.

  • DBADMINPW: Das Passwort des angegebenen Datenbankadministrators.

  • ADMINPW: Das Passwort des ADONIS-Benutzers Admin.

  • PARENTPROJCONFFOLDER: Das übergeordnete Verzeichnis des Verzeichnisses config, das die Datei config.json enthält. In den Beispielen dieses Guides ist dieser Wert /opt/data.

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 zum Upgrade 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..

Datenbank-Upgrade durchführen​

Nachdem Sie das Arbeitsverzeichnis, die Anwendungsbibliothek und die erforderlichen Konfigurationsdateien vorbereitet haben, führen Sie den folgenden Befehl auf dem Linux-Rechner oder in der WSL-Umgebung aus, um das Datenbank-Upgrade zu starten.

docker run -it --rm \
  --entrypoint "" \
  --env-file aupgrade.env \
  -v /opt/data/logs:/aserver/logs \
  -v /opt/data/config:/aserver/config \
  <boc-registry> \
  sh -c '/aserver/aupgrade_product \
    --srcProductVersion "$SOURCEVER" \
    --id "$DBNAME" \
    --dbInstance "$HOST" \
    --dbType "$DBTYPE" \
    --dbPort "$DBPORT" \
    --dbUser "$DBADMIN" \
    --dbPassword "$DBADMINPW" \
    --adminpw "$ADMINPW" \
    --configRootPath "$PARENTPROJCONFFOLDER"'

Der Befehl startet einen kurzlebigen Docker-Container unter Verwendung des Applikations-Server-Images von ADONIS. Der Container führt aupgrade_product aus, aktualisiert die Datenbank und wird nach Abschluss des Vorgangs automatisch beendet.

Info

Für Microsoft SQL Server verwendet aupgrade_product 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 mehr für Microsoft SQL Server-Datenbanken. Bitte verwenden Sie stattdessen die SQL Server-Authentifizierung.

Die wichtigsten Bestandteile des Befehls sind:

  • --env-file aupgrade.env: Liest die Umgebungsvariablen aus der Datei aupgrade.env.

  • -v /opt/data/logs:/aserver/logs: Speichert die während des Upgrades erzeugten Log-Dateien im Verzeichnis /opt/data/logs auf dem Host-System.

  • -v /opt/data/config:/aserver/config: Stellt die Upgrade-Konfiguration, einschließlich config.json und gegebenenfalls einer gecustomizten Anwendungsbibliothek, für aupgrade_product innerhalb des Containers bereit.

Während des Upgrades führt aupgrade_product folgende Schritte aus:

  1. Aktualisiert das Datenbankschema.

  2. Exportiert die vorhandenen Komponenteneinstellungen.

  3. Aktualisiert die Anwendungsbibliothek in der Datenbank.

  4. Führt die erforderlichen Migrationsskripte aus.

  5. Importiert die Komponenteneinstellungen erneut.

Info

Nach erfolgreichem Abschluss des Datenbank-Upgrades kann die aktualisierte Datenbank nicht mehr mit ADONIS 16.0 – 16.7 oder 17.0 – 17.4 verwendet werden.

ADONIS 19.0 bereitstellen​

Nachdem Sie die Datenbank erfolgreich aktualisiert haben, stellen Sie ADONIS 19.0 in Ihrer Kubernetes-Umgebung bereit.

Hinweis

Stellen Sie ADONIS 19.0 gemäß den Anweisungen in ADONIS bereitstellen bereit.

Stellen Sie während der Bereitstellung die deploymentspezifische Konfiguration Ihrer bisherigen Installation mithilfe der im Abschnitt Deploymentspezifische Konfiguration sichern gesicherten Konfigurationswerte wieder her.

Hinweis

Im Kapitel Deploymentspezifische Konfiguration auf Umgebungsvariablen mappen erfahren Sie, wie die Konfigurationsparameter früherer ADONIS-Versionen auf die Umgebungsvariablen von ADONIS 19.0 mappen.

Bisherige Installation entfernen​

Nachdem Sie ADONIS 19.0 erfolgreich bereitgestellt haben und sichergestellt haben, dass das migrierte System wie erwartet funktioniert, können Sie die bisherige ADONIS-Installation entfernen.

  • Deinstallieren Sie den Applikations-Server von ADONIS 16.0 – 16.7 oder 17.0 – 17.4 vom Windows-Server. Dies können Sie über die Systemsteuerung erledigen.

  • Entfernen Sie die Webapplikation von ADONIS 16.0 – 16.7 oder 17.0 – 17.4 aus Apache Tomcat.