Umstellung von PPP ab 3.19.x nach PPP 3.23.x - Debian 12.x

zu verschlüsselt

Voraussetzungen prüfen

Prüfen Sie, ob Sie derzeit eine Version der PICTURE-Prozessplattform in Betrieb haben, für welche ein direkter Migrationspfad zur neuesten für Selbsthoster vorliegenden Version 3.23.3 angeboten wird. Das Migrationswerkzeug unterstützt folgende Migrationspfade:

• v3.19.1 → v3.23.3

• v3.21.1 → v3.23.3

Sollten Sie eine ältere Version im Einsatz haben, wenden Sie sich an unseren Support (support@picture-gmbh.de)!

Für die beiden unterstützten Navigationspfade wird eine Migration der bestehenden (Nutz-)Daten benötigt. Bitte führen Sie bei der Umstellung unbedingt die Arbeitsschritte "Probelauf der Bestandsdatenmigration durchführen" und "Bestandsdatenmigration durchführen" aus. 

Ablauf der Umstellung

An dieser Stelle wird der “grobe” Ablauf der folgenden umfangreichen Detail-Anweisungen beschrieben, damit Sie die auszuführenden Schritte in geeignet Weise planen und die notwendigen Kommunikationsmaßnahmen (Wartungsfenster) vornehmen können.

Vorbereitende Maßnahmen

Diese Maßnahmen können Sie unabhängig von der eigentlichen Umstellung des Produktiv-Systems vornehmen.

• Installation einer Minimal-Installation von Debian Linux 12 für die Hardware-Plattform des Zielsystems

• Installation von Drittanbieter-Software mittels Debian-Paketverwaltung

• Konfiguration der Drittanbieter-Software

Probelauf durchführen

Den Probelauf können Sie ohne den Produktiv-Betrieb zu unterbrechen durchführen. Der Probelauf wird durchgeführt, um die ordnungsgemäße Funktionsfähigkeit des Releases zu gewährleisten.

• Datenbank, Dokumente und Versionshistorie für Probemigration sichern

• Download-Paket herunterladen und entpacken

• Probelauf der Bestandsdatenmigration durchführen

Übertragung aller relevanten Daten auf den neuen Server

Führen Sie diese Schritte in einem geeigneten Wartungsfenster (Zeitbedarf ca. 1-2 Stunden) durch. Diese Schritte sind notwendig, um alle relevanten Daten auf den neue Server zu überführen und den Betrieb wiederherzustellen.

• Bestandsdatenmigration durchführen

• Nutzdaten, Konfigurations- / Lizenz-Dateien, sowie Logdateien sichern, auf den neuen Server übertragen und dort wieder einspielen

• Web-Anwendung einspielen

• abschließende Tests durchführen

Neue Minimal-Installation von Debian Linux 12 und Basis-Dienste installieren

Der Betrieb der PICTURE-Prozessplattform erfordert ab Version 3.23 die Neuinstallation eines Debian-12- Systems, sowie neuer Drittanbieter-Software. Bitte folgen Sie exakt den Schritten, die in den folgenden Kapiteln des Leitfadens zur Neuinstallation der PICTURE-Prozessplattform beschrieben sind:

• 2 - Installation von benötigter Drittanbieter-Software (v3.x) - Debian 12.x

• 3 - Konfiguration der Drittanbieter-Software (v3.x) - Debian 12.x.

Nachdem Sie die o.g. Schritte durchgeführt haben, sind die Voraussetzungen für den Betrieb der PICTURE-Prozessplattform 3.23.x geschaffen. Auf dem System sind nun das passende Betriebssystem (Debian Linux 12 “Bookworm”), der fertig eingerichtete Tomcat 10.1.x und die MariaDB-Version 10.11.x installiert, sowie alle benötigten Drittanbieter-Komponenten spezifisch für die PICTURE-Prozessplattform konfiguriert.

In den nachfolgenden Schritten ist beschrieben, wie Sie Ihre Nutzdaten migrieren, sichern und auf den neuen Server übertragen können und anschließend die Installation und Konfiguration der PICTURE-Prozessplattform auf dem neuen Server vornehmen können.

Datenbank, Dokumente und Versionshistorie für Probemigration sichern 

Für die Probemigration der Produktivdaten ist es notwendig, Kopien der folgender Daten anzufertigen: 

• Datenbank-Schema

• Dateiuploads/Versionshistorie

Führen Sie dazu die folgenden Befehle aus: 

In das Home-Verzeichnis wechseln und ein Backup-Verzeichnis anlegen:

