Table of Contents

Entwicklerhinweise

romexis-base/Dockerfile
romexis/Dockerfile
romexis-payload/romexis-versions.env
romexis-payload/romexis-copy-map.tsv
romexis-payload/extract-and-copy-romexis-parts.sh

Aktuelle Ergänzungen der Projektstruktur
Payload-Image-Vertrag
Migrationsarchitektur
Restart-State-Datei
Laufzeitskripte

entrypoint.sh
init-romexis-db.sh
RomexisPropertyAgent.java

Multi-Architektur
Lokaler Entwicklungsablauf
Neue Romexis-Versionen hinzufügen
Installer-Mapping aktualisieren
Registry und CI
Sicherheitshinweise

Deutsch | English

Entwicklerhinweise

Dieses Dokument beschreibt den internen Aufbau des Romexis-Docker-Projekts und erläutert, wie die einzelnen Build-Komponenten zusammenspielen.

Repository-Struktur

Das Projekt ist bewusst in mehrere Schichten aufgeteilt:

romexis-base/
  Stellt die wiederverwendbare Java- und Systemlaufzeit bereit.

romexis/
  Erstellt das eigentliche Romexis-Server-Image aus dem offiziellen Installationspaket.

docker-compose.yml
  Startet bereits erstellte Container-Images.

docker-compose.build.yml
  Erstellt lokale Base- und Server-Images für Entwicklung und Tests.

Durch diese Trennung bleibt das Runtime-Basisimage unabhängig von einzelnen Romexis-Versionen.

Hauptkomponenten

`romexis-base/Dockerfile`

Erstellt das wiederverwendbare Runtime-Basisimage.

Aufgaben:

Bereitstellung einer Java-11-Laufzeit mit JavaFX/OpenJFX-Unterstützung
Installation der SQL-Server-Kommandozeilenwerkzeuge
Installation der Firebird-Clientbibliotheken
Einspielen aktueller Betriebssystempakete und Sicherheitsupdates
Auslagerung gemeinsamer Abhängigkeiten aus dem eigentlichen Server-Dockerfile

Das Basisimage wird architekturspezifisch erstellt:

romexis-base-jre:11-amd64
romexis-base-jre:11-arm64

`romexis/Dockerfile`

Erstellt das eigentliche Romexis-Server-Image.

Hierfür wird ein dreistufiger Build verwendet:

romexis-build
- lädt die benötigten Installationsbestandteile herunter
- extrahiert die erforderlichen CAB-Komponenten
- erstellt die endgültige Verzeichnisstruktur unter /opt/romexis
- lädt die native Chilkat-Bibliothek
agent-build
- kompiliert RomexisPropertyAgent.java
- erstellt RomexisPropertyAgent.jar
Finales Image
- basiert auf dem Romexis-Basisimage
- übernimmt die vorbereiteten Laufzeitdateien
- ergänzt Hilfsskripte und Sicherheitsrichtlinien

`romexis-payload/romexis-versions.env`

Ordnet unterstützte Romexis-Versionen den offiziellen Installer-URLs zu.

Die Schlüssel verwenden Unterstriche anstelle von Punkten:

6_5_3_444_203=https://...

Das Dockerfile akzeptiert auch Versionspräfixe wie:

6.5.3

und löst diese automatisch auf die neueste passende vollständige Version auf.

`romexis-payload/romexis-copy-map.tsv`

Definiert, wie die aus dem Installer extrahierten Komponenten in die endgültige Verzeichnisstruktur kopiert werden.

Format:

Quelle<TAB>Ziel

Beispiel:

Server_jar  /opt/romexis/server
Server_Program_64bit/server/*.xml   /opt/romexis/server

Diese Datei sollte angepasst werden, wenn sich der interne Aufbau des Romexis-Installers ändert.

`romexis-payload/extract-and-copy-romexis-parts.sh`

Verwendet die Mapping-Datei, um:

die benötigten CAB-Hauptkomponenten zu bestimmen,
ausschließlich diese Komponenten mit unshield zu extrahieren,
Dateien und Verzeichnisse an ihre endgültigen Zielorte zu kopieren.

Dadurch bleibt das Dockerfile übersichtlich und enthält keine langen, fest kodierten Kopierketten mehr.

Aktuelle Ergänzungen der Projektstruktur

Das Repository enthält jetzt zusätzlich:

romexis-payload/
  Erstellt wiederverwendbare, versionierte, architekturunabhängige Payload Images aus dem offiziellen Romexis-Installer.

migration-service/
  Stellt Web UI, REST API, SFTP, Validierung und Restore-Orchestrierung bereit.

migration-client/
  Enthält den Windows Client für geführte Migrationen von Quellsystemen.

romexis/Dockerfile ist nicht mehr für Installer-Download und CAB-Extraktion zuständig. Es verwendet das vorbereitete Payload Image und ergänzt nur noch Runtime-spezifische Bestandteile wie Chilkat, Java Agent und Entrypoint-Skripte.

Payload-Image-Vertrag

Ein Payload Image muss bereitstellen:

/opt/romexis
/opt/romexis-mssql-db
/opt/romexis/version
/opt/romexis/server/RomexisServer.jar

Es darf keine architekturspezifischen Runtime-Bibliotheken wie Chilkat enthalten.

Änderungen an romexis-payload/romexis-copy-map.tsv oder den Extraktionsskripten können das Payload aller Versionen verändern. Deshalb baut CI bei Änderungen an dieser Logik alle Payload-Versionen neu.

Migrationsarchitektur

Der Migration Service verwaltet Migrationsjobs als JSON-State-Dateien und stellt temporäre SFTP-Benutzer für aktive Jobs bereit.

Wichtiges Verhalten:

aktive Jobs stellen SFTP-Benutzer beim Service-Start wieder her
completed, cancelled und failed stellen keine SFTP-Benutzer wieder her
Abschluss oder Abbruch eines Jobs entfernt oder deaktiviert den temporären SFTP-Benutzer
der Server besitzt das Manifestformat
Clients liefern Parameter, keine vollständig formatierten Manifeste

Das Restore-Skript erwartet diesen Manifest-Vertrag:

{
  "backup": {
    "file": "database/Romexis_db.bak"
  }
}

Restart-State-Datei

Migration Service und Romexis-Container koordinieren Neustarts über:

/data/romexis_images/.romexis_restart_state

Der Migration Service schreibt eine ausstehende Neustartanforderung, der Romexis-Entrypoint startet den Romexis-Prozess neu und schreibt success oder failed zurück. Der Migration Service liest den finalen Status und entfernt die Datei.

Laufzeitskripte

`entrypoint.sh`

Bereitet die Romexis-Laufzeitumgebung vor.

Aufgaben:

setzt ProgramData=/programdata
initialisiert das persistente sconfig
initialisiert das ProgramData-sconfig
erzeugt die Datenbankverbindungsparameter
bereitet statische Schlüssel und den KeyVault vor
erstellt die benötigten Datenverzeichnisse
aktiviert die Standardkonfiguration des Java-Property-Agents
startet RomexisServer.jar

`init-romexis-db.sh`

Initialisiert die SQL-Server-Datenbank.

Aufgaben:

wartet auf den SQL Server
erstellt die Datenbank, falls sie noch nicht existiert
erstellt den Romexis-Datenbankbenutzer, falls erforderlich
importiert die Romexis-SQL-Skripte
setzt Linux-spezifische Datenpfade in der Datenbank

Das Skript ist idempotent und überspringt die Initialisierung, sobald Datenbank und Benutzer bereits vorhanden sind.

`RomexisPropertyAgent.java`

Ermöglicht das Setzen von RxProperties über Umgebungsvariablen.

Format:

PROPERTY_AGENT_SET_<RXPROPERTY_NAME>=<Wert>

Beispiel:

PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true

Multi-Architektur

Der Build unterstützt:

linux/amd64
linux/arm64

Die Architekturauswahl erfolgt über das Docker-Buildargument TARGETARCH.

Beispiele:

--build-arg TARGETARCH=amd64
--build-arg TARGETARCH=arm64

Die passende Chilkat-Bibliothek wird automatisch anhand von TARGETARCH ausgewählt:

TARGETARCH	Chilkat-Architektur
`amd64`	`x86_64`
`arm64`	`aarch64`

Das finale Basisimage wird ausgewählt über:

ROMEXIS_BASE_IMAGE

Beispiel:

--build-arg ROMEXIS_BASE_IMAGE=romexis-base-jre:11-amd64

Lokaler Entwicklungsablauf

Empfohlener Workflow:

TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d

Logs anzeigen:

docker compose -f docker-compose.build.yml logs -f romexis

Installierte Version prüfen:

docker exec -it romexis-server cat /opt/romexis/version

Neue Romexis-Versionen hinzufügen

Offizielle Installer-URL in romexis-payload/romexis-versions.env ergänzen.
Mit dem neuen Versionspräfix lokal bauen.
Die aufgelöste Version in /opt/romexis/version kontrollieren.
Container starten und Datenbankinitialisierung prüfen.
Verbindung eines Romexis-Clients testen.

Installer-Mapping aktualisieren

Wenn neue Romexis-Versionen andere InstallShield-Komponentennamen verwenden:

CAB-Inhalt untersuchen.
romexis-copy-map.tsv anpassen.
Server-Image neu erstellen.
Prüfen, ob alle benötigten Dateien unter /opt/romexis vorhanden sind.
Extraktionslogik ausschließlich in Mapping-Datei und Hilfsskript pflegen -- nicht im Dockerfile.

Registry und CI

Die Drone-Pipeline veröffentlicht:

romexis-base-jre:11-amd64
romexis-base-jre:11-arm64
romexis-server:<version>-amd64
romexis-server:<version>-arm64
romexis-server:<version>

Die architekturspezifischen Images werden anschließend zu einem Multi-Architektur-Manifest zusammengeführt.

Zur besseren Registry-Kompatibilität werden OCI-Provenance und SBOM im CI deaktiviert:

--provenance=false
--sbom=false

Sicherheitshinweise

Im Repository werden keine Romexis-Programmdateien gespeichert.
Das Installationspaket wird erst während des Builds heruntergeladen.
Laufzeitgeheimnisse sollten über Docker Compose, CI-Secrets oder einen externen Secret-Manager bereitgestellt werden.
Standardkennwörter in den Beispiel-Compose-Dateien müssen vor einem produktiven Einsatz geändert werden.
Vor dem produktiven Einsatz sollten vollständige Backups erstellt werden.