From de1c0a9a3e26153276739a7a77c6aa22f8f9c8bf Mon Sep 17 00:00:00 2001 From: Patrick Gniza Date: Mon, 29 Jun 2026 06:20:15 +0000 Subject: [PATCH] =?UTF-8?q?Reference=20README.de=20hinzugef=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Reference-README.de.md | 595 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 595 insertions(+) create mode 100644 Reference-README.de.md diff --git a/Reference-README.de.md b/Reference-README.de.md new file mode 100644 index 0000000..ca36c16 --- /dev/null +++ b/Reference-README.de.md @@ -0,0 +1,595 @@ +# Romexis Docker + +[English](README.md) | [Deutsch](README.de.md) | [Build-Prozess](BUILD.de.md) | [Entwicklerdokumentation](DEVELOPERS.md) | [![Build Status](https://drone.buchhorster.de/api/badges/patrick/romexis-server-docker/status.svg?ref=refs/heads/main)] + +> Containerisierte Ausführung von Planmeca Romexis Server 6.5 unter Linux mit Docker, Microsoft SQL Server und einem wiederverwendbaren Multiarch-Romexis-Basisimage. + +--- + +## Überblick + +Dieses Projekt baut und betreibt den Planmeca Romexis Server in Docker. + +Der Build-Prozess extrahiert die benötigten Romexis-Serverdateien direkt aus dem offiziellen Romexis-Windows-Installer. Im Repository werden keine Romexis-Programmbinaries gespeichert. + +Der aktuelle Build ist in Payload-, Base- und Server-Image-Schichten aufgeteilt: + +1. **Romexis Base Image** + - Stellt Java 11 mit JavaFX-Unterstützung bereit. + - Enthält Microsoft SQL Server Kommandozeilenwerkzeuge. + - Enthält Firebird-Clientbibliotheken. + - Wird separat für `amd64` und `arm64` gebaut. + +2. **Romexis Server Image** + - Baut auf dem Romexis Base Image auf. + - Lädt und extrahiert den ausgewählten Romexis-Installer. + - Erstellt die finale `/opt/romexis`-Verzeichnisstruktur. + - Fügt Java Property Agent, Laufzeitskripte und Datenbankinitialisierung hinzu. + +Diese Trennung reduziert Duplikate, vereinfacht die Wartung und erlaubt die Wiederverwendung des Laufzeit-Basisimages für unterschiedliche Romexis-Versionen. + +--- + +## Features + +- Romexis Server 6.5 in Docker +- Microsoft SQL Server 2022 Unterstützung +- Automatische Datenbankinitialisierung +- Persistente Speicherung aller Nutzdaten +- Automatische Vorbereitung von KeyVault und ProgramData +- Unterstützung vorhandener Datenbank-Volumes +- Multi-Stage Docker Build +- Multiarch-Image-Publishing für `amd64` und `arm64` +- Dediziertes wiederverwendbares Romexis Base Image +- Mapping-basierte Installer-Extraktion über `romexis-copy-map.tsv` +- Selektive InstallShield-CAB-Extraktion +- Romexis-Installerversionen werden über `romexis-versions.env` verwaltet +- Keine Windows Registry erforderlich +- Kein RomexisConfig-Aufruf erforderlich +- Linux-kompatible Laufzeitpfade +- Java-Property-Injection über `RomexisPropertyAgent` +- CI/CD Build-Unterstützung über Drone + +--- + +## Architektur + +```text ++----------------------+ +| Romexis Clients | ++----------+-----------+ + | + | RMI / Romexis-Protokollports + v ++----------------------+ +| Romexis Server | +| Docker | ++----------+-----------+ + | + | JDBC + v ++----------------------+ +| Microsoft SQL Server | +| Docker | ++----------------------+ +``` + +--- + +## Unterstützte Plattformen + +Der Build-Prozess unterstützt folgende Zielarchitekturen: + +| Architektur | Docker-Plattform | Tag-Suffix | +|------------|------------------|------------| +| x86_64 | `linux/amd64` | `-amd64` | +| ARM64 | `linux/arm64` | `-arm64` | + +Die Drone-Pipeline erstellt architekturspezifische Images und veröffentlicht anschließend ein Multiarch-Manifest ohne Architektur-Suffix. + +--- + +## Voraussetzungen + +### Laufzeithost + +- Linux-Host +- Docker Engine +- Docker Compose Plugin +- Netzwerkverbindung zwischen Romexis-Clients und den veröffentlichten RMI-Ports + +### Build-Host + +- Docker Engine mit BuildKit-Unterstützung +- Docker Buildx +- Docker Compose Plugin +- Zugriff auf die Romexis-Installer-Download-URLs aus `romexis-payload/romexis-versions.env` +- Zugriff auf die konfigurierte Container-Registry +- Ausreichend Speicherplatz für Installer-Extraktion und Docker-Build-Cache + +### Empfohlene Ressourcen + +- 8 GB RAM +- 4 CPU-Kerne +- 20 GB freier Speicherplatz für den Betrieb +- Zusätzlicher freier Speicherplatz auf Build-Hosts für Build-Cache und extrahierte Installerdateien + +--- + +## Container Images + +Die Images werden in der Gitea Container Registry des Projekts veröffentlicht. + +### Image-Struktur + +```text +gitea.buchhorster.de/patrick/romexis-base-jre:11-amd64 +gitea.buchhorster.de/patrick/romexis-base-jre:11-arm64 + +gitea.buchhorster.de/patrick/romexis-server:-amd64 +gitea.buchhorster.de/patrick/romexis-server:-arm64 +gitea.buchhorster.de/patrick/romexis-server: +``` + +Die architekturspezifischen Tags werden für das Multiarch-Manifest verwendet. + +### Beispiel-Pull + +```bash +docker pull gitea.buchhorster.de/patrick/romexis-server:6.5.3.444.203 +``` + +### Installierte Romexis-Version prüfen + +```bash +docker run --rm \ + --entrypoint cat \ + gitea.buchhorster.de/patrick/romexis-server:6.5.3.444.203 \ + /opt/romexis/version +``` + +--- + +## Versionsverwaltung + +Die Datei `romexis-payload/romexis-versions.env` ordnet unterstützte Romexis-Versionen den offiziellen Installer-URLs zu. + +Beispiel: + +```text +6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip +6_5_2_189_213=https://content.planmeca.com/files/Planmeca_Romexis_6.5.2.189.213_Win.zip +``` + +Das Build-Argument `ROMEXIS_VERSION` kann eine vollständige Version oder ein Präfix enthalten. + +Beispiel: + +```bash +ROMEXIS_VERSION=6.5.3 +``` + +Der Build löst dies zur neuesten passenden Version auf, zum Beispiel: + +```text +6.5.3.444.203 +``` + +Die aufgelöste Version wird im Image gespeichert: + +```text +/opt/romexis/version +``` + +--- + +## Projektstruktur + +```text +. +├── docker-compose.yml +├── docker-compose.build.yml +├── README.md +├── README.de.md +├── BUILD.md +├── BUILD.de.md +├── DEVELOPERS.md +│ +├── romexis-base +│ └── Dockerfile +│ +├── romexis +│ ├── Dockerfile +│ ├── entrypoint.sh +│ ├── fix-keystore-alias.sh +│ ├── init-romexis-db.sh +│ ├── RomexisPropertyAgent.java +│ ├── +│ +└── data + ├── programdata + ├── sconfig + ├── romexis_images + ├── romexis_cache + └── romexis_ergodata +``` + +--- + +## Betrieb mit fertigen Images + +Für den normalen Betrieb wird `docker-compose.yml` verwendet. + +```bash +ROMEXIS_VERSION=6.5.3.444.203 docker compose up -d +``` + +Logs anzeigen: + +```bash +docker compose logs -f +``` + +Nur Romexis: + +```bash +docker compose logs -f romexis +``` + +Nur SQL Server: + +```bash +docker compose logs -f mssql +``` + +Umgebung stoppen: + +```bash +docker compose down +``` + +--- + +## Lokaler Build mit Docker Compose + +Für lokale Builds wird `docker-compose.build.yml` verwendet. + +Das Base Image muss vor dem Romexis Server Image gebaut werden, da das Server-Dockerfile das Basisimage über das Build-Argument `ROMEXIS_BASE_IMAGE` verwendet. + +```bash +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 +``` + +Für einen ARM64-Build-Host: + +```bash +TARGETARCH=arm64 docker compose -f docker-compose.build.yml --profile build build romexis-base +TARGETARCH=arm64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis +``` + +Weitere Details stehen in [BUILD.de.md](BUILD.de.md). + +--- + + +--- + +## Aktueller Architekturstand + +Das Projekt verwendet inzwischen drei Build-Schichten statt nur Base- und Server-Image: + +1. **Romexis Payload Image** + - wird aus `romexis-payload/Dockerfile` gebaut + - lädt und extrahiert den offiziellen Romexis-Installer + - enthält `/opt/romexis` und `/opt/romexis-mssql-db` + - ist architekturunabhängig und wird als `romexis-payload:` getaggt + +2. **Romexis Base Image** + - wird aus `romexis-base/Dockerfile` gebaut + - enthält Java, JavaFX, SQL-Tools und gemeinsame Runtime-Bibliotheken + - ist architekturspezifisch + +3. **Romexis Server Image** + - wird aus `romexis/Dockerfile` gebaut + - verwendet Payload Image und Base Image + - ergänzt Chilkat, Java Property Agent, Laufzeitskripte und Startlogik + +Durch das Payload Image müssen Installer-ZIP und CAB-Dateien nicht bei jedem Server-Build erneut heruntergeladen und extrahiert werden. + +--- + +## Migration Service + +Das Repository enthält jetzt einen Romexis Migration Service und einen Windows Migration Client. + +Der Migration Service stellt bereit: + +- Web UI und REST API für Migrationsjobs +- temporäre SFTP-Zugangsdaten pro Job +- Datenbankbackup-Upload über den Browser +- automatische serverseitige `manifest.json`-Erzeugung +- SQL Server Datenbank-Restore +- Upload-Validierung +- Datei-Restore-Workflow +- Abbruch und Bereinigung von Migrationen +- Abschluss einer Migration mit Entfernung des SFTP-Zugangs +- koordinierten Romexis-Neustart über eine gemeinsame State-Datei + +Unterstützte Migrationswege: + +1. **Windows Migration Client** + - erkennt Romexis-Installation, SQL-Server-Konfiguration und Datenverzeichnisse + - erstellt oder nutzt ein Datenbankbackup + - lädt Daten per rclone/SFTP hoch + - kommuniziert mit der Migration Service API + +2. **Manueller Browser- und SFTP-Workflow** + - Migrationsjob im Web UI erstellen + - Datenbankbackup über den Browser hochladen + - Manifest vom Server erzeugen lassen + - `romexis_images`, `romexis_ergodata` und optional `romexis_cache` per SFTP hochladen + - validieren, wiederherstellen und Migration abschließen + +Der Romexis-Neustart nach dem Restore wird über folgende Datei koordiniert: + +```text +/data/romexis_images/.romexis_restart_state +``` + +Der Migration Service schreibt die Neustartanforderung, der Romexis-Entrypoint führt den Neustart aus und schreibt den finalen Status zurück. + + +## Persistente Datenverzeichnisse + +### sconfig + +Gemountet nach: + +```text +/opt/romexis/sconfig +``` + +Enthält persistente Romexis-Serverkonfiguration. + +### programdata + +Gemountet nach: + +```text +/programdata/Planmeca/Romexis +``` + +Entspricht dem Windows-Pfad `%ProgramData%\Planmeca\Romexis` und enthält KeyVault sowie sicherheitsrelevante Dateien. + +### romexis_images + +Gemountet nach: + +```text +/data/romexis_images +``` + +Speichert Patientenbilder. + +### romexis_cache + +Gemountet nach: + +```text +/data/romexis_cache +``` + +Speichert Cache-Daten. + +### romexis_ergodata + +Gemountet nach: + +```text +/data/romexis_ergodata +``` + +Speichert Ergo- und Zusatzdaten. + +--- + +## Datenbankinitialisierung + +Beim ersten Start: + +1. SQL Server startet. +2. Romexis wartet, bis SQL Server als erreichbar gilt. +3. Die Datenbank `Romexis_db` wird erstellt, falls sie fehlt. +4. Der Datenbankbenutzer `romexis` wird erstellt, falls er fehlt. +5. Romexis-Schema- und Update-Skripte werden importiert. +6. Linux-Datenpfade werden in die Datenbank geschrieben. + +Die Initialisierung wird übersprungen, wenn Datenbank und Romexis-Benutzer bereits existieren. + +Deaktivieren: + +```yaml +ROMEXIS_INIT_DB: "0" +``` + +Ausführliche SQL-Ausgabe: + +```yaml +DB_CREATE_VERBOSE: "true" +``` + +--- + +## KeyVault und ProgramData + +Romexis erwartet einen Windows-ähnlichen `ProgramData`-Pfad. Der Entrypoint setzt: + +```bash +ProgramData=/programdata +``` + +Der KeyVault-Pfad wird in `romexis_server.properties` geschrieben: + +```properties +SERVER_KEYVAULT_PATH=/programdata/Planmeca/Romexis/sconfig +``` + +Der Entrypoint initialisiert fehlende Schlüsseldateien aus den im Image enthaltenen Defaults: + +- `static_keys_default.p12` -> `static_keys.p12` +- `initial_keyvault.p12` -> `keyvault.p12` + +--- + +## RomexisConfig + +`RomexisConfig` wird absichtlich nicht ausgeführt. + +In einem Linux-Container kann RomexisConfig versuchen, über Advapi32/JNA auf Windows-Registry-Funktionen zuzugreifen. Die notwendigen Aufgaben übernimmt stattdessen der Docker-Entrypoint. + +Ersetzte Aufgaben: + +- KeyVault-Vorbereitung +- ProgramData-Handling +- Datenbankkonfiguration +- Linux-Pfadkonfiguration +- Runtime-Property-Injection + +--- + +## Erweiterte Konfiguration + +### Datenbank-URL + +Standardmäßig erzeugt der Entrypoint: + +```text +jdbc:sqlserver://:;databaseName=;encrypt=true;trustServerCertificate=true; +``` + +Eine vollständige JDBC-URL kann explizit gesetzt werden: + +```yaml +ROMEXIS_DB_URL: "jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;" +``` + +### Datenbank-Backend + +```yaml +SERVER_DB: "5" +``` + +Wert `5` steht für Microsoft SQL Server. + +### RMI Host und Ports + +```yaml +SERVER_RMI_HOSTNAME: "192.168.65.177" +SERVER_RMI_LOW_PORT: "1100" +SERVER_RMI_HIGH_PORT: "1120" +``` + +`SERVER_RMI_HOSTNAME` muss für Romexis-Clients erreichbar sein. + +### Property Agent + +Der Java Property Agent kann Romexis `RxProperties` über Umgebungsvariablen setzen. + +Syntax: + +```yaml +PROPERTY_AGENT_SET_: "" +``` + +Standardverhalten: + +```yaml +PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES: "true" +``` + +Diese Einstellung ist für zuverlässiges KeyVault-Handling unter Docker/Linux erforderlich. + +--- + +## Troubleshooting + +### SQL Server prüfen + +```bash +docker compose logs mssql +``` + +### Romexis prüfen + +```bash +docker compose logs romexis +``` + +### SQL-Server-Verbindung testen + +```bash +docker exec -it romexis-mssql \ + /opt/mssql-tools18/bin/sqlcmd \ + -C \ + -S localhost \ + -U sa \ + -P 'Pwr0mex!s!!!' \ + -Q "SELECT 1" +``` + +### Aufgelöste Romexis-Version prüfen + +```bash +docker exec -it romexis-server cat /opt/romexis/version +``` + +### Keystore-Alias-Probleme + +Falls Romexis meldet: + +```text +Failed to get keystore entry by alias: +server_certificate_... +``` + +ausführen: + +```bash +docker exec -it romexis-server /opt/fix-keystore-alias.sh +``` + +--- + +## Bekannte Einschränkungen + +- Nur Serverbetrieb wurde getestet. +- `RomexisConfig` wird im Container nicht unterstützt. +- Microsoft SQL Server ist das primär unterstützte Datenbank-Backend. +- Firebird-Clientbibliotheken sind im Base Image enthalten, die aktuelle Compose-Laufzeitumgebung fokussiert SQL Server. +- Multiarch-Images werden vom Build-Prozess unterstützt; die funktionale Validierung hängt von Plattform und verfügbaren Romexis-Komponenten ab. + +--- + +## Lizenz + +### Romexis + +Planmeca Romexis ist proprietäre Software. + +Dieses Repository enthält keine Romexis-Programmdateien. Der offizielle Installer wird während des Builds anhand von `romexis-versions.env` heruntergeladen. + +### Chilkat + +Dieses Projekt nutzt die von Romexis benötigte Chilkat-Bibliothek. Sie wird während des Builds passend zur Zielarchitektur heruntergeladen. + +--- + +## Haftungsausschluss + +Dieses Projekt steht in keiner Verbindung zu Planmeca Oy. + +Die Nutzung erfolgt auf eigene Verantwortung. + +Vor dem produktiven Einsatz werden vollständige Backups und Tests dringend empfohlen.