Datenbank sichern:

Dokumente und Versionshistorie sichern:

Download-Paket herunterladen und entpacken

Laden Sie das Download-Paket zur aktuellen Version aus unserem Download-Bereich herunter (https://download.prozessplattform.de/ppp/ppp_3-23-3.zip). Der Download-Bereich ist passwortgeschützt. Als registrierter On-Premise-Kunde verfügen Sie über einen individuellen Download-Zugang. Sollten Ihnen die Zugangsdaten hierfür nicht bekannt sein, wenden Sie sich bitte an support@picture-gmbh.de.

Das Download-Paket besteht aus einem ZIP-Archiv, das alle relevanten Programme, Tools und Daten zur Aktualisierung der PICTURE-Prozessplattform enthält. Entpacken Sie dieses nach dem Download in ein temporäres Arbeitsverzeichnis: 

Nach dem Auspacken sollten im Verzeichnis "ppp_[Version]" (z.B. "ppp_3-23-3") folgende Unterverzeichnisse existieren: 

• config_templates: Vorlagen für die Konfigurationsdateien der PICTURE-Prozessplattform-Webanwendung (wird für das Update eines vorhandenen Mandanten nicht benötigt)

• db_template: Datenbankvorlage zum Einrichten eines neuen, "leeren" Mandanten (wird für das Update eines vorhandenen Mandanten nicht benötigt)

• program_files: PPP-Webanwendung sowie Unterverzeichnis mit Datenbankmigrationstool für die Umstellung einer vorhandenen älteren PPP-Version

Probelauf der Bestandsdatenmigration durchführen

Für alle aufgeführten Migrationspfade steht ein Datenmigrationswerkzeug zur Verfügung. Mit dessen Hilfe können sämtliche mit der zuvor installierten Version der PICTURE-Prozessplattform verwalteten Daten ohne Informationsverlust in die neuen Datenstrukturen überführt werden.

Das Migrationsprogramm verfügt über einen integrierten Selbsttest, der im Anschluss an die Migration eine Konsistenzprüfung der Datenbank durchführt. Die ordnungsgemäße Funktionsfähigkeit des Releases können wir nur sicherstellen, wenn diese Konsistenzprüfung ohne Fehler abgeschlossen werden kann. Sollten bei der Prüfung Fehler gefunden werden, empfehlen wir Ihnen daher eine Rücksprache mit unserem Support zwecks Problembehebung.

Datenbank, Dokumente und Versionshistorie für Probelauf einspielen 

An der Datenbank anmelden:

Neues, leeres Datenbank-Schema anlegen und ausloggen:

Datenbank-Snapshot in das neue Datenbank-Schema einspielen:

Dokumente und Versionshistorie aus den zuvor gesicherten Dateien einspielen:

Datenbank-Migrationstool für den Probelauf konfigurieren

Zur Vereinfachung der Ausführung der Migration wurde das Skript "on-premise-db-migration.sh" dem Download-Paket hinzugefügt. Vor dem Starten des Skripts müssen folgende Anpassungen für Ihr System vorgenommen werden.

Datenbank-Einstellung eintragen (db.config)

Öffnen Sie die Datenbank Konfigurations-Datei im Texteditor:

Folgende Werte müssen in der "db.config" enthalten sein und auf Ihre Gegebenheiten angepasst werden:

Datenbankschema eintragen (databases.list)

In der "databases.list" muss das zu migrierende Datenbank Schema eingetragen werden (Hier muss darauf geachtet werden, dass nur das Datenbank Schema in der ersten Zeile eingetragen wird):

Migrations-Skript anpassen (on-premise-db-migration.sh)

Im ersten Abschnitt des Scripts (gekennzeichnet durch den Kommentar "Skript Variablen - bitte passen Sie diese für Ihre individuelle Umgebung an") befinden sich Variablen, die Sie zur Vorbereitung der Probemigration ggf. an Ihre konkreten Gegebenheiten anpassen müssen. Öffnen Sie hierzu die o.g. Datei in einem Texteditor und passen Sie die u.g. Variablen an:

Ggfs. müssen folgende Variablen angepasst werden:

Migration ausführen

Machen Sie das Migrations-Skript anschließend ausführbar: 

Nun können Sie das Skript ausführen und somit die Probemigration starten:

Während der Migration protokolliert das Migrations-Script per Konsolenausgabe den Bearbeitungsfortschritt: 

Log-Auszug

Protokolldatei des Probelaufs der Datenbank-Migration auswerten

Während der Migration wird die Log-Datei "migration_to_3-23-3.log" für die Migration angelegt. Sichten Sie diese Datei nach Abschluss des Migrationslaufs indem Sie den Inhalt der Datei auf der Konsole ausgeben

Prüfen Sie, ob sich hier Hinweise auf Fehler bei der Datenmigration bzw. der anschließenden Konsistenzprüfung finden. Falls ein Migrationsschritt erfolgreich durchgeführt wurde, finden Sie in den Logdateien keine Java-Stacktraces und am Anfang bzw. Ende der Datei finden sich Log-Ausgaben folgender Art:

Auszug migration_to_3-23-3.log

Tomcat-Server herunterfahren

Falls der Probelauf der Datenbank-Migration erfolgreich abgeschlossen werden konnte, können Sie mit der Bestandsdatenmigration der Nutzdaten des Produktivsystems beginnen. Fahren Sie hierzu zunächst den Tomcat-Server herunter (erfordert root-Berechtigung): 

Bestandsdatenmigration durchführen

Datenbank-Schema der Produktiv-Datenbank eintragen (databases.list)

In der "databases.list" muss das zu migrierende Datenbank-Schema eingetragen werden (Hier muss darauf geachtet werden, dass nur das Datenbank-Schema in der ersten Zeile eingetragen wird):

Migrations-Skript an Produktiv-Umgebung anpassen (on-premise-db-migration.sh)

In der "on-premise-db-migration.sh" muss das zu migrierende Verzeichnis der Dokumente und Versionshistorie eingetragen werden:

Nun können Sie das Script ausführen und somit die Migration starten:

Protokolldatei der Bestandsdatenmigration auswerten

Während der Bestandsdatenmigration wird die Log-Datei "migration_to_3-23-3.log" für die Migration fortgeschrieben. Sichten Sie diese Datei nach Abschluss des Migrationslaufs nochmals mit einem Texteditor. Prüfen Sie, ob sich hier Hinweise auf Fehler bei der Bestandsdatenmigration bzw. der anschließenden Konsistenzprüfung finden.

Datensicherung aller relevanten Daten zur Übertragung auf den neuen Server

Für die Überführung der Produktivdaten auf den neuen Server ist es notwendig, Kopien der folgender Daten anzufertigen

• Datenbank-Schema

• Dateiuploads/Versionshistorie

• Konfigurations- und Lizenz-Dateien

• Logdateien

Führen Sie dazu die folgenden Befehle aus: 

In das Home-Verzeichnis wechseln und das Backup-Verzeichnis der Probemigration löschen

Neues Backup-Verzeichnis anlegen

Datenbank sichern

Dokumente und Versionshistorie sichern

Konfigurations- und Lizenz-Dateien sichern

Log-Dateien sichern

Nutzdaten auf den neuen Server übertragen

Übertragen Sie die gesicherten Daten nun auf den neuen Server indem Sie folgenden Befehle auf Ihrem Produktivsystem ausführen:

Nutzdaten wieder einspielen

In diesem Schritt stellen Sie die Nutzdaten auf Ihrem neuen Server wieder her.

Einloggen

Neues, leeres Datenbank-Schema anlegen

Schema erstellen und ausloggen

Datenbank-Snapshot in das neue Datenbank-Schema einspielen

Uploads-Verzeichnis wiederherstellen

Sichern Sie in diesem Schritt die zuvor gesicherten Dateien aus dem Uploads-Verzeichnis zurück. Gehe Sie dazu - wie folgt - vor:

Stellen Sie nach Durchführung der Bestandsdatenmigration sicher, dass das Benutzerkonto, in dessen Namen der Tomcat-Serverdienst ausgeführt wird, die notwendigen Zugriffsberechtigungen für die im Dateisystem gespeicherten Nutzdaten der PICTURE-Prozessplattform aufweist.

Konfigurations- und Lizenz-Dateien wieder einspielen

Im nächsten Schritt stellen Sie das Konfigurationsverzeichnis inkl. der Lizenz-Datei wieder her. Die zuvor gesicherten Daten werden mit den nachfolgenden Befehlen zurück gesichert:

Stellen Sie nach der Durchführung sicher, dass das Benutzerkonto, in dessen Namen der Tomcat-Serverdienst ausgeführt wird, die notwendigen Zugriffsberechtigungen für die im Dateisystem gespeicherten Konfigurationsdateien der PICTURE-Prozessplattform aufweist.

Log-Dateien wieder einspielen

In diesem Schritt werden die gesicherten Log-Dateien wiederhergestellt, damit Sie im Fehlerfall auch historische Log-Dateien zur Verfügung haben. Das Log-Verzeichnis wird mit den folgenden Befehlen zurückgesichert:

Stellen Sie auch hier sicher, dass das Benutzerkonto, in dessen Namen der Tomcat-Serverdienst ausgeführt wird, die notwendigen Zugriffsberechtigungen für die im Dateisystem gespeicherten Log-Dateien der PICTURE-Prozessplattform aufweist.

Schreibzugriff für den Tomcat-Dienst einrichten

Da der Tomcat-Dienst auf einem Debian-System in einem geschützten Bereich ausgeführt wird, ist es notwendig die PICTURE-spezifische Verzeichnisse gesondert freizugeben. Bitte führen Sie dazu die folgenden Schritte aus:

Nun muss noch der System- und Sitzungs-Manager “systemd” veranlasst werden, die soeben geschrieben Konfigurationsdatei zu laden, sowie der Tomcat-Dienst neu gestartet werden:

Download-Paket herunterladen und entpacken

Damit Ihnen auf dem neuen Server die WAR-Datei der PPP-Webanwendung zur Verfügung steht, laden Sie erneut das Download-Paket herunter und entpacken Sie es (vgl. Umstellung von PPP ab 3.19.x nach PPP 3.23.x - Debian 12.x | Download Paket herunterladen und entpacken)

WAR-Datei der Webanwendung einspielen

Kopieren Sie nun die neue WAR-Datei der PPP in das “webapps”-Verzeichnis des Tomcat10-Servers. Führen Sie hierzu folgende Befehle aus: 

"Smoke-Test" durchführen

Ca. 10 - 30 Sekunden nach dem Start des Tomcat-Servers sollte der Tomcat-Server das Deployment der PPP-Webanwendung abgeschlossen haben und Beim Aufruf der URL der Webanwendung im Webbrowser sollte der Login-Bildschirm zur Verfügung stehen.

Falls bereits das Deployment der Webanwendung fehlschlagen sollte, sodass der Login-Bildschirm gar nicht erst aufgerufen werden kann, finden Sie in den folgenden Log-Dateien möglicherweise erste Ansätze zur Fehlersuche: 

• /var/lib/tomcat10/logs/ppp/PPP.log (Logdatei der PPP-Webanwendung; Pfad wird definiert in der Datei logback.xml im Konfigurationsverzeichnis der PPP-Webanwendung)

• /var/lib/tomcat10/logs/catalina.{yyyy-mm-dd}.log (Logdatei des Tomcat-Servers)

• /var/lib/tomcat10/logs/localhost.{yyyy-mm-dd}.log (enthält i.d.R. Hinweise auf schwerwiegende Fehler, derentwegen der Tomcat-Server so früh fehlschlägt, dass in die o.g. Log-Dateien gar nicht erst geschrieben wird).

• /var/lib/tomcat10/logs/localhost_access_log.{yyyy-mm-dd}.txt (enthält die Informationen zu jeder Anfrage, die den Server erreicht. Es kann zum Verfolgen von Seitenzugriffszahlen, Benutzersitzungsaktivitäten usw. verwendet werden, da alle eingehenden Anforderungen zusammen mit Zeitstempel, HTTP-Anforderungsmethode und HTTP-Antwortcode protokolliert werden.)

Erscheint erwartungsgemäß der Login-Bildschirm, dann loggen Sie sich in die PPP ein und prüfen Sie deren prinzipielle Funktionsfähigkeit, in dem Sie zentrale Features stichprobenartig testen: 

• Suche nach Prozessnamen im Prozessregister

• Öffnen eines Prozesssteckbriefs zur Ansicht

• Exportieren des Steckbriefs als PDF-Datei (=> Kann die heruntergeladene PDF-Datei in einem PDF-Reader geöffnet werden und enthält sie keine offensichtlichen Fehler?)

• Öffnen eines Prozess-Detailmodells (Kopie eines "echten" Prozesses bzw. Testdaten) zum Bearbeiten, Änderung durchführen, anschließend speichern

• Ausführen einer Analyse-App und Durchführung eines Excel-Exports (=> Kann die heruntergeladene Excel-Datei in Excel geöffnet werden?)

Aufräumarbeiten

Wenn alle Schritte durchgeführt wurden und die PICTURE-Prozessplattform - wie gewünscht - läuft, nehmen Sie sich nun noch die Zeit das Home-Verzeichnis des User “picture” wieder aufzuräumen. Führen Sie dazu folgende Befehle aus: