Zielgruppe BetriebVersion: GSB10.1Migrationsanleitung GSB 10.0 -> 10.1

• • 1.1 Datenbanken (allgemeine Hinweise)
  • 1.2. Repository
  • 1.3. Suchindex
  • 1.4. Adminportal
  • 1.5. Serviceportal
  • 1.6. MailDistributor
• 2 Infrastruktur
  • 2.1 Beistellungen
  • 2.2. Runtime

Der GSB 10.1.0 unterscheidet sich aufgrund der Komponentenaktualisierungen stark vom GSB 10.0.x.

Daher empfiehlt sich keine direkte Migration vom GSB 10.0 auf den GSB 10.1 in einer Infrastruktur. Stattdessen sollte für die GSB 10.1.0 Infrastruktur eine neue Infrastruktur aufgebaut werden. Nach Abschluss der Migration kann dann die alte GSB 10.0 Infrastruktur abgebaut werden, da diese nicht weiter benötigt wird.

Dieses Dokument geht von einem parallelen Aufbau einer neuen GSB 10.1.0 Infrastruktur aus.

1.1 Datenbanken (allgemeine Hinweise)

Im GSB 10.1 werden für alle Anwendungen, welche eine Datenbank benötigen, SQL Skripte für MySQL und Oracle bereit gestellt.

Die Dateinamen der Skipte beginnen immer mit Va.b.c_x__. a.b.c ist hierbei die GSB-Version und x ist eine zusätzliche laufende Nummer.

Die V10.0.0_x__*.sql Skripte müssen bei einer Migration von 10.0 auf 10.1 nicht ausgeführt werden. Diese Skripte würden das Datenbank-Schema für einen GSB 10.0 anlegen, welches ja bereits vorhanden ist.

Für die Migration von 10.0 auf 10.1 müssen nur die Skripte ausgeführt werden, deren Namen mit V10.1 beginnen.

1.1.1. Automatisierte Datenbank-Migration mit Flyway

Die SQL-Skripte können auch automatisiert von der Anwendung selbst mit Hilfe von Flyway 5.2.4 ausgeführt werden. Dafür sind die folgenden Schritte notwendig:

Flyway selbst muss im Ordner /opt/gsbos/lib ($GSB_LIB_DIR) - als .jar-Datei - abgelegt werden. Für MySQL und Oracle XE reicht hierbei die kostenlose Version, für eine kommerzielle Oracle Datenbank ist auch die kommerzielle Flyway Variante erforderlich. Die kostenlose Version kann hier herunter geladen werden: https://repo1.maven.org/maven2/org/flywaydb/flyway-core/5.2.4/flyway-core-5.2.4.jar

Die Anwendung muss entsprechend Konfiguriert werden

• Da - im Falle der Migration - bereits Tabellen in der Datenbank vorhanden sind (welche nicht von Flyway angelegt wurden), muss Flyway entsprechend darauf vorbereitet werden:

spring.flyway.baseline-on-migrate=true

spring.flyway.baseline-version=10.0.0_x (1)

• Falls der normale Datenbank Nutzer (datasource.username und spring.datasource.password) nicht die nötigen Rechte hat, um Tabellen anzulegen, zu ändern oder zu löschen, kann hierfür ein separater Nutzer konfiguriert werden:

spring.flyway.user=root

spring.flyway.password=secret

(1)	Hier muss die Version des letzten Skriptes, welches nicht mehr ausgeführt werden muss, eingetragen werden. In der Regel wird dies - im Falle der Migration von 10.0 auf 10.1 - die Version 10.0.0_0 sein.

nach oben

1.2. Repository

Der GSB 10.0 nutzt als Repository die Jackrabbit-Version 2, der GSB 10.1 nutzt die aktuelle Jackrabbit-Version 3, so dass die Repositories vom Jackrabbit 2 in das Jackrabbit 3 Format transformiert werden müssen. Die Migration wird mit Hilfe der Standard Jackrabbit Migration-Tools durchgeführt.

Das genutzte Tool oak-upgrade wird im Release im Artefakt oak-upgrade mit ausgeliefert und kann für eine Migration genutzt werden.

Folgende Schritte sind für die Durchführung der Migration durchzuführen. Die Beschreibung skizziert die Migration für ein MySql basiertes GSB 10.0 Contentrepository. Bei Verwendung einer Oracle-Datenbank müssen die MySql spezifischen Punkte entsprechend an die Anforderungen von Oracle angepasst werden.

1.2.1 Bereitstellung DB-Treiber

Der Datenbanktreiber für die Verbindung zum GSB 10.0 Repository ist im lib-Verzeichnis unterhalb von /opt/gsbos/software/oak-upgrade abzulegen.

1.2.2 Definition JAVA_OPTS

Das Tool oak-upgrade ist eine Java-Applikation, welches über eine Reihe von System-Properties parametriert aufgerufen werden muss. Die Properties repository.db.username, repository.db.password und repository.db.url müssen auf die infstrukturspezfischen Werte angepasst werden. Diese Properties definieren den Zugriff auf die dem GSB 10.0 zugrundeliegende Repository-Datenbank (s.a. repository.system.properties in der exemplarischen Runtime des GSB 10.0).

Das unten aufgeführte Beispiel definiert die Properties entsprechend der im GSB 10.0 Release enthaltenen exemplarischen Runtimekonfiguration.

JAVA_OPTS="-Drepository.cl.nodeId=node1
-Drepository.db.username=repo_preview
-Drepository.db.password=repo_preview
-Drepository.db.url=jdbc:mysql://repository.preview.example.com:3306/repo_preview?serverTimezone=UTC&useSSL=false
-Drepository.db.driver=com.mysql.jdbc.Driver
-Drepository.db.type=mysql -Drepository.lucene.enableConsistencyCheck=true
-Drepository.lucene.forceConsistencyCheck=false
-Drepository.lucene.autoRepair=true
-Drepository.fs.prefix=JR_FS_
-Drepository.ds.prefix=JR_DS_
-Drepository.ds.minRecordLength=1024
-Drepository.ds.maxConnections=10
-Drepository.ds.copyWhenReading=true
-Drepository.ws.prefix=JR_WS_
-Drepository.ws.bundleCacheSize=256
-Drepository.vn.prefix=JR_VN_
-Drepository.vn.bundleCacheSize=128
-Drepository.cl.prefix=JR_CL_"

1.2.3. Blob-Store

Die im Repository abgelegten Binärdokumente werden im sogenannten Jackrabbit Blobstore gespeichert. Der Blobstore muss bei der Migration ebenfalls mit migriert werden. Details zur Migration finden sich im Kapitel "Migrating blob store" der Jackrabbit Oak-Dokumentation.

Für die Migration wird davon ausgegangen, dass

• das GSB 10.1 Repository im Ordner /space/gsbos/data/repositoryoak-preview abgelegt werden soll und
• die GSB 10.0 Installation im Ordner /opt/gsbos/software/repository10/ vorhanden ist.

Das oak-upgrade Tool ist unter den oben skizzierten Voraussetzungen wie folgt zu parametrieren:

UPGRADE="--copy-binaries
--datastore=/space/gsbos/data/repositoryoak-preview/oak/blobs
/space/gsbos/data/repository10-preview/jackrabbit/repository
/opt/gsbos/software/repository10/webapps/repository/conf/repository.mysql.xml
/space/gsbos/data/repositoryoak-preview/oak"

1.2.4. Durchführung der Migration

Die Migration wird mit dem Kommando /opt/gsbos/software/oak-upgrade/bin/oak-upgrade $UPGRADE angestoßen.

Nach Abschluss der Migration durch oak-run liegt des GSB 10.1 Repository im Migration-Ordner /space/gsbos/data/repositoryoak-preview. Für eine produktive Nutzung mit der exemplarischen Runtimekonfiguration des GSB 10.1 Release muss das Repository dann noch in den produktiv genutzten Data-Ordner des jeweiligen Repositories verschoben werden (Ordner /space/gsb/data/repository-preview für das Redaktionssystem).

1.2.5. Workflow

Eine Übernahme der aktuell in der GSB 10.0 vorhandenen redaktionellen Freigabeworkflows wird nicht durchgeführt. Diese müssen bei Bedarf in der neuen Infrastruktur manuell durch die Mandanten gestartet werden.

nach oben

1.3. Suchindex

Das GSB 10.1 Repository wird bei der Migration neu aufgebaut, so dass die migrierten Inhalte über andere Dokument-IDs verfügen. Die Solr Suchindices müssen daher nach der Migration neu aufgebaut werden.

nach oben

1.4. Adminportal

Das Adminportal basiert in der GSB Version 10.1.0 auf dem Liferay-Portal in der Version 7.1. Beim Wechsel von 10.0.x nach 10.1.0l ist eine erneute Einrichtung des Adminportals auf Grundlage einer leeren Adminportal-Datenbank sinnvoll, da das Liferay-Portal in der Major-Version angehoben wurde (von 6.2 nach 7.1). Darüber hinaus unterscheidet sich die Seitenstruktur eines Mandanten in 10.1.x deutlich von der in 10.0.x (Struktur, Single-Views, Nachrichten).

Die Ersteinrichtung sowie die Einrichtung eines neuen Mandanten sind in der Dokumentation zur Einrichtung des Adminportals beschrieben.

Da in der Version 10.1.x eine Trennung der Daten von Adminportal und Serviceportal besteht, müssen die 10.0.x Daten des Serviceportals erst aus der Adminportal-Datenbank extrahiert werden, bevor der alte Datenbestand der Adminportals entfernt werden kann. Hierzu sind die unten genannten Tabellen zu dumpen, damit sie in der Serviceportal-Datenbank wieder importiert und anschließend migriert werden können, was im nächsten Abschnitt (Serviceportal) näher beschrieben wird. Die Daten der folgenden Tabellen sind zu extrahieren und in ein Skript mit DML-Statements zu dumpen.

• spf_document
• spf_event
• spf_gsbindexer
• spf_gsbuser
• spf_guestbook
• spf_guestbookentry
• spf_lrdatatable
• spf_lrdatatableentry
• spf_redojob
• spf_lrroleassignment
• spf_rating
• ddmstructure
• ddlrecordset

nach oben

1.5. Serviceportal

Die Migration des Datenbankschemas bzw. der Daten des Serviceportals aus dem Release 10.0.x wird mit Hilfe eines SQL-Skripts durchgeführt.

Da die Daten des Serviceportals im Release 10.0.x standardmäßig in der Datenbank des Adminportals lagen, wurden die entsprechenden Tabellen im vorherigen Abschnitt in eine Skript-Datei gedumpt, damit sie in der Serviceportal-Datenbank wieder importiert werden können.

Die Serviceportal-Datenbank kann mit dem Skript

../releases/core/10.1.0/infrastructure/sql/<mysql|oracle>/serviceportal/V10.0.0_0__Init.sql

initialisiert werden. Nach Ausführung ist das Schema des Serviceportals der Version 10.0.x in der Datenbank vorhanden, so dass die gedumpten Daten aus der Adminportal-DB importiert werden können. Die eigentliche Migration erfolgt - wie im Kapitel Datenbanken (allgemeine Hinweise) beschrieben - mit Ausführung des Skripts

../releases/core/10.1.0/infrastructure/sql/<mysql|oracle>/serviceportal/V10.1.0_0__Migration.sql

Nach erfolgreicher Ausführung kann das Serviceportal normal gestartet werden.

1.5.1. Datentabellen und Umfragen

Die Datentabellen-Einträge und Umfrage-Ergebnisse werden nicht durch das SQL-Skript migriert, sondern müssen in der Datentabellen-Verwaltung und Umfrage-Verwaltung des "alten" Adminportal exportiert werden und können dann in der Datentabellen-Verwaltung und Umfrage-Verwaltung des "neuen" Adminportals wieder importiert werden.

nach oben

1.6. MailDistributor

Die Migration des Datenbankschemas bzw. der Daten des MailDistributors aus dem Release 10.0.x wird mit Hilfe eines SQL-Skripts durchgeführt.

Das Skript

../releases/core/10.1.0/infrastructure/sql/<mysql|oracle>/maildistributor/V10.1.0_0__Migration.sql

kann im Kontext des vorhandenen Schemas ausgeführt werden.

Falls keine Migration erfolgen soll, da noch keine Newsletter im Mandanten genutzt wurden und / oder eine neue Datenbank aufgesetzt wird, ist vor dem Migrations-Skript zuerst das Initialisierung-Skript

../releases/core/10.1.0/infrastructure/sql/<mysql|oracle>/maildistributor/V10.0.0_0__Init.sql`

auszuführen, dass das Schema in der Release-Version 10.0.x erstellt.

Anwendungsfall	Auszuführende(s) Skript(e)
Migration der Daten von 10.0.x nach 10.1.x	V10.1.0_0__Migration.sql
Neuerstellung des Schemas für 10.1.x	V10.0.0_0__Init.sql V10.1.0_0__Migration.sql

Je nach Datenbankhersteller kann ein SQL-Skript z.B. wie folgt ausgeführt werden:

Migration MailDistributor Datenbank (MySQL)

 mysql -u <user> -p <password> maildistributor < .../releases/core/10.1.0/infrastructure/sql/mysql/maildistributor/V10.1.0_0__Migration.sql

Migration MailDistributor Datenbank (Oracle)

 sqlplus <user>/<password>@<connection> @.../releases/core/10.1.0/infrastructure/sql/oracle/maildistributor/V10.1.0_0__Migration.sql

Nach erfolgreicher Ausführung kann der MailDistributor wie gewohnt gestartet werden.

nach oben

2 Infrastruktur

Durch den parallelen Aufbau der GSB 10.1.0 Infrastruktur zur vorhandenen und zu migrierenden Infrastruktur können Interferenzen durch die parallele Installation und Betrieb in einer Infrastruktur ausgeschlossen werden.

nach oben

2.1 Beistellungen

Die Beistellungen der GSB 10.1.0 Infrastruktur werden wie in der Installationsanleitung beschrieben installiert. Die Systemvoraussetzungen des GSB 10.1.0 sind bei Installation der Beistellungen zwingend zu beachten.

nach oben

2.2. Runtime

Die Runtime-Konfigurationen der GSB Service-Instanzen unterscheiden sich stark zwischen den Versionen GSB 10.0.x und GSB 10.1.0, da der technische Unterbau aufgrund der Komponentenaktualisierungen ein anderer ist und die Properties und -namen aufgrund der Konsolidierung und Homogenisierug der Runtime-Konfiguration z.T. andere sind.

Die Runtime-Konfiguration der neuen GSB 10.1.0 Infrastruktur sollte daher auf komplett neu erstellt werden, indem die exemplarische Runtime Konfiguration des GSB 10.1.0 als Grundlage genommen wird.

Das Ziel der Erstellung der infrastrukturspezifischen Runtime-Konfiguration sollte darin bestehen, möglichst viele Werte der exemplarischen Runtime-Konfiguration zu übernehmen und nur die notwendigen infrastrukturspezifischen Anpassungen vorzunehmen. Hierzu zählen bspw. Servernamen und -Ports unter denen die einzelnen Service-Typen erreichbar sind oder Datenbank-Connect-Strings.

D.h. für die Erstellung der infrastrukturspezifischen Runtime-Konfiguration gilt es die Stellen in der exemplarischen Runtime zu ermitteln, die individualisiert werden müssen. Diese Ermittlung sollte sich einfach durchführen lassen, indem die spezifische Runtime-Konfiguration der GSB 10.0.x Infrastruktur zugrundegelegt wird. Durch Vergleich der infrastrukturspezifischen Runtime mit der exemplarischen Runtime können die Stellen identifiziert werden, die angepasst worden sind.

Das folgende Kommando skizziert die Ermittlung der infrastrukturspezifischen Anpassungen der Runtime-Konfiguration exemplarisch für die Service-Instanz repository-preview

Ermittlung Unterschiede Runtime-Konfiguration

diff -r /opt/gsbos/runtime/repository-preview ~/releases/core/10.0.1/infrastructure/runtime/repository-preview

Der so ermittelte Diff-Output sieht am Beispiel der Runtime-Properties des License-Keys wie folgt aus:

< repository.licenseKey.platformName=customerName
< repository.licenseKey.expireDate=01.01.2020
< workflow.rest.url.base=http://workflow.mydomain.de:6021/engine-rest
...
> repository.licenseKey.platformName=
> repository.licenseKey.expireDate=
> workflow.rest.url.base=http://workflow.preview.example.com:6021/engine-rest

Die Zeilen mit einem führenden > enthalten den Propertynamen und Wert der exemplarischen Runtime und die Zeilen mit dem führenden < enthalten die infrastrukturspezifischen Werte.

Im skizzierten Beispiel muss also für repository.licenseKey.platformName in der Runtime der neuen GSB 10.1.0 Infrastruktur der Wert customerName und für …​expireDate der Wert 01.01.2020 gesetzt werden.

In der Runtime Property workflow.rest.url.base ist der Name des Workflowservers von workflow.preview.example.com auf workflow.mydomain.de geändert worden. Der Port (6021) hingegen ist nicht angepasst worden.

In der Runtime der neuen GSB 10.1.0 Infrastruktur können anschließend alle Vorkommen von workflow.previwe.example.com durch workflow.mydomain.de ausgetauscht werden.

Mit dem skizzierten Vorgehen sollte sich die benötigte Runtime für die geplante GSB 10.1.0 Infrastruktur auf Basis und Grundlage der exemplarischen Runtime-Konfiguration des GSB 10.1.0 einfach erstellen lassen.

Hinweis:
Die plattformspezifischen Lizenzinformationen des GSB 10.0.0 können im GSB 10.1.0 weiterverwendet werden. D.h. es muss kein neuer Lizenzschlüssel für die GSB 10.1.0 Infrastruktur angefordert werden.

nach oben