diff --git a/Architecture.de.md b/Architecture.de.md new file mode 100644 index 0000000..2a6a9b0 --- /dev/null +++ b/Architecture.de.md @@ -0,0 +1,177 @@ +[**Deutsch**](Architecture.de) | [English](Architecture) + +# Architektur + +## Übergeordnete Runtime-Architektur + +Die Runtime ist in einen Basis-Compose-Stack und ein ausgewähltes Datenbank-Backend-Override aufgeteilt. + +### Microsoft-SQL-Server-Modus + +```text ++----------------------+ +----------------------+ +| Romexis Clients | | Browser / noVNC User | ++----------+-----------+ +----------+-----------+ + | | + | RMI / Romexis ports | HTTP / WebSocket + v v ++----------------------+ +----------------------+ +| Romexis Server | | Romexis Admin | +| Docker Container | | noVNC Container | ++----------+-----------+ +----------------------+ + | + | JDBC + v ++----------------------+ +| Microsoft SQL Server | +| Docker Container | ++----------------------+ +``` + +### Firebird-Modus + +```text ++----------------------+ +----------------------+ +| Romexis Clients | | Browser / noVNC User | ++----------+-----------+ +----------+-----------+ + | | + | RMI / Romexis ports | HTTP / WebSocket + v v ++----------------------+ +----------------------+ +| Romexis Server | | Romexis Admin | +| Docker Container | | noVNC Container | ++----------+-----------+ +----------------------+ + | + | JDBC / Jaybird + v ++----------------------+ +| Firebird Server | +| Docker Container | ++----------------------+ +``` + +### mRomexis Web App + +```text ++----------------------+ +| Browser | ++----------+-----------+ + | + | HTTP + v ++----------------------+ +| OpenResty / Nginx | +| proxy container | ++----------+-----------+ + | + +------------------------------+ + | | + v v ++----------------------+ +----------------------+ +| mRomexis Web App | | Romexis Server | +| Tomcat Container | | Backend port 8093 | ++----------------------+ +----------------------+ +``` + +Der mRomexis-Proxy schreibt Backend-Proxy-Anfragen auf den internen Dienst `romexis` um. Er vertraut keinen beliebigen, vom Browser bereitgestellten Hosts. + +--- + +## Image-Architektur + +```text +romexis-payload: + | + +--> romexis-server: + | + +--> romexis-admin: + | + +--> romexis-mromexis-app: + +romexis-base-jre:11- + | + +--> romexis-server:- + +romexis-firebird-payload:latest + | + +--> romexis-server:- +``` + +--- + +## Compose-Architektur + +```text +docker-compose.yml + Common services: + - romexis + - romexis-admin + - romexis-app + - proxy + +docker-compose.mssql.yml + MSSQL service and MSSQL-specific Romexis environment. + +docker-compose.firebird.yml + Firebird service and Firebird-specific Romexis environment. +``` + +Das ausgewählte Backend wird geladen über: + +```env +DATABASE_BACKEND=mssql +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +--- + +## Persistenter Datenfluss + +```text +/srv/romexis-data/ + sconfig/ + programdata/ + romexis_images/ + romexis_cache/ + romexis_ergodata/ + sql-backup/ + firebird/ +``` + +Dieselbe persistente Datenwurzel kann über Neuerstellungen des Servers hinweg verwendet werden. Backend-spezifische Daten verbleiben im ausgewählten Datenbank-Volume oder Host-Verzeichnis. + +--- + +## Admin-Runtime-Architektur + +`romexis-admin` stellt einen grafischen Linux-Container für Romexis Admin / RomexisConfig bereit. + +Er startet: + +```text +Xvfb +Openbox +xcompmgr +x11vnc +noVNC / websockify +``` + +RomexisConfig kann bei Bedarf gestartet werden, wenn sich ein VNC-/noVNC-Client verbindet, und wieder beendet werden, wenn der letzte Client die Verbindung trennt. + +--- + +## Architektur der mRomexis Web App + +`romexis-app` ist ein Tomcat-Image, das Folgendes enthält: + +```text +/usr/local/tomcat/webapps/ROOT.war +``` + +Die WAR-Datei wird aus der Romexis-Payload kopiert: + +```text +/opt/romexis/broker/mromexis-html.war +``` + +Diese Datei existiert nur in Romexis 6.5.3 und neuer. diff --git a/Architecture.md b/Architecture.md index 345a38e..1a53f67 100644 --- a/Architecture.md +++ b/Architecture.md @@ -1,3 +1,5 @@ +[Deutsch](Architecture.de) | **English** + # Architecture ## High-Level Runtime Architecture diff --git a/Backup-and-Restore.de.md b/Backup-and-Restore.de.md new file mode 100644 index 0000000..74ce8e3 --- /dev/null +++ b/Backup-and-Restore.de.md @@ -0,0 +1,79 @@ +**Deutsch** | [English](Backup-and-Restore) + +# Backup und Wiederherstellung + +## Wiederherstellung eines MSSQL-Backups + +Der Migrationsdienst stellt SQL-Server-Backups über das gemeinsame Backup-Verzeichnis wieder her. + +Host: + +```text +DATABASE_BACKUP_DIR=/srv/mssql-backup +``` + +Migrationsdienst: + +```text +/upload/database +``` + +SQL Server: + +```text +/var/opt/mssql/backup +``` + +Wiederherstellungsskripte sollten den gemeinsamen Pfad verwenden, damit SQL Server auf die hochgeladene `.bak`-Datei zugreifen kann. + +--- + +## Wiederherstellung eines Firebird-Backups + +Die Firebird-Unterstützung umfasst ursprüngliche Hilfsskripte aus dem Payload des macOS-Installers: + +```text +/opt/romexis-firebird-db/tools/Romexis_Firebird_Backup.sh +/opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh +``` + +Die langfristige Wiederherstellungsstrategie sollte Folgendes unterstützen: + +```text +.fbk backup restore through gbak +.fdb file handling for compatible database files +``` + +Für Migrationen ist eine `gbak`-basierte Wiederherstellung vorzuziehen, weil sie Unterschiede zwischen Firebird-ODS-Versionen sicherer überbrücken kann als das Kopieren roher `.fdb`-Dateien. + +--- + +## Neustart nach der Wiederherstellung + +Der Migrationsdienst sollte den Romexis-Prozess nicht direkt von außen steuern. + +Stattdessen verwendet er die gemeinsame Neustart-Statusdatei: + +```text +/data/romexis_images/.romexis_restart_state +``` + +Erwarteter Ablauf: + +1. Der Migrationsdienst schreibt eine Neustartanforderung. +2. Der Romexis-Container erkennt die Anforderung. +3. Der Romexis-Prozess wird neu gestartet. +4. Der Romexis-Container schreibt das Ergebnis. +5. Der Migrationsdienst liest das Ergebnis. +6. Der Migrationsdienst entfernt die Statusdatei. + +--- + +## Endgültiger Abschluss der Migration + +Eine abgeschlossene Migration sollte: + +- Protokolle aufbewahren +- den temporären SFTP-Benutzer entfernen +- Aktionsschaltflächen ausblenden +- den Migrationsstatus für Audit und Fehlersuche aufbewahren diff --git a/Backup-and-Restore.md b/Backup-and-Restore.md index 3f8ccf0..90c5178 100644 --- a/Backup-and-Restore.md +++ b/Backup-and-Restore.md @@ -1,3 +1,5 @@ +[Deutsch](Backup-and-Restore.de) | **English** + # Backup and Restore ## MSSQL Backup Restore diff --git a/Base-Image.de.md b/Base-Image.de.md new file mode 100644 index 0000000..df2d670 --- /dev/null +++ b/Base-Image.de.md @@ -0,0 +1,86 @@ +**Deutsch** | [English](Base-Image) + +# Base-Image + +Das Base-Image stellt wiederverwendbare Laufzeitabhängigkeiten für das Romexis-Server-Image bereit. + +Verzeichnis: + +```text +romexis-base/ +``` + +--- + +## Verantwortlichkeiten + +Das Base-Image stellt Folgendes bereit: + +- Java-11-Laufzeit +- JavaFX-/OpenJFX-Unterstützung +- Microsoft-SQL-Server-Kommandozeilenwerkzeuge +- Firebird-Clientbibliotheken und -Werkzeuge +- gemeinsame Betriebssystempakete +- Sicherheitsaktualisierungen + +--- + +## Architekturspezifische Tags + +```text +romexis-base-jre:11-amd64 +romexis-base-jre:11-arm64 +``` + +Das Base-Image ist architekturspezifisch, weil es native Laufzeitpakete enthält. + +--- + +## Firebird-Werkzeuge + +Für die Firebird-Initialisierung benötigt der Romexis-Container die Firebird-CLI-Werkzeuge. + +Das wichtige Werkzeug ist üblicherweise: + +```text +isql-fb +``` + +nicht: + +```text +isql +``` + +Unter Debian/Ubuntu kann `isql` auf unixODBC verweisen. Das Firebird-Initialisierungsskript sollte daher standardmäßig Folgendes verwenden: + +```bash +ISQL="${ISQL:-isql-fb}" +``` + +Typischerweise erforderliche Pakete: + +```text +firebird3.0-utils +libfbclient2 +``` + +Paketnamen können sich abhängig von der Basisdistribution unterscheiden. + +--- + +## SQL-Server-Werkzeuge + +Das MSSQL-Initialisierungsskript verwendet: + +```text +/opt/mssql-tools18/bin/sqlcmd +``` + +Dies wird benötigt für: + +- das Warten auf SQL Server +- das Erstellen der Datenbank +- das Erstellen des Romexis-Datenbankbenutzers +- den Import von SQL-Skripten +- die Aktualisierung der Romexis-Datenpfade diff --git a/Base-Image.md b/Base-Image.md index 7d48e09..cbb6e9c 100644 --- a/Base-Image.md +++ b/Base-Image.md @@ -1,3 +1,5 @@ +[Deutsch](Base-Image.de) | **English** + # Base Image The base image provides reusable runtime dependencies for the Romexis Server image. diff --git a/Build-System.de.md b/Build-System.de.md new file mode 100644 index 0000000..1908985 --- /dev/null +++ b/Build-System.de.md @@ -0,0 +1,203 @@ +[**Deutsch**](Build-System.de) | [English](Build-System) + +# Build-System + +Das Build-System ist in unabhängige Schichten und Service-Images aufgeteilt. + +```text +romexis-payload + | + +--> romexis-server + +--> romexis-admin + +--> romexis-mromexis-app + ^ + | +romexis-base-jre + +romexis-firebird-payload + | + v +romexis-server +``` + +--- + +## Build-Komponenten + +### Payload-Build + +Der Payload-Build extrahiert den offiziellen Romexis-Windows-Installer. + +Er erzeugt: + +```text +/opt/romexis +/opt/romexis-mssql-db +/opt/romexis/version +``` + +Er stellt außerdem Dateien bereit, die von anderen Service-Images verwendet werden, einschließlich Admin-Dateien und, sofern verfügbar, der WAR-Datei der mRomexis Web App. + +### Firebird-Payload-Build + +Der Firebird-Payload-Build extrahiert das Datenbankpaket des macOS-Installers. + +Er erzeugt: + +```text +/opt/romexis-firebird-db +/opt/romexis-firebird-db/scripts +/opt/romexis-firebird-db/tools +/opt/romexis-firebird-db/templates +``` + +### Base-Image-Build + +Das Base-Image stellt wiederverwendbare Runtime-Abhängigkeiten bereit: + +- Java 11 +- JavaFX/OpenJFX +- SQL-Server-Werkzeuge +- Firebird-Clientbibliotheken und -Werkzeuge +- Betriebssystemabhängigkeiten + +### Server-Image-Build + +Das finale Server-Image importiert: + +- `/opt/romexis` aus `romexis-payload` +- `/opt/romexis-mssql-db` aus `romexis-payload` +- `/opt/romexis-firebird-db` aus `romexis-firebird-payload` +- die Basis-Runtime aus `romexis-base-jre` +- die native Chilkat-Bibliothek +- den Java Property Agent +- Runtime-Hilfsskripte + +### Admin-Image-Build + +Das Admin-Image importiert die Romexis-Admin-Dateien aus der Payload und ergänzt eine browserzugängliche X11-/noVNC-Runtime. + +Wichtige Runtime-Komponenten: + +```text +Xvfb +Openbox +xcompmgr +x11vnc +noVNC/websockify +JavaFX +``` + +### Build der mRomexis Web App + +Das Image der mRomexis Web App kopiert: + +```text +/opt/romexis/broker/mromexis-html.war +``` + +aus der Romexis-Payload nach Tomcat als: + +```text +/usr/local/tomcat/webapps/ROOT.war +``` + +Dies ist nur mit Romexis 6.5.3 und neuer möglich. + +--- + +## Lokale Build-Skripte + +Lokale Builds werden ausgeführt über: + +```text +scripts/build-local.sh +scripts/build-local.ps1 +``` + +Linux/macOS: + +```bash +chmod +x scripts/build-local.sh +./scripts/build-local.sh all +``` + +Windows PowerShell: + +```powershell +.\scripts\build-local.ps1 -Targets all +``` + +Einzelne Image-Gruppen bauen: + +```bash +./scripts/build-local.sh base server +./scripts/build-local.sh admin mromexis +./scripts/build-local.sh migration +``` + +--- + +## Beispiele für manuelle Docker-Builds + +Payload bauen: + +```bash +docker buildx build --platform linux/amd64 --provenance=false --sbom=false --build-arg ROMEXIS_VERSION=6.5.3.444.203 -t gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203 --load ./romexis-payload +``` + +Server-Image bauen: + +```bash +docker buildx build --platform linux/amd64 --provenance=false --sbom=false --build-arg TARGETARCH=amd64 --build-arg ROMEXIS_VERSION=6.5.3.444.203 -t gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-amd64 --load ./romexis +``` + +Admin-Image bauen: + +```bash +docker buildx build --platform linux/amd64 --provenance=false --sbom=false --build-arg TARGETARCH=amd64 --build-arg ROMEXIS_VERSION=6.5.3.444.203 -t gitea.buchhorster.de/planmeca/romexis-admin:6.5.3.444.203-amd64 --load ./romexis-admin +``` + +mRomexis Web App bauen: + +```bash +docker buildx build --platform linux/amd64 --provenance=false --sbom=false --build-arg TARGETARCH=amd64 --build-arg ROMEXIS_VERSION=6.5.3.444.203 -t gitea.buchhorster.de/planmeca/romexis-mromexis-app:6.5.3.444.203-amd64 --load ./romexis-mromexis-app +``` + +--- + +## Beziehung zur Runtime-Compose-Konfiguration + +Die Runtime-Compose-Dateien verwenden Multi-Architektur-Manifest-Tags anstelle architekturspezifischer Tags. + +Feature-Branches verwenden `IMAGE_SUFFIX`: + +```env +IMAGE_SUFFIX=-feature-romexis-admin +``` + +Die Image-Referenzen der Runtime-Compose-Konfiguration werden damit in Branch-spezifische Manifeste aufgelöst. + +--- + +## Bereinigung des Docker-Caches + +Buildx-Cache: + +```bash +docker buildx prune -a -f +``` + +Builder-Cache: + +```bash +docker builder prune -a -f +``` + +Systembereinigung: + +```bash +docker system prune -a -f +``` + +Verwende `--volumes` nur, wenn nicht verwendete Datenbank-/Anwendungs-Volumes absichtlich entfernt werden sollen. diff --git a/Build-System.md b/Build-System.md index 980d718..e25e0fb 100644 --- a/Build-System.md +++ b/Build-System.md @@ -1,3 +1,5 @@ +[Deutsch](Build-System.de) | **English** + # Build System The build system is split into independent layers and service images. diff --git a/CI-CD-Pipeline.de.md b/CI-CD-Pipeline.de.md new file mode 100644 index 0000000..c94e2bd --- /dev/null +++ b/CI-CD-Pipeline.de.md @@ -0,0 +1,178 @@ +**Deutsch** | [English](CI-CD-Pipeline) + +# CI/CD-Pipeline + +Das Projekt verwendet Drone CI, um Images zu bauen und in der Gitea-Container-Registry zu veröffentlichen. + +--- + +## Hauptaufgaben der Pipeline + +Die Pipeline baut: + +```text +romexis-payload +romexis-firebird-payload +romexis-base-jre:11-amd64 +romexis-base-jre:11-arm64 +romexis-server:-amd64 +romexis-server:-arm64 +romexis-admin:-amd64 +romexis-admin:-arm64 +romexis-mromexis-app:-amd64 +romexis-mromexis-app:-arm64 +romexis-migration-service:amd64 +romexis-migration-service:arm64 +multiarch manifests +``` + +--- + +## Behandlung von Branch-Suffixen + +Für `main` werden Image-Tags ohne Suffix veröffentlicht. + +Bei Feature-Branches wird der Branchname normalisiert und als Image-Suffix angehängt: + +```text +-feature-romexis-admin +``` + +Dadurch können Feature-Branch-Images und -Manifeste getestet werden, ohne `main`-Images zu überschreiben. + +--- + +## Payload-Buildlogik + +Der Windows-Payload-Build prüft Versionsdefinitionen und Änderungen an der Kopierzuordnung. + +Gewünschtes Verhalten: + +| Änderung | Verhalten | +|---|---| +| Neue Version hinzugefügt | nur neue Version bauen | +| Vorhandene URL geändert | betroffene Version erzwungen neu bauen | +| Kopierzuordnung geändert | alle Payload-Versionen neu bauen | +| Extraktionsskript geändert | alle Payload-Versionen neu bauen | + +--- + +## Firebird-Payload-Build + +Das Firebird-Payload wird nach dem Windows-Romexis-Payload-Schritt gebaut. + +Es verwendet: + +```text +romexis-firebird-payload/romexis-firebird-versions.env +``` + +Der Build veröffentlicht: + +```text +romexis-firebird-payload:latest +``` + +Das Server-Image verwendet das gemeinsame Firebird-Payload-Image. + +--- + +## Server-Build + +Der Server-Build lädt: + +```text +ROMEXIS_PAYLOAD_IMAGE +ROMEXIS_FIREBIRD_PAYLOAD_IMAGE +ROMEXIS_BASE_IMAGE +``` + +Anschließend wird das endgültige Laufzeitimage für jede Architektur gebaut. + +--- + +## Admin-Build + +Der Admin-Build verwendet das Romexis-Payload und baut: + +```text +romexis-admin:-amd64 +romexis-admin:-arm64 +romexis-admin: +romexis-admin:latest +``` + +Das endgültige Image enthält die grafische noVNC-Laufzeit sowie die Dateien von Romexis Admin / RomexisConfig. + +--- + +## mRomexis-Web-App-Build + +mRomexis-Web-App-Images werden nur für Romexis-Versionen gebaut, für die gilt: + +```text +version >= 6.5.3 +``` + +Ältere Versionen werden übersprungen, weil das Payload Folgendes nicht enthält: + +```text +/opt/romexis/broker/mromexis-html.war +``` + +Veröffentlichte Tags: + +```text +romexis-mromexis-app:-amd64 +romexis-mromexis-app:-arm64 +romexis-mromexis-app: +romexis-mromexis-app:latest +``` + +--- + +## Push gegenüber Load + +In CI sollte `--push` für die buildx-Ausgabe verwendet werden, wenn Images veröffentlicht werden. + +Dies vermeidet unnötiges lokales Laden von Images und kann die Worker-Zeit reduzieren. + +--- + +## Häufige CI-Fehlersuche + +### Build ist nach dem Leeren des Caches zu schnell + +Dies kann bedeuten, dass die Pipeline den Build übersprungen hat, weil das Registry-Image bereits existiert. + +Nach Protokollzeilen wie diesen suchen: + +```text +already exists +Skipping rebuild +docker manifest inspect +``` + +Einen Neubau erzwingen, indem die Pipeline-Bedingung geändert oder die Variable für den erzwungenen Neubau gesetzt wird. + +### `latest`-Tag nicht gefunden + +Wenn das Server-Dockerfile auf Folgendes verweist: + +```text +romexis-firebird-payload:latest +``` + +muss die Firebird-Payload-Pipeline `latest` veröffentlichen. + +### mRomexis-Build übersprungen + +Die Romexis-Version prüfen. Die mRomexis Web App wird nur für 6.5.3 und neuer gebaut. + +### Payload fehlt im endgültigen Image + +Das endgültige Image prüfen: + +```bash +docker run --rm --entrypoint find gitea.buchhorster.de/planmeca/romexis-server: /opt -maxdepth 3 -type f +``` diff --git a/CI-CD-Pipeline.md b/CI-CD-Pipeline.md index d64cc27..390dafb 100644 --- a/CI-CD-Pipeline.md +++ b/CI-CD-Pipeline.md @@ -1,3 +1,5 @@ +[Deutsch](CI-CD-Pipeline.de) | **English** + # CI/CD Pipeline The project uses Drone CI to build and publish images to the Gitea container registry. diff --git a/Compose-Runtime.de.md b/Compose-Runtime.de.md new file mode 100644 index 0000000..9a76d46 --- /dev/null +++ b/Compose-Runtime.de.md @@ -0,0 +1,182 @@ +[**Deutsch**](Compose-Runtime.de) | [English](Compose-Runtime) + +# Compose-Runtime + +Die Runtime-Compose-Konfiguration ist in eine gemeinsame Basisdatei und Backend-spezifische Override-Dateien aufgeteilt. + +--- + +## Dateien + +```text +.env.sample +docker-compose.yml +docker-compose.mssql.yml +docker-compose.firebird.yml +scripts/build-local.sh +scripts/build-local.ps1 +``` + +`docker-compose.build.yml` wird für die lokale Entwicklung nicht mehr benötigt. Lokale Image-Builds werden über `scripts/build-local.*` ausgeführt. + +--- + +## Backend-Auswahl + +Das ausgewählte Backend wird in `.env` gesteuert. + +### Microsoft SQL Server + +```env +DATABASE_BACKEND=mssql +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +### Firebird + +```env +DATABASE_BACKEND=firebird +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +In nativen Windows-Shells muss als Trennzeichen der Compose-Dateien möglicherweise `;` statt `:` verwendet werden: + +```env +COMPOSE_PATH_SEPARATOR=; +COMPOSE_FILE=docker-compose.yml;docker-compose.${DATABASE_BACKEND}.yml +``` + +Danach kann der Stack immer gestartet werden mit: + +```bash +docker compose up -d +``` + +Effektive Konfiguration anzeigen: + +```bash +docker compose config +``` + +--- + +## Basis-Runtime-Dienste + +Die Basis-Compose-Datei enthält die gemeinsam verwendeten Dienste: + +```text +romexis +romexis-admin +romexis-app +proxy +``` + +Backend-spezifische Dateien ergänzen oder überschreiben Datenbankdienste und datenbankbezogene Umgebungsvariablen. + +--- + +## MSSQL-Override + +Das MSSQL-Override stellt üblicherweise bereit: + +```text +mssql +romexis-migration +``` + +Es konfiguriert außerdem den Romexis-Server für das MSSQL-Backend, beispielsweise: + +```env +SERVER_DB=5 +MSSQL_HOST=mssql +ROMEXIS_DB_NAME=Romexis_db +``` + +--- + +## Firebird-Override + +Das Firebird-Override stellt üblicherweise bereit: + +```text +firebird +``` + +Es konfiguriert den Romexis-Server für das Firebird-Backend, beispielsweise: + +```env +SERVER_DB=4 +FIREBIRD_HOST=firebird +ROMEXIS_DB_USER=sysdba +``` + +--- + +## Image-Tags und Branch-Suffixe + +Die Runtime-Compose-Dateien verwenden Multi-Architektur-Manifest-Tags: + +```text +${REGISTRY}/${ROMEXIS_IMAGE}:${ROMEXIS_VERSION}${IMAGE_SUFFIX} +${REGISTRY}/${MIGRATION_IMAGE}:latest${IMAGE_SUFFIX} +${REGISTRY}/${ADMINISTRATION_IMAGE}:latest${IMAGE_SUFFIX} +${REGISTRY}/${MROMEXIS_WEBAPP_IMAGE}:${ROMEXIS_VERSION}${IMAGE_SUFFIX} +``` + +Für `main` bleibt `IMAGE_SUFFIX` leer: + +```env +IMAGE_SUFFIX= +``` + +Für Feature-Branches: + +```env +IMAGE_SUFFIX=-feature-romexis-admin +``` + +Dadurch wird verhindert, dass Images aus Feature-Branches die von `main` verwendeten Runtime-Images überschreiben. + +--- + +## Häufige Befehle + +Stack mit ausgewähltem Backend starten: + +```bash +docker compose up -d +``` + +Dienste nach Image-Aktualisierungen neu erstellen: + +```bash +docker compose up -d --force-recreate +``` + +Logs anzeigen: + +```bash +docker compose logs -f +``` + +Einen einzelnen Dienst anzeigen: + +```bash +docker compose logs -f romexis +docker compose logs -f romexis-admin +docker compose logs -f romexis-app +``` + +Stack stoppen: + +```bash +docker compose down +``` + +Volumes nur entfernen, wenn persistente Testdaten gelöscht werden dürfen: + +```bash +docker compose down -v +``` diff --git a/Compose-Runtime.md b/Compose-Runtime.md index 5173a52..5f1f8c1 100644 --- a/Compose-Runtime.md +++ b/Compose-Runtime.md @@ -1,3 +1,5 @@ +[Deutsch](Compose-Runtime.de) | **English** + # Compose Runtime The runtime Compose setup is split into a common base file and backend-specific override files. diff --git a/Configuration.de.md b/Configuration.de.md new file mode 100644 index 0000000..4854f0e --- /dev/null +++ b/Configuration.de.md @@ -0,0 +1,220 @@ +[**Deutsch**](Configuration.de) | [English](Configuration) + +# Konfiguration + +Die Konfiguration erfolgt größtenteils über Umgebungsvariablen in `.env` und Docker Compose. + +--- + +## Kernvariablen + +| Variable | Beschreibung | +|---|---| +| `REGISTRY` | Namespace der Container-Registry | +| `ROMEXIS_VERSION` | Auszuführende Romexis-Version | +| `IMAGE_SUFFIX` | Optionales Branch-spezifisches Image-Suffix | +| `DATABASE_BACKEND` | Ausgewähltes Backend, normalerweise `mssql` oder `firebird` | +| `COMPOSE_FILE` | Compose-Dateikette auf Basis des ausgewählten Backends | +| `HOST_IP` | Host-IP-Adresse, die Romexis-Clients bereitgestellt wird | +| `ROMEXIS_DATA_ROOT` | Stammverzeichnis für persistente Romexis-Daten | + +Beispiel: + +```env +REGISTRY=gitea.buchhorster.de/planmeca +ROMEXIS_VERSION=6.5.3.444.203 +IMAGE_SUFFIX= +DATABASE_BACKEND=mssql +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +HOST_IP=192.168.65.177 +ROMEXIS_DATA_ROOT=/srv/romexis-data +``` + +--- + +## Variablen für Image-Namen + +```env +ROMEXIS_IMAGE=romexis-server +MIGRATION_IMAGE=romexis-migration-service +ADMINISTRATION_IMAGE=romexis-admin +MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app +``` + +Diese werden durch die Compose-Dateien mit `REGISTRY`, `ROMEXIS_VERSION` und `IMAGE_SUFFIX` kombiniert. + +--- + +## Auswahl des Datenbank-Backends + +Die Backend-Auswahl wird durch die Auswahl der Compose-Dateien gesteuert, nicht nur durch `SERVER_DB`. + +### MSSQL + +```env +DATABASE_BACKEND=mssql +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Das MSSQL-Override setzt anschließend die Romexis-Backend-Werte, beispielsweise: + +```env +SERVER_DB=5 +MSSQL_HOST=mssql +``` + +### Firebird + +```env +DATABASE_BACKEND=firebird +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Das Firebird-Override setzt anschließend die Romexis-Backend-Werte, beispielsweise: + +```env +SERVER_DB=4 +FIREBIRD_HOST=firebird +``` + +--- + +## Microsoft-SQL-Server-Einstellungen + +```env +MSSQL_PORT=1433 +MSSQL_SA_PASSWORD=Pwr0mex!s!!! +MSSQL_PID=Express + +ROMEXIS_DB_NAME=Romexis_db +ROMEXIS_DB_USER=romexis +ROMEXIS_DB_PASSWORD=romexis +``` + +Erzeugte JDBC-URL: + +```text +jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true; +``` + +--- + +## Firebird-Einstellungen + +```env +FIREBIRD_PORT=3050 +FIREBIRD_USER=sysdba +FIREBIRD_PASSWORD=pwr0mex! +FIREBIRD_DB_PATH=/firebird/data/romexis.fdb +``` + +Erzeugte JDBC-URL: + +```text +jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb +``` + +Für die Romexis-Authentifizierung: + +```env +ROMEXIS_DB_USER=sysdba +ROMEXIS_DB_PASSWORD=pwr0mex! +``` + +--- + +## RMI-Ports + +```env +SERVER_RMI_LOW_PORT=1100 +SERVER_RMI_HIGH_PORT=1120 +``` + +Diese Ports müssen für Romexis-Clients erreichbar sein. + +--- + +## Romexis-Admin-Einstellungen + +```env +ADMIN_NOVNC_PORT=6080 +ADMIN_VNC_PORT=5900 +ADMIN_VNC_PASSWORD=promax +ADMIN_RESOLUTION=1280x900x24 +ADMIN_JAVA_OPTS=-Xms256m -Xmx1024m +ADMIN_LANGUAGE=de +DEBUG_XTERM=false +ADMIN_VNC_LIFECYCLE=true +ENABLE_PROPERTY_AGENT=false +``` + +Wichtiges Verhalten: + +- `ADMIN_LANGUAGE` wird für den Startbildschirm und als Parameter `language=` für RomexisConfig verwendet. +- `DEBUG_XTERM=true` startet ein optionales Debug-Terminal innerhalb der noVNC-Sitzung. +- `ADMIN_VNC_LIFECYCLE=true` startet RomexisConfig bei der ersten VNC-/noVNC-Verbindung und beendet es nach dem Trennen der letzten Verbindung. +- Der Admin-Container verwendet Openbox und xcompmgr als erforderliche Runtime-Komponenten. + +--- + +## Einstellungen der mRomexis Web App + +```env +MROMEXIS_WEB_PORT=8081 +``` + +Der mRomexis-Web-App-Container wird über den Proxy-Dienst bereitgestellt. Das Backend-Proxy-Ziel wird intern auf den Romexis-Serverdienst umgeschrieben. + +--- + +## Einstellungen des Migrationsdienstes + +```env +MIGRATION_HTTP_PORT=8080 +MIGRATION_SFTP_PORT=2222 +MIGRATION_API_TOKEN=change-me +DATABASE_BACKUP_DIR=/srv/romexis-data/sql-backup +``` + +`DATABASE_BACKUP_DIR` wird für Datenbank-Wiederherstellungsworkflows gemeinsam vom Migrationsdienst und dem Datenbank-Backend verwendet. + +--- + +## Versionslimit der Datenbankinitialisierung + +Der Datenbankinitialisierer leitet das Schema-Ziel ab aus: + +```text +/opt/romexis/version +``` + +Beispiel: + +```text +6.5.3.444.203 -> 653 +``` + +Um die Initialisierung auf eine maximale Schema-Kennung zu begrenzen: + +```env +ROMEXIS_DB_MAX_VERSION=653 +``` + +Ist die Romexis-Version des Containers neuer als das konfigurierte Maximum, gibt das Skript eine Warnung aus und initialisiert nur bis zur konfigurierten Kennung. + +--- + +## Property Agent + +Der Java Property Agent kann Romexis-`RxProperties` über Umgebungsvariablen setzen. + +Syntax: + +```env +PROPERTY_AGENT_SET_= +``` + +Dies ist vor allem für die Romexis-Server-Runtime relevant. Im Admin-Container ist der PropertyAgent standardmäßig deaktiviert. diff --git a/Configuration.md b/Configuration.md index 65c0633..262eee9 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,3 +1,5 @@ +[Deutsch](Configuration.de) | **English** + # Configuration Configuration is mostly handled through environment variables in `.env` and Docker Compose. diff --git a/Container-Images.de.md b/Container-Images.de.md new file mode 100644 index 0000000..6505791 --- /dev/null +++ b/Container-Images.de.md @@ -0,0 +1,157 @@ +**Deutsch** | [English](Container-Images) + +# Container-Images + +Images werden in dem vom Projekt verwendeten Namespace der Gitea-Paket-Registry veröffentlicht. + +--- + +## Hauptimages + +```text +gitea.buchhorster.de/planmeca/romexis-payload: +gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest + +gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64 +gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64 +gitea.buchhorster.de/planmeca/romexis-base-jre:11 + +gitea.buchhorster.de/planmeca/romexis-server:-amd64 +gitea.buchhorster.de/planmeca/romexis-server:-arm64 +gitea.buchhorster.de/planmeca/romexis-server: + +gitea.buchhorster.de/planmeca/romexis-admin:-amd64 +gitea.buchhorster.de/planmeca/romexis-admin:-arm64 +gitea.buchhorster.de/planmeca/romexis-admin: +gitea.buchhorster.de/planmeca/romexis-admin:latest + +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-amd64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-arm64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app: +gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest + +gitea.buchhorster.de/planmeca/romexis-migration-service:amd64 +gitea.buchhorster.de/planmeca/romexis-migration-service:arm64 +gitea.buchhorster.de/planmeca/romexis-migration-service:latest +``` + +--- + +## Tagging-Strategie + +### Payload-Image + +Das Windows-Payload-Image wird mit der Romexis-Version versioniert und ist architekturunabhängig: + +```text +romexis-payload:6.5.3.444.203 +``` + +### Base-Image + +Base-Images sind architekturspezifisch und werden zusätzlich als Manifest veröffentlicht: + +```text +romexis-base-jre:11-amd64 +romexis-base-jre:11-arm64 +romexis-base-jre:11 +``` + +### Server-Image + +Server-Images sind architekturspezifisch und werden als Multi-Architektur-Manifest veröffentlicht: + +```text +romexis-server:6.5.3.444.203-amd64 +romexis-server:6.5.3.444.203-arm64 +romexis-server:6.5.3.444.203 +``` + +### Admin-Image + +Das Admin-Image verwendet das Romexis-Payload und stellt die browserbasierte noVNC-Admin-Laufzeit bereit: + +```text +romexis-admin:-amd64 +romexis-admin:-arm64 +romexis-admin: +romexis-admin:latest +``` + +### mRomexis-Web-App-Image + +Das mRomexis-Web-App-Image wird mit der Romexis-Version versioniert: + +```text +romexis-mromexis-app:-amd64 +romexis-mromexis-app:-arm64 +romexis-mromexis-app: +romexis-mromexis-app:latest +``` + +Es kann nur für Romexis-Versionen gebaut werden, die Folgendes enthalten: + +```text +/opt/romexis/broker/mromexis-html.war +``` + +Dies wird für Romexis 6.5.3 und neuer erwartet. + +--- + +## Branch-Image-Suffixe + +Für `main` bleibt `IMAGE_SUFFIX` leer: + +```env +IMAGE_SUFFIX= +``` + +Für Feature-Branches wird ein branch-spezifischer Suffix verwendet: + +```env +IMAGE_SUFFIX=-feature-romexis-admin +``` + +Beispiel für ein aufgelöstes Image: + +```text +gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-feature-romexis-admin +``` + +Dies verhindert, dass Feature-Branch-Builds Laufzeitimages von `main` überschreiben oder mit ihnen verwechselt werden. + +--- + +## Images abrufen + +Für Multiarch-Verwendung: + +```bash +docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203 +``` + +Admin-Image: + +```bash +docker pull gitea.buchhorster.de/planmeca/romexis-admin:latest +``` + +mRomexis-Web-App-Image: + +```bash +docker pull gitea.buchhorster.de/planmeca/romexis-mromexis-app:6.5.3.444.203 +``` + +--- + +## Image-Referenzen in Runtime Compose + +Compose verwendet Manifest-Tags statt architekturspezifischer Tags: + +```text +${REGISTRY}/${ROMEXIS_IMAGE}:${ROMEXIS_VERSION}${IMAGE_SUFFIX} +${REGISTRY}/${MIGRATION_IMAGE}:latest${IMAGE_SUFFIX} +${REGISTRY}/${ADMINISTRATION_IMAGE}:latest${IMAGE_SUFFIX} +${REGISTRY}/${MROMEXIS_WEBAPP_IMAGE}:${ROMEXIS_VERSION}${IMAGE_SUFFIX} +``` diff --git a/Container-Images.md b/Container-Images.md index 70bccb5..bfea663 100644 --- a/Container-Images.md +++ b/Container-Images.md @@ -1,3 +1,5 @@ +[Deutsch](Container-Images.de) | **English** + # Container Images Images are published to the Gitea package registry namespace used by the project. diff --git a/Database-Backends.de.md b/Database-Backends.de.md new file mode 100644 index 0000000..9b666c1 --- /dev/null +++ b/Database-Backends.de.md @@ -0,0 +1,146 @@ +**Deutsch** | [English](Database-Backends) + +# Datenbank-Backends + +Romexis unterstützt mehrere Datenbank-Backends. Dieses Docker-Projekt behandelt Microsoft SQL Server derzeit als Standard-Backend und Firebird über ein eigenes Compose-Override als paralleles Backend. + +--- + +## Auswahl des Compose-Backends + +Das Datenbank-Backend wird in `.env` mit `DATABASE_BACKEND` und `COMPOSE_FILE` ausgewählt. + +### Microsoft SQL Server + +```env +DATABASE_BACKEND=mssql +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +### Firebird + +```env +DATABASE_BACKEND=firebird +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Das backend-spezifische Compose-Override setzt die tatsächlichen Romexis-Backendvariablen. + +--- + +## Backend-Kennungen + +Romexis selbst verwendet intern weiterhin `SERVER_DB`. + +| `SERVER_DB` | Backend | +|---|---| +| `5` | Microsoft SQL Server | +| `4` | Firebird | + +Im Normalbetrieb sollte `SERVER_DB` nicht manuell in der Basis-`.env` gesetzt werden, außer zu Debugzwecken. Das backend-spezifische Compose-Override sollte den Wert setzen. + +--- + +## Backend-Dienste + +### MSSQL + +Das MSSQL-Override startet den Dienst `mssql` und konfiguriert Romexis für die Verbindung zu: + +```text +mssql:1433 +``` + +Typische Werte: + +```env +MSSQL_SA_PASSWORD=Pwr0mex!s!!! +ROMEXIS_DB_NAME=Romexis_db +ROMEXIS_DB_USER=romexis +ROMEXIS_DB_PASSWORD=romexis +``` + +### Firebird + +Das Firebird-Override startet den Dienst `firebird` und konfiguriert Romexis für die Verbindung über Jaybird. + +Typische Werte: + +```env +FIREBIRD_USER=sysdba +FIREBIRD_PASSWORD=pwr0mex! +FIREBIRD_DB_PATH=/firebird/data/romexis.fdb +``` + +--- + +## Initialisierungsskripte + +Der Einstiegspunkt der Initialisierung ist: + +```text +/opt/init-romexis-db.sh +``` + +Dieses Skript leitet weiter an: + +```text +/opt/init-romexis-mssql-db.sh +/opt/init-romexis-firebird-db.sh +``` + +--- + +## Versionsabhängige Initialisierung + +Die Backend-Skripte lesen: + +```text +/opt/romexis/version +``` + +Beispiel: + +```text +6.5.3.444.203 +``` + +Sie ermitteln die Ziel-Schemamarkierung über die explizite Romexis-Aktualisierungsreihenfolge. + +Beispiel: + +```text +6.5.3 -> 653 +6.5.2 -> 652 +6.5.1 -> 651 +6.4.x -> 64 +3.8.3 -> 383 +``` + +Die Skripte verlassen sich nicht auf eine rein numerische Reihenfolge, da Romexis-Aktualisierungsmarkierungen keine natürliche Sortierung besitzen. + +--- + +## Maximale Schemaversion + +Verwendung: + +```env +ROMEXIS_DB_MAX_VERSION=653 +``` + +Ist die Romexis-Version neuer als die konfigurierte Maximalmarkierung, wird die Initialisierung nur bis zur Maximalmarkierung fortgesetzt und eine Warnung ausgegeben. + +--- + +## Bestehende Datenbanken + +Wenn die Datenbank bereits initialisiert erscheint, wird die Initialisierung übersprungen. + +Bei MSSQL basiert dies auf dem Vorhandensein von Datenbank und Benutzer. + +Bei Firebird basiert dies auf dem Vorhandensein zentraler Romexis-Tabellen. + +Zukünftige Upgradelogik kann ergänzt werden, indem die vorhandene Datenbank-Schemamarkierung gelesen wird. diff --git a/Database-Backends.md b/Database-Backends.md index 737e8bb..5ec08c2 100644 --- a/Database-Backends.md +++ b/Database-Backends.md @@ -1,3 +1,5 @@ +[Deutsch](Database-Backends.de) | **English** + # Database Backends Romexis supports multiple database backends. This Docker project currently treats Microsoft SQL Server as the default backend and Firebird as a parallel backend through a dedicated Compose override. diff --git a/Developer-Guide.de.md b/Developer-Guide.de.md new file mode 100644 index 0000000..36e1c2c --- /dev/null +++ b/Developer-Guide.de.md @@ -0,0 +1,113 @@ +**Deutsch** | [English](Developer-Guide) + +# Entwicklerhandbuch + +Diese Seite beschreibt die interne Projektstruktur und den Entwicklungsworkflow. + +--- + +## Hauptverzeichnisse des Projekts + +```text +romexis-base/ + Runtime base image. + +romexis-payload/ + Windows installer payload extraction. + +romexis-firebird-payload/ + macOS Firebird SQL payload extraction. + +romexis/ + Final Romexis Server image. + +migration-service/ + Migration Web UI, REST API, SFTP and restore orchestration. + +migration-client/ + Source-side migration helper client. + +docs/ + Extended markdown documentation. +``` + +--- + +## Entwicklungsgrundsätze + +- Proprietäre Binärdateien aus Git fernhalten. +- Installerextraktion in Payload-Images belassen. +- Laufzeitabhängigkeiten im Base-Image belassen. +- Das endgültige Server-Image auf Zusammenbau und Laufzeitlogik konzentrieren. +- MSSQL- und Firebird-Initialisierung getrennt halten. +- Das Wrapper-Skript ausschließlich für das Backend-Routing verwenden. +- Explizite Validierung gegenüber still erzeugten, unvollständigen Images bevorzugen. + +--- + +## Datenbankinitialisierungsskripte + +```text +init-romexis-db.sh + Routes to backend-specific init script. + +init-romexis-mssql-db.sh + Handles SQL Server initialization. + +init-romexis-firebird-db.sh + Handles Firebird initialization. +``` + +--- + +## Versionsabhängige Datenbankaktualisierungen + +Die Datenbankinitialisierungsskripte verwenden eine explizite Romexis-Aktualisierungsreihenfolge. + +Dies ist erforderlich, weil sich die Markierungen nicht numerisch sortieren lassen. + +Beispiel: + +```text +600, 610, 63, 64, 651, 652, 653 +``` + +Das Skript ermittelt die Zielmarkierung aus `/opt/romexis/version` und führt Aktualisierungen bis zu dieser Markierung aus. + +--- + +## Image-Inhalte testen + +```bash +docker run --rm --entrypoint find \ + gitea.buchhorster.de/planmeca/romexis-server: \ + /opt -maxdepth 3 -type f | sort +``` + +Shell öffnen: + +```bash +docker run --rm -it --entrypoint bash \ + gitea.buchhorster.de/planmeca/romexis-server: +``` + +--- + +## Lokales Debug-Compose-Override + +```yaml +services: + romexis: + entrypoint: + - /bin/bash + - -c + - sleep infinity + stdin_open: true + tty: true +``` + +Anschließend: + +```bash +docker compose exec romexis bash +``` diff --git a/Developer-Guide.md b/Developer-Guide.md index d630700..14e3187 100644 --- a/Developer-Guide.md +++ b/Developer-Guide.md @@ -1,3 +1,5 @@ +[Deutsch](Developer-Guide.de) | **English** + # Developer Guide This page describes the internal project structure and development workflow. diff --git a/Docker-Desktop-WSL-Windows.de.md b/Docker-Desktop-WSL-Windows.de.md new file mode 100644 index 0000000..f5e793d --- /dev/null +++ b/Docker-Desktop-WSL-Windows.de.md @@ -0,0 +1,111 @@ +**Deutsch** | [English](Docker-Desktop-WSL-Windows) + +# Romexis Docker unter Windows mit Docker Desktop und WSL 2 ausführen + +## Zweck + +Diese Anleitung erklärt, wie der Romexis-Docker-Stack unter Windows mit Docker Desktop und dem WSL-2-Backend ausgeführt wird. + +Offizielle Dokumentation: +https://docs.docker.com/desktop/features/wsl/ + +## Voraussetzungen + +- Windows 10/11 +- WSL 2 +- Docker Desktop +- Ubuntu (empfohlen) + +## WSL installieren + +```powershell +wsl --install +wsl -l -v +``` + +## Docker-Desktop-WSL-Integration aktivieren + +Docker Desktop → Settings → Resources → WSL Integration + +Die verwendete Ubuntu-Distribution aktivieren. + +Prüfen: + +```bash +docker version +docker compose version +``` + +## Empfohlenes Verzeichnislayout + +```text +/srv/romexis-docker +/srv/romexis-data +/srv/romexis-backup +``` + +Verzeichnisse erstellen: + +```bash +sudo mkdir -p /srv/romexis-docker /srv/romexis-data /srv/romexis-backup +sudo chown -R $USER:$USER /srv/romexis-docker /srv/romexis-data /srv/romexis-backup +``` + +## Konfigurieren + +```bash +cp .env.sample .env +nano .env +``` + +Beispiel: + +```env +ROMEXIS_VERSION=6.5.3.444.203 +SERVER_DB=5 +HOST_IP=192.168.1.100 +ROMEXIS_DATA_ROOT=/srv/romexis-data +DATABASE_BACKUP_DIR=/srv/romexis-backup +``` + +Firebird: + +```env +SERVER_DB=4 +FIREBIRD_USER=sysdba +FIREBIRD_PASSWORD=pwr0mex! +ROMEXIS_DB_URL=jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb +``` + +## Starten + +```bash +docker compose up -d +docker compose ps +docker compose logs -f romexis +``` + +## Nützliche Befehle + +```bash +docker compose exec romexis bash +docker buildx prune -a -f +docker compose build --no-cache --pull +docker compose up -d --force-recreate +``` + +## Fehlersuche + +### Docker nicht gefunden + +Die WSL-Integration aktivieren. + +### Langsame Leistung + +Das Projekt unter `/srv` statt unter `/mnt/c` speichern. + +### Einen Container debuggen + +```bash +docker compose run --rm --entrypoint /bin/bash romexis +``` diff --git a/Docker-Desktop-WSL-Windows.md b/Docker-Desktop-WSL-Windows.md index 4cae47c..f8de48e 100644 --- a/Docker-Desktop-WSL-Windows.md +++ b/Docker-Desktop-WSL-Windows.md @@ -1,3 +1,5 @@ +[Deutsch](Docker-Desktop-WSL-Windows.de) | **English** + # Running Romexis Docker on Windows with Docker Desktop and WSL 2 ## Purpose diff --git a/FAQ.de.md b/FAQ.de.md new file mode 100644 index 0000000..064aa87 --- /dev/null +++ b/FAQ.de.md @@ -0,0 +1,76 @@ +**Deutsch** | [English](FAQ) + +# Häufig gestellte Fragen + +## Werden Romexis-Binärdateien in Git gespeichert? + +Nein. Das Repository speichert keine proprietären Romexis-Anwendungsbinärdateien. + +Das Build-System lädt offizielle Installerpakete herunter und extrahiert die benötigten Dateien während der Payload-Builds. + +--- + +## Warum werden Payload-Images verwendet? + +Payload-Images vermeiden wiederholte Installerdownloads und entkoppeln die Installerextraktion vom Zusammenbau des endgültigen Server-Images. + +--- + +## Warum wird das Firebird-Payload als `latest` geteilt? + +Das Firebird-Payload enthält das gepflegte Firebird-SQL-Payload. Es wird vom Server-Image unabhängig von dessen Architektur verwendet. + +--- + +## Welches Datenbank-Backend ist Standard? + +Microsoft SQL Server. + +Verwendung: + +```env +SERVER_DB=5 +``` + +--- + +## Wie aktiviere ich Firebird? + +Verwendung: + +```env +SERVER_DB=4 +FIREBIRD_PASSWORD=pwr0mex! +ROMEXIS_DB_USER=sysdba +ROMEXIS_DB_PASSWORD=pwr0mex! +``` + +und anschließend die Firebird-Compose-Variante starten. + +--- + +## Warum verwendet die Firebird-Initialisierung `isql-fb`? + +Weil `isql` das Werkzeug von unixODBC sein kann. Die Firebird-CLI heißt üblicherweise: + +```text +isql-fb +``` + +--- + +## Kann ich ARM64 verwenden? + +Das Projekt baut ARM64-Romexis-Laufzeitimages. Microsoft SQL Server bietet keinen gleichwertigen nativen ARM64-Containerpfad, daher sind Firebird oder ein externes Datenbank-Backend die realistischere Ausrichtung für ARM64. + +--- + +## Kann ich von einem bestehenden Windows-Romexis-Server migrieren? + +Ja, dies ist der Zweck des Workflows aus Migrationsdienst und Migrationsclient. + +--- + +## Sollten abgeschlossene Migrationsjobs weiterhin SFTP-Benutzer besitzen? + +Nein. Abgeschlossene und abgebrochene Jobs sollten den SFTP-Zugang entfernen oder deaktivieren und temporäre Benutzer beim Neustart des Dienstes nicht erneut erstellen. diff --git a/FAQ.md b/FAQ.md index ccc73d2..7ca531c 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,3 +1,5 @@ +[Deutsch](FAQ.de) | **English** + # FAQ ## Are Romexis binaries stored in Git? diff --git a/Firebird.de.md b/Firebird.de.md new file mode 100644 index 0000000..0f1081d --- /dev/null +++ b/Firebird.de.md @@ -0,0 +1,152 @@ +**Deutsch** | [English](Firebird) + +# Firebird + +Firebird-Unterstützung wird als paralleles Datenbank-Backend eingeführt. + +Dies ist besonders relevant, weil macOS-basierte Romexis-Installationen Firebird verwenden und Firebird einen realistischen Weg für ARM64-Umgebungen darstellt. + +--- + +## Compose-Dienst + +Empfohlener Firebird-Dienst: + +```yaml +firebird: + image: jacobalberty/firebird:3.0 + container_name: romexis-firebird + environment: + ISC_PASSWORD: "${FIREBIRD_PASSWORD}" + FIREBIRD_DATABASE: "romexis.fdb" + ports: + - "${FIREBIRD_PORT:-3050}:3050" + volumes: + - ${ROMEXIS_DATA_ROOT}/firebird:/firebird/data + healthcheck: + test: ["CMD-SHELL", "nc -z localhost 3050 || exit 1"] + interval: 10s + timeout: 5s + retries: 30 + start_period: 20s + restart: unless-stopped +``` + +Den Container nicht so konfigurieren, dass ein zweiter `SYSDBA`-Benutzer erstellt wird. `SYSDBA` ist bereits vorhanden. + +--- + +## Romexis-Einstellungen + +```env +SERVER_DB=4 +FIREBIRD_PORT=3050 +FIREBIRD_USER=sysdba +FIREBIRD_PASSWORD=pwr0mex! +FIREBIRD_DB_PATH=/firebird/data/romexis.fdb + +ROMEXIS_DB_USER=sysdba +ROMEXIS_DB_PASSWORD=pwr0mex! +``` + +Erzeugte JDBC-URL: + +```text +jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb +``` + +--- + +## Firebird-SQL-Payload + +Das Firebird-SQL-Payload wird aus dem macOS-Romexis-Installer extrahiert und gespeichert unter: + +```text +/opt/romexis-firebird-db +``` + +Wichtige Dateien: + +```text +scripts/RX_Create_Database.sql +scripts/RX_Base_10fb_MAC.sql +scripts/rxdb.sh +scripts/rxupd.sh +tools/Romexis_Firebird_Backup.sh +tools/Romexis_Firebird_Restore.sh +templates/romexis_new.fdb +``` + +--- + +## Wichtiger Hinweis zu Werkzeugen + +Das Firebird-CLI-Werkzeug sollte Folgendes sein: + +```text +isql-fb +``` + +nicht das `isql` von unixODBC. + +Wenn diese Ausgabe erscheint: + +```text +unixODBC - isql and iusql +``` + +wird das falsche Werkzeug verwendet. + +Setzen: + +```bash +export ISQL=isql-fb +``` + +oder das Initialisierungsskript standardmäßig Folgendes verwenden lassen: + +```bash +ISQL="${ISQL:-isql-fb}" +``` + +--- + +## Strategie zur Datenbankerstellung + +Wenn der Firebird-Container über Folgendes eine leere Datenbank erstellt: + +```yaml +FIREBIRD_DATABASE: "romexis.fdb" +``` + +sollte das Romexis-Firebird-Initialisierungsskript nicht erneut `CREATE DATABASE` ausführen. + +Stattdessen sollte es sich mit der vorhandenen leeren Datenbank verbinden und die Romexis-SQL-Skripte importieren. + +--- + +## Firebird-Initialisierung debuggen + +Eine Shell im Romexis-Container öffnen: + +```bash +docker exec -it romexis-server bash +``` + +Initialisierungsprogramm manuell ausführen: + +```bash +ISQL=isql-fb DB_CREATE_VERBOSE=1 bash -x /opt/init-romexis-firebird-db.sh +``` + +Verbindung prüfen: + +```bash +bash -c ': Dieses Projekt stellt eine reproduzierbare Docker-Umgebung für den Betrieb von Planmeca Romexis Server unter Linux, macOS oder WSL mit Windows bereit und hält den Build-Prozess dabei nahe am Layout des ursprünglichen Installers. Romexis-Anwendungsbinärdateien werden nicht im Repository gespeichert. Sie werden während des Build-Prozesses aus offiziellen Installer-Paketen extrahiert. + +--- + +## Hauptbereiche + +| Bereich | Beschreibung | +|---|---| +| [Projektübersicht](Project-Overview.de) | Übergeordnete Ziele, Funktionen und unterstützte Plattformen | +| [Architektur](Architecture.de) | Image-Schichten, Runtime-Container und Datenfluss | +| [Schnellstart](Quick-Start.de) | Minimale Schritte zum Starten des Stacks | +| [Compose-Runtime](Compose-Runtime.de) | Basis-Compose-Datei, Backend-Overrides und `.env`-Auswahl | +| [Konfiguration](Configuration.de) | Umgebungsvariablen und Runtime-Konfiguration | +| [Container-Images](Container-Images.de) | Registry-Images, Tags, Manifeste und Branch-Suffixe | +| [Romexis Admin](Romexis-Admin.de) | Browserbasierter RomexisConfig-/Admin-Container über noVNC | +| [mRomexis Web App](mRomexis-WebApp.de) | Separater Tomcat-basierter mRomexis-Web-Frontend-Container | +| [Build-System](Build-System.de) | Payload-, Base-, Server-, Admin- und Web-App-Build-Workflow | +| [Lokale Build-Skripte](Local-Build-Scripts.de) | Lokale Build-Hilfsskripte für Linux/macOS und Windows | +| [Datenbank-Backends](Database-Backends.de) | MSSQL- und Firebird-Backend-Architektur | +| [Migrationsdienst](Migration-Service.de) | Web-UI, REST-API, SFTP und Wiederherstellungsworkflow | +| [Migrationsworkflow](Migration-Workflow.de) | Manueller und Client-gestützter Migrationsprozess | +| [CI/CD-Pipeline](CI-CD-Pipeline.de) | Drone-Pipeline und Veröffentlichungsprozess | +| [Entwicklerhandbuch](Developer-Guide.de) | Repository-Struktur und interne Entwicklungshinweise | +| [Fehlerbehebung](Troubleshooting.de) | Häufige Fehler und Lösungen | + +--- + +## Aktuelle Kernkomponenten + +```text +romexis-payload/ + Builds architecture-independent payload images from the official Windows installer. + +romexis-firebird-payload/ + Builds a Firebird SQL payload from the official macOS installer. + +romexis-base/ + Builds the reusable Java 11 runtime base image. + +romexis/ + Builds the final Romexis Server image. + +romexis-admin/ + Builds the browser-accessible Romexis Admin / RomexisConfig container. + +romexis-mromexis-app/ + Builds the standalone mRomexis Web App container from the Romexis payload WAR. + +migration-service/ + Provides browser-based and API-driven migration orchestration. + +migration-client/ + Provides the Windows migration helper client. + +scripts/ + Contains local build helpers such as build-local.sh and build-local.ps1. +``` + +--- + +## Aktuelles Runtime-Layout + +Die Runtime ist in eine Basis-Compose-Datei und Backend-spezifische Override-Dateien aufgeteilt: + +```text +docker-compose.yml + Base runtime services and shared configuration. + +docker-compose.mssql.yml + Microsoft SQL Server backend and MSSQL-specific Romexis settings. + +docker-compose.firebird.yml + Firebird backend and Firebird-specific Romexis settings. +``` + +Das aktive Backend wird in `.env` über `DATABASE_BACKEND` und `COMPOSE_FILE` ausgewählt. + +--- + +## Empfohlene Lesereihenfolge + +1. [Projektübersicht](Project-Overview.de) +2. [Architektur](Architecture.de) +3. [Compose-Runtime](Compose-Runtime.de) +4. [Schnellstart](Quick-Start.de) +5. [Konfiguration](Configuration.de) +6. [Romexis Admin](Romexis-Admin.de) +7. [mRomexis Web App](mRomexis-WebApp.de) +8. [Datenbank-Backends](Database-Backends.de) +9. [Build-System](Build-System.de) +10. [Entwicklerhandbuch](Developer-Guide.de) + +--- + +## Wichtige Hinweise + +- Es werden keine Romexis-Anwendungsbinärdateien in das Repository eingecheckt. +- Offizielle Planmeca-Installer-Pakete werden während der Payload-Builds heruntergeladen. +- Die Auswahl des Runtime-Backends wird über `.env` und die Docker-Compose-Dateiauswahl gesteuert. +- Microsoft SQL Server bleibt das standardmäßige und am umfassendsten getestete Backend. +- Firebird-Unterstützung ist über ein dediziertes Compose-Override verfügbar. +- Romexis Admin wird über einen separaten Browser-/noVNC-Container bereitgestellt. +- mRomexis Web App wird über einen separaten Tomcat-basierten Container bereitgestellt und benötigt Romexis 6.5.3 oder neuer. +- Der Migrationsdienst ist dafür vorgesehen, vorhandene Windows-basierte Romexis-Installationen in den Docker-Stack zu übertragen. diff --git a/Home.md b/Home.md index 8c19451..35187f5 100644 --- a/Home.md +++ b/Home.md @@ -1,3 +1,5 @@ +[Deutsch](Home.de) | **English** + # Romexis Docker Wiki Welcome to the Romexis Docker project wiki. diff --git a/Java-Property-Agent.de.md b/Java-Property-Agent.de.md new file mode 100644 index 0000000..d275c08 --- /dev/null +++ b/Java-Property-Agent.de.md @@ -0,0 +1,224 @@ +[**Deutsch**](Java-Property-Agent.de) | [English](Java-Property-Agent) + +# Java Property Agent + +## Zweck + +Der `RomexisPropertyAgent` ist ein kleiner Java-Instrumentation-Agent, den das Romexis-Docker-Projekt verwendet, um Romexis-`RxProperties` während des JVM-Starts zu konfigurieren. + +Er ermöglicht es, ausgewählte Romexis-Runtime-Eigenschaften durch Umgebungsvariablen zu setzen, bevor die Romexis-Server-Anwendung vollständig startet. + +Dies ist erforderlich, da bestimmtes Romexis-Verhalten sehr früh während des JVM-Starts festgelegt wird und später nicht zuverlässig durch Bearbeiten von Dateien im Container geändert werden kann. + +--- + +## Warum der Agent existiert + +Beim Start von `RomexisServer.jar` unter Linux wählte Romexis intern ein Verhalten aus, das dem macOS-Runtime-Pfad entsprach. + +Dieses macOS-spezifische Verhalten war mit der Linux-Docker-Umgebung nicht kompatibel. + +Die entscheidende Eigenschaft war: + +```text +KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES +``` + +Damit Romexis Server im Linux-Container korrekt startet, musste diese Eigenschaft gesetzt werden auf: + +```text +true +``` + +Dadurch verhält sich Romexis in diesem Bereich wie die Windows-Server-Runtime und verwendet den erwarteten, auf Server-Properties basierenden Speicherort des Key-Vault-Passworts. + +Ohne dieses Override konnte der Start von Romexis Server unter Linux fehlschlagen, weil die falsche plattformspezifische Property-Verarbeitung ausgewählt wurde. + +--- + +## Erforderliche Docker-Einstellung + +Die wichtigste derzeit vom Docker-Image verwendete Umgebungsvariable ist: + +```env +PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true +``` + +Diese wird vom Java-Agent übersetzt in: + +```java +RxProperties.setProperty( + RxProperties.KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES, + true +); +``` + +Dieses Override ist einer der Gründe, warum Romexis Server zuverlässig im Linux-basierten Container betrieben werden kann. + +--- + +## Warum ein Java-Agent statt Datei-Patches? + +Der Java-Agent-Ansatz vermeidet: + +- das Patchen von Romexis-Anwendungsdateien +- das Ändern proprietärer Romexis-JARs +- das Bearbeiten von Konfigurationsdateien, nachdem der Start bereits begonnen hat +- die Pflege benutzerdefinierter Binär-Patches +- das erneute Bauen von Romexis selbst + +Stattdessen kann die Docker-Runtime diese Einstellungen mit gewöhnlichen Umgebungsvariablen steuern. + +Dies ist sicherer, einfacher zu pflegen und besser für automatisierte Deployments geeignet. + +--- + +## Funktionsweise + +Der Agent wird von der JVM geladen, bevor die Romexis-Anwendung startet. + +Er durchsucht alle Umgebungsvariablen mit dem Präfix: + +```text +PROPERTY_AGENT_SET_ +``` + +Der Teil nach dem Präfix wird als Feldname aus folgender Klasse interpretiert: + +```java +romexis_lib_base.types.RxProperties +``` + +Beispiel: + +```env +PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true +``` + +Der Agent entfernt das Präfix: + +```text +KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES +``` + +Danach sucht er das passende öffentliche Feld in `RxProperties`. + +Existiert das Feld, liest der Agent den tatsächlichen Romexis-Property-Schlüssel und ruft die passende Methode `RxProperties.setProperty(...)` auf. + +--- + +## Unterstützte Werttypen + +Der Agent konvertiert Werte automatisch in einen der folgenden Typen: + +| Umgebungswert | Java-Typ | +|---|---| +| `true` / `false` | `Boolean` | +| Ganzzahlwerte | `Integer` | +| alle anderen Werte | `String` | + +--- + +## Unbekannte Properties + +Referenziert eine Umgebungsvariable ein Feld, das in `RxProperties` nicht existiert, lässt der Agent den Start nicht fehlschlagen. + +Stattdessen protokolliert er eine Warnung: + +```text +JavaAgent WARN: RxProperties field not found: +``` + +Damit ist der Mechanismus für optionale oder versionsabhängige Properties sicher. + +--- + +## Vorgesehene Anwendungsfälle + +Der Java Property Agent ist vorgesehen für: + +- Docker-Deployments +- Kubernetes-Deployments +- automatisiertes Konfigurationsmanagement +- Runtime-Anpassungen +- Korrekturen der Plattformkompatibilität +- kontrollierte Overrides des Romexis-Serververhaltens + +--- + +## Build-Integration + +Der Quellcode des Agents wird beim Build des Romexis-Server-Images kompiliert. + +Das Dockerfile verwendet eine dedizierte Build-Stage: + +```text +agent-build +``` + +Das Ergebnis wird in das finale Image kopiert als: + +```text +/opt/romexis/server/RomexisPropertyAgent.jar +``` + +Das JAR-Manifest enthält: + +```text +Premain-Class: RomexisPropertyAgent +``` + +Dadurch kann die JVM es laden über: + +```text +-javaagent:/opt/romexis/server/RomexisPropertyAgent.jar +``` + +--- + +## Runtime-Integration + +Der Romexis-Entrypoint fügt den Java-Agent dem JVM-Startbefehl von Romexis Server hinzu. + +Das Property-Override wird damit angewendet, bevor `RomexisServer.jar` seine normale Startsequenz fortsetzt. + +Typische Runtime-Konfiguration: + +```env +PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true +``` + +--- + +## Beispielhafte Log-Ausgabe + +Erfolgreiche Anwendung der Eigenschaft: + +```text +JavaAgent: set KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true +JavaAgent: 1 properties applied +``` + +Unbekannte Eigenschaft: + +```text +JavaAgent WARN: RxProperties field not found: SOME_UNKNOWN_FIELD +``` + +--- + +## Wichtige Hinweise + +- Der Agent verändert keine Romexis-Binärdateien. +- Der Agent patcht keine Klassendateien. +- Der Agent ruft ausschließlich öffentliche `RxProperties`-Felder und Setter-Methoden auf. +- Unbekannte Felder werden mit einer Warnung ignoriert. +- Dieser Mechanismus sollte nur für Eigenschaften verwendet werden, die verstanden und bewusst überschrieben werden. + +--- + +## Aktuell entscheidende Eigenschaft + +| Eigenschaft | Wert | Grund | +|---|---|---| +| `KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES` | `true` | Zwingt Romexis Server zu dem auf Server-Properties basierenden Verhalten, das für den Linux-Docker-Start erforderlich ist | diff --git a/Java-Property-Agent.md b/Java-Property-Agent.md index 9cf6f66..7f6e2fb 100644 --- a/Java-Property-Agent.md +++ b/Java-Property-Agent.md @@ -1,3 +1,5 @@ +[Deutsch](Java-Property-Agent.de) | **English** + # Java Property Agent ## Purpose diff --git a/Local-Build-Scripts.de.md b/Local-Build-Scripts.de.md new file mode 100644 index 0000000..6b6447f --- /dev/null +++ b/Local-Build-Scripts.de.md @@ -0,0 +1,124 @@ +**Deutsch** | [English](Local-Build-Scripts) + +# Lokale Buildskripte + +Lokale Image-Builds werden über spezielle Hilfsskripte ausgeführt. + +`docker-compose.build.yml` wird nicht mehr benötigt. + +--- + +## Dateien + +```text +scripts/build-local.sh +scripts/build-local.ps1 +``` + +--- + +## Linux / macOS + +```bash +chmod +x scripts/build-local.sh +./scripts/build-local.sh all +``` + +--- + +## Windows PowerShell + +```powershell +.\scripts\build-local.ps1 -Targets all +``` + +--- + +## Buildziele + +Verfügbare Zielgruppen: + +```text +all +base +server +admin +mromexis +migration +``` + +Beispiele: + +```bash +./scripts/build-local.sh base server +./scripts/build-local.sh admin mromexis +./scripts/build-local.sh migration +``` + +PowerShell-Beispiele: + +```powershell +.\scripts\build-local.ps1 -Targets base,server +.\scripts\build-local.ps1 -Targets admin,mromexis +``` + +--- + +## Umgebungsvariablen + +Die Skripte verwenden dieselben Variablen wie die Compose-Laufzeitkonfiguration. + +Wichtige Beispiele: + +```env +REGISTRY=gitea.buchhorster.de/planmeca +ROMEXIS_VERSION=6.5.3.444.203 +TARGETARCH=amd64 +IMAGE_SUFFIX= + +ROMEXIS_IMAGE=romexis-server +MIGRATION_IMAGE=romexis-migration-service +ADMINISTRATION_IMAGE=romexis-admin +MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app +``` + +Für Feature-Branches: + +```env +IMAGE_SUFFIX=-feature-romexis-admin +``` + +--- + +## Beziehung zu Runtime Compose + +Die Buildskripte erstellen die Image-Tags, welche die Runtime-Compose-Dateien erwarten. + +Runtime Compose verwendet Image-Referenzen im Manifeststil, beispielsweise: + +```text +${REGISTRY}/${ROMEXIS_IMAGE}:${ROMEXIS_VERSION}${IMAGE_SUFFIX} +${REGISTRY}/${ADMINISTRATION_IMAGE}:latest${IMAGE_SUFFIX} +${REGISTRY}/${MROMEXIS_WEBAPP_IMAGE}:${ROMEXIS_VERSION}${IMAGE_SUFFIX} +``` + +Dadurch kann dieselbe `.env` für lokale Builds und den Start der Laufzeit verwendet werden. + +--- + +## Typischer Workflow + +```bash +cp .env.sample .env +nano .env + +./scripts/build-local.sh all + +docker compose up -d +``` + +Den ausgewählten Laufzeit-Stack untersuchen: + +```bash +docker compose config +``` diff --git a/Local-Build-Scripts.md b/Local-Build-Scripts.md index 1944d95..2425600 100644 --- a/Local-Build-Scripts.md +++ b/Local-Build-Scripts.md @@ -1,3 +1,5 @@ +[Deutsch](Local-Build-Scripts.de) | **English** + # Local Build Scripts Local image builds are handled through dedicated helper scripts. diff --git a/Microsoft-SQL-Server.de.md b/Microsoft-SQL-Server.de.md new file mode 100644 index 0000000..0fc7e87 --- /dev/null +++ b/Microsoft-SQL-Server.de.md @@ -0,0 +1,79 @@ +**Deutsch** | [English](Microsoft-SQL-Server) + +# Microsoft SQL Server + +Microsoft SQL Server ist das standardmäßige und am umfassendsten getestete Datenbank-Backend. + +--- + +## Compose-Dienst + +Der MSSQL-Dienst verwendet das offizielle Microsoft-SQL-Server-Image: + +```yaml +mssql: + image: mcr.microsoft.com/mssql/server:2022-latest + container_name: romexis-mssql + environment: + ACCEPT_EULA: "Y" + MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}" + MSSQL_PID: "${MSSQL_PID:-Express}" + ports: + - "${MSSQL_PORT}:1433" + volumes: + - mssql_data:/var/opt/mssql + - ${DATABASE_BACKUP_DIR}:/var/opt/mssql/backup +``` + +--- + +## Romexis-Einstellungen + +```env +SERVER_DB=5 +MSSQL_HOST=mssql +MSSQL_PORT=1433 +MSSQL_SA_PASSWORD= + +ROMEXIS_DB_NAME=Romexis_db +ROMEXIS_DB_USER=romexis +ROMEXIS_DB_PASSWORD= +``` + +Erzeugte JDBC-URL: + +```text +jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true; +``` + +--- + +## Initialisierung + +Das MSSQL-Initialisierungsprogramm: + +```text +/opt/init-romexis-mssql-db.sh +``` + +Verantwortlichkeiten: + +- auf SQL Server warten +- die Romexis-Datenbank erstellen, falls sie fehlt +- den Romexis-Datenbankbenutzer erstellen oder aktualisieren +- Basis-SQL-Skripte importieren +- Aktualisierungsskripte bis zur Ziel-Schemamarkierung importieren +- Laufzeitpfade in `RBA_Server_Param_S` aktualisieren + +--- + +## Backup-Verzeichnis + +`DATABASE_BACKUP_DIR` wird sowohl in den Migrationsdienst als auch in SQL Server eingebunden: + +```text +Migration service: /upload/database +SQL Server: /var/opt/mssql/backup +``` + +Dadurch kann der Migrationsdienst eine `.bak`-Datei hochladen und die Wiederherstellung der Datenbank auslösen. diff --git a/Microsoft-SQL-Server.md b/Microsoft-SQL-Server.md index 51d8661..5219a5c 100644 --- a/Microsoft-SQL-Server.md +++ b/Microsoft-SQL-Server.md @@ -1,3 +1,5 @@ +[Deutsch](Microsoft-SQL-Server.de) | **English** + # Microsoft SQL Server Microsoft SQL Server is the default and most tested database backend. diff --git a/Migration-Client.de.md b/Migration-Client.de.md new file mode 100644 index 0000000..3b67ec9 --- /dev/null +++ b/Migration-Client.de.md @@ -0,0 +1,56 @@ +**Deutsch** | [English](Migration-Client) + +# Migrationsclient + +Der Migrationsclient ist das quellseitige Hilfsprogramm für geführte Migrationen aus bestehenden Romexis-Installationen. + +Aktuelle Ausrichtung: + +```text +Windows client first +Future: evaluate C# for broader platform support +``` + +--- + +## Verantwortlichkeiten + +Der Client sollte bei Folgendem helfen: + +- lokale Romexis-Installationspfade erkennen +- SQL-Server-Verbindungseinstellungen erkennen +- ein Datenbankbackup erstellen +- Romexis-Bild- und Ergodataverzeichnisse erkennen +- über die API des Migrationsdienstes einen Migrationsjob erstellen +- Daten über rclone/SFTP hochladen +- API-Endpunkte aufrufen, um den Workflowstatus weiterzuschalten +- Fortschritt und Protokolle anzeigen + +--- + +## Warum rclone? + +rclone eignet sich für große Migrationen, weil es Folgendes unterstützt: + +- SFTP +- Fortschrittsausgabe +- Wiederholungsversuche +- fortsetzbare Workflows +- Verzeichnissynchronisierung +- konfigurierbare Transfers und Checker + +--- + +## Ausrichtung Python gegenüber C# + +Der erste Client basiert auf Python, weil er sich schnell entwickeln und einfach in bestehende Skripte integrieren lässt. + +Für eine zukünftige macOS-Unterstützung könnte C# langfristig die bessere Option sein, weil es Folgendes bieten kann: + +- nativen Windows-Build +- möglichen macOS-Build +- leistungsfähigere GUI-Optionen +- einfachere Paketierung als einzelne Binärdatei +- bessere langfristige Wartbarkeit für einen Desktop-Migrationsclient + +Die README sollte dies als architektonische Ausrichtung und nicht als bereits fertiggestellte Funktion darstellen. diff --git a/Migration-Client.md b/Migration-Client.md index 090060e..6979f88 100644 --- a/Migration-Client.md +++ b/Migration-Client.md @@ -1,3 +1,5 @@ +[Deutsch](Migration-Client.de) | **English** + # Migration Client The migration client is the source-side helper for guided migrations from existing Romexis installations. diff --git a/Migration-Service.de.md b/Migration-Service.de.md new file mode 100644 index 0000000..ebc3b0d --- /dev/null +++ b/Migration-Service.de.md @@ -0,0 +1,155 @@ +[**Deutsch**](Migration-Service.de) | [English](Migration-Service) + +# Migrationsdienst + +Der Romexis-Migrationsdienst hilft dabei, eine vorhandene Romexis-Installation in den Docker-basierten Romexis-Server-Stack zu migrieren. + +Er stellt bereit: + +- Flask-Web-UI +- REST-API +- temporäre SFTP-Benutzer +- Zustandsverfolgung von Migrationsjobs +- Upload von Datenbanksicherungen +- Manifest-Erstellung +- Upload-Validierung +- Orchestrierung der Wiederherstellung +- abschließenden Abschluss-/Abbruchworkflow + +--- + +## Warum ein Migrationsdienst? + +Romexis-Installationen können enthalten: + +- große SQL-Server-Sicherungen +- große Bildverzeichnisse +- Ergo-Datenverzeichnisse +- Cache-Verzeichnisse +- sehr viele kleine Dateien + +Browser-Uploads allein sind dafür nicht ideal. Deshalb kombiniert der Migrationsdienst: + +```text +Web UI / API + for orchestration and state + +SFTP + for large file and directory transfer +``` + +--- + +## Zustand eines Migrationsjobs + +Migrationsjobs werden als JSON-Zustandsdateien gespeichert. + +Typischer Workflow: + +```text +created + -> database_uploaded + -> database_restored + -> upload_complete + -> validated + -> restored + -> completed +``` + +Endzustände: + +```text +completed +cancelled +failed +``` + +--- + +## Lebenszyklus der SFTP-Benutzer + +Der Dienst erstellt für jede aktive Migration einen temporären SFTP-Benutzer. + +Wichtiges Verhalten: + +- aktive Jobs erstellen ihre SFTP-Benutzer beim Start des Dienstes erneut +- abgeschlossene Jobs dürfen keine SFTP-Benutzer erneut erstellen +- abgebrochene Jobs dürfen keine SFTP-Benutzer erneut erstellen +- fehlgeschlagene Jobs dürfen keine SFTP-Benutzer erneut erstellen, sofern sie nicht bewusst reaktiviert wurden +- das Abschließen oder Abbrechen eines Jobs entfernt oder deaktiviert den temporären SFTP-Zugriff + +--- + +## Manueller Browser-Workflow + +1. Migrationsjob in der Web-UI erstellen. +2. Datenbanksicherung über den Browser hochladen. +3. Der Dienst erstellt automatisch `manifest.json`. +4. Datenbankwiederherstellung auslösen. +5. Dateiverzeichnisse über SFTP hochladen. +6. Upload als abgeschlossen markieren. +7. Upload validieren. +8. Wiederherstellung ausführen. +9. Migration abschließen und SFTP-Zugriff entfernen. + +--- + +## SFTP-Upload + +Die Web-UI zeigt die SFTP-Zugangsdaten und Beispielbefehle an. + +Typische rclone-Einrichtung: + +```bash +rclone config create romexis-migration sftp \ + host \ + port \ + user \ + pass "$(rclone obscure '')" +``` + +Bilder hochladen: + +```bash +rclone sync "/PATH/TO/LOCAL/romexis_images" \ + "romexis-migration:/romexis_images" \ + --progress \ + --transfers 4 \ + --checkers 8 +``` + +Ergo-Daten hochladen: + +```bash +rclone sync "/PATH/TO/LOCAL/romexis_ergodata" \ + "romexis-migration:/romexis_ergodata" \ + --progress \ + --transfers 4 \ + --checkers 8 +``` + +Optionaler Cache-Upload: + +```bash +rclone sync "/PATH/TO/LOCAL/romexis_cache" \ + "romexis-migration:/romexis_cache" \ + --progress \ + --transfers 4 \ + --checkers 8 +``` + +--- + +## Neustartkoordination + +Der Migrationsdienst und der Romexis-Container koordinieren Neustarts über eine gemeinsame Zustandsdatei: + +```text +/data/romexis_images/.romexis_restart_state +``` + +Der Migrationsdienst schreibt eine ausstehende Neustartanforderung. + +Der Romexis-Entrypoint/-Prozess beobachtet den Zustand, startet den Romexis-Dienst neu und schreibt das Ergebnis. + +Der Migrationsdienst liest das Ergebnis und entfernt die Zustandsdatei. diff --git a/Migration-Service.md b/Migration-Service.md index 9b1a83f..35ac1f9 100644 --- a/Migration-Service.md +++ b/Migration-Service.md @@ -1,3 +1,5 @@ +[Deutsch](Migration-Service.de) | **English** + # Migration Service The Romexis Migration Service helps migrate an existing Romexis installation into the Docker-based Romexis Server stack. diff --git a/Migration-Workflow.de.md b/Migration-Workflow.de.md new file mode 100644 index 0000000..079f259 --- /dev/null +++ b/Migration-Workflow.de.md @@ -0,0 +1,165 @@ +[**Deutsch**](Migration-Workflow.de) | [English](Migration-Workflow) + +# Migrationsworkflow + +Diese Seite beschreibt den vorgesehenen Migrationsworkflow von einem vorhandenen Romexis-Server in den Docker-basierten Romexis-Stack. + +--- + +## Quellsystem + +Das Quellsystem ist üblicherweise ein Windows-basierter Romexis-Server. + +Erforderliche Daten: + +```text +SQL Server database backup (.bak) +Romexis image directory +Romexis ergo data directory +optional Romexis cache directory +``` + +Das Cache-Verzeichnis ist optional, da es normalerweise neu erzeugt werden kann. + +--- + +## Zielsystem + +Auf dem Zielsystem laufen: + +```text +Romexis Server container +Database backend container +Migration Service container +Persistent data volumes +``` + +--- + +## Workflow-Übersicht + +```text +Existing Romexis Server + | + | database backup + | image data + | ergo data + v +Romexis Migration Service + | + | validation + | database restore + | data restore + v +Docker-based Romexis Server +``` + +--- + +## Manueller Workflow + +1. Migrations-Web-UI öffnen. +2. Neuen Migrationsjob erstellen. +3. Datenbanksicherung im Browser hochladen. +4. Den Dienst `manifest.json` erstellen lassen. +5. Datenbankwiederherstellung auslösen. +6. Bilder und Ergo-Daten über SFTP hochladen. +7. Upload als abgeschlossen markieren. +8. Hochgeladene Daten validieren. +9. Wiederherstellung ausführen. +10. Migration abschließen. +11. SFTP-Zugangsdaten werden entfernt oder deaktiviert. + +--- + +## Client-gestützter Workflow + +Der Migrationsclient soll die meisten Schritte auf der Quellseite automatisieren: + +1. Romexis-Installation erkennen +2. Datenbankkonfiguration erkennen +3. Datenverzeichnisse erkennen +4. Migrationsjob erstellen oder verwenden +5. Datenbanksicherung erstellen +6. Daten über rclone/SFTP hochladen +7. API-Endpunkte aufrufen, um den Workflow voranzubringen +8. Logs und Wiederherstellungsstatus anzeigen + +--- + +## Erwartetes Upload-Layout + +```text +/upload/ +├── meta/ +│ └── manifest.json +├── database/ +│ └── Romexis_db.bak +├── romexis_images/ +├── romexis_ergodata/ +└── romexis_cache/ +``` + +--- + +## Manifest + +Das Manifest beschreibt die hochgeladenen Migrationsdaten. + +Beispiel: + +```json +{ + "migration_id": "example", + "name": "Example Migration", + "source_host": "old-romexis-server", + "database": { + "backup": "database/Romexis_db.bak" + }, + "romexis_images": true, + "romexis_ergodata": true, + "romexis_cache": false +} +``` + +Der manuelle Browser-Workflow kann dieses Manifest nach dem Datenbank-Upload automatisch erzeugen. + +--- + +## Validierung + +Die Validierung sollte prüfen: + +- Manifest ist vorhanden +- Datenbanksicherung ist vorhanden +- Bildverzeichnis ist vorhanden +- Ergo-Datenverzeichnis ist vorhanden +- optionales Cache-Verzeichnis ist vorhanden, wenn angefordert +- Dateianzahlen +- Gesamtzahl der Bytes +- zukünftige Prüfsummendaten + +--- + +## Wiederherstellung + +Der Wiederherstellungsschritt führt aus oder koordiniert: + +1. Datenbankwiederherstellung +2. Platzierung der Dateien in den Ziel-Volumes +3. Korrektur der Berechtigungen +4. Neustart von Romexis +5. abschließende Statusmeldung + +--- + +## Abschluss + +Nach einer erfolgreichen Wiederherstellung sollte der Job als abgeschlossen markiert werden. + +Der Abschluss sollte: + +- den temporären SFTP-Benutzer entfernen oder deaktivieren +- Workflow-Aktionsschaltflächen ausblenden +- Logs verfügbar halten +- die Migrationszustandsdatei für Audit/Debugging aufbewahren diff --git a/Migration-Workflow.md b/Migration-Workflow.md index 6b83d36..5554429 100644 --- a/Migration-Workflow.md +++ b/Migration-Workflow.md @@ -1,3 +1,5 @@ +[Deutsch](Migration-Workflow.de) | **English** + # Migration Workflow This page describes the target migration workflow from an existing Romexis server into the Docker-based Romexis stack. diff --git a/Payload-Images.de.md b/Payload-Images.de.md new file mode 100644 index 0000000..29e9434 --- /dev/null +++ b/Payload-Images.de.md @@ -0,0 +1,137 @@ +**Deutsch** | [English](Payload-Images) + +# Payload-Images + +Payload-Images sind wiederverwendbare Zwischenimages, die extrahierte Installerinhalte enthalten. + +--- + +## Windows-Payload + +Verzeichnis: + +```text +romexis-payload/ +``` + +Zweck: + +- offiziellen Windows-Installer herunterladen +- erforderliche InstallShield-CAB-Komponenten extrahieren +- `/opt/romexis` erstellen +- MSSQL-Initialisierungs-SQL-Dateien extrahieren +- `/opt/romexis/version` schreiben + +Ausgabevertrag: + +```text +/opt/romexis +/opt/romexis-mssql-db +/opt/romexis/version +/opt/romexis/server/RomexisServer.jar +``` + +Das Payload darf keine architekturspezifischen Laufzeitbibliotheken wie Chilkat enthalten. + +--- + +## Versionsdatei + +Unterstützte URLs für Windows-Installer werden hier gepflegt: + +```text +romexis-payload/romexis-versions.env +``` + +Beispiel: + +```text +6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip +``` + +--- + +## Kopierzuordnung + +Die Installerextraktion wird gesteuert durch: + +```text +romexis-payload/romexis-copy-map.tsv +``` + +Format: + +```text +SourceDestination +``` + +Beispiel: + +```text +Server_jar /opt/romexis/server +Server_Program_64bit/server/*.xml /opt/romexis/server +``` + +Wenn sich diese Zuordnung ändert, sollten alle Payload-Versionen neu gebaut werden, weil sich das extrahierte Laufzeitlayout geändert haben kann. + +--- + +## Firebird-Payload + +Verzeichnis: + +```text +romexis-firebird-payload/ +``` + +Zweck: + +- offizielles macOS-DMG herunterladen +- PKG-Payloads extrahieren +- Firebird-Datenbank-SQL-Skripte sammeln +- ursprüngliche Hilfsskripte für Backup und Wiederherstellung sammeln +- `romexis_new.fdb` als Referenz/Vorlage aufnehmen + +Ausgabevertrag: + +```text +/opt/romexis-firebird-db/version +/opt/romexis-firebird-db/scripts +/opt/romexis-firebird-db/tools +/opt/romexis-firebird-db/templates +/opt/romexis-firebird-db/layout +``` + +Wichtige Dateien: + +```text +/opt/romexis-firebird-db/scripts/rxdb.sh +/opt/romexis-firebird-db/scripts/rxupd.sh +/opt/romexis-firebird-db/scripts/RX_Base_10fb_MAC.sql +/opt/romexis-firebird-db/scripts/RX_Update_653.sql +/opt/romexis-firebird-db/tools/Romexis_Firebird_Backup.sh +/opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh +/opt/romexis-firebird-db/templates/romexis_new.fdb +``` + +--- + +## Ein Payload-Image untersuchen + +Wenn ein Payload-Image auf `scratch` basiert, besitzt es möglicherweise keine Shell. + +Verwendung: + +```bash +docker save gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest -o payload.tar +mkdir payload rootfs +tar -xf payload.tar -C payload +tar -xf payload//layer.tar -C rootfs +find rootfs/opt -type f | sort +``` + +Wenn das Image eine Shell enthält: + +```bash +docker run --rm -it --entrypoint sh gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest +``` diff --git a/Payload-Images.md b/Payload-Images.md index 02e0441..da84876 100644 --- a/Payload-Images.md +++ b/Payload-Images.md @@ -1,3 +1,5 @@ +[Deutsch](Payload-Images.de) | **English** + # Payload Images Payload images are reusable intermediate images containing extracted installer content. diff --git a/Project-Overview.de.md b/Project-Overview.de.md new file mode 100644 index 0000000..5cdc522 --- /dev/null +++ b/Project-Overview.de.md @@ -0,0 +1,173 @@ +[**Deutsch**](Project-Overview.de) | [English](Project-Overview) + +# Projektübersicht + +## Zweck + +Das Romexis-Docker-Projekt stellt eine reproduzierbare Docker-basierte Umgebung für den Betrieb von Planmeca Romexis Server unter Linux bereit. + +Das Projekt wurde dafür entwickelt: + +- Romexis Server in Containern auszuführen +- die Runtime-Konfiguration zu externalisieren +- das Datenbank-Backend über die Docker-Compose-Konfiguration auszuwählen +- manuelle, Windows-typische Einrichtungsschritte zu vermeiden +- persistente Anwendungs- und Datenbankdaten zu unterstützen +- browserbasierten Zugriff auf Romexis Admin / RomexisConfig bereitzustellen +- mRomexis Web App als separaten Web-Container bereitzustellen +- die Migration vorhandener Installationen zu unterstützen +- wiederholbare lokale und CI/CD-Builds zu unterstützen +- einen Weg für Microsoft SQL Server und Firebird als Datenbank-Backends vorzubereiten + +--- + +## Wichtigste Runtime-Dienste + +```text +romexis + Romexis Server backend runtime. + +mssql / firebird + Selected database backend loaded through Compose override files. + +romexis-admin + Browser-accessible Romexis Admin / RomexisConfig runtime using noVNC. + +romexis-app + Tomcat-based mRomexis Web App container. + +proxy + OpenResty/Nginx proxy for mRomexis Web App backend access. + +romexis-migration + Optional migration service for MSSQL-based migration workflows. +``` + +--- + +## Designprinzipien + +### Keine Romexis-Binärdateien in Git + +Das Repository enthält keine Romexis-Anwendungsbinärdateien. + +Stattdessen lädt der Build-Prozess offizielle Installer-Pakete herunter und extrahiert ausschließlich die erforderlichen Server-, Admin- und Web-Komponenten in Payload-Images. + +### Mehrschichtige Image-Architektur + +Das Build-System ist in wiederverwendbare Schichten aufgeteilt: + +```text +Payload image + Contains extracted Romexis application files, SQL payload and web/admin artifacts. + +Base image + Contains reusable runtime dependencies such as Java, JavaFX and database tools. + +Service images + Build server, admin, migration and mRomexis runtime containers from the prepared layers. +``` + +### Architekturunabhängige Payloads + +Die Romexis-Payload selbst ist architekturunabhängig. Architekturspezifische Bestandteile wie native Bibliotheken verbleiben in den Service-Runtime-Images. + +Dieselbe Payload kann wiederverwendet werden für: + +```text +linux/amd64 +linux/arm64 +``` + +### Compose-basierte Backend-Auswahl + +Datenbank-Backends werden über `.env` ausgewählt: + +```env +DATABASE_BACKEND=mssql +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Das Backend-spezifische Compose-Override setzt den korrekten Datenbankdienst und die Romexis-Datenbank-Umgebungswerte. + +--- + +## Hauptfunktionen + +- Romexis-Server-6.5-Docker-Runtime +- Microsoft-SQL-Server-2022-Backend +- Firebird-Backend über Compose-Override +- automatische Datenbankinitialisierung +- persistente Runtime-Volumes +- Java Property Agent zur serverseitigen Injektion von Runtime-Eigenschaften +- versionierte Payload-Images +- Multi-Architektur-Service-Images +- Romexis-Admin-Container mit Browser-/noVNC-Zugriff +- durch VNC-Sitzungen gesteuerter Admin-Lebenszyklus +- lokalisierter Admin-Startbildschirm +- mRomexis-Web-App-Container für Romexis 6.5.3 und neuer +- OpenResty-/Nginx-Proxy für mRomexis-Backend-Anfragen +- lokale Build-Skripte für Linux/macOS und Windows +- Drone-CI/CD-Pipeline +- Migrationsdienst mit Web-UI, REST-API und SFTP +- Windows-Migrationsclient +- Veröffentlichung in der Gitea-Paket-Registry + +--- + +## Unterstützte Plattformen + +| Plattform | Status | +|---|---| +| linux/amd64 | Primär unterstütztes Ziel | +| linux/arm64 | Für Romexis-Runtime-Images unterstützt | +| Microsoft SQL Server auf amd64 | Standard-Backend | +| Firebird auf amd64/arm64 | Über dediziertes Compose-Override unterstützt | +| Romexis Admin über noVNC | Browserbasierter Zugriff | +| mRomexis Web App | Erfordert Romexis 6.5.3 oder neuer | +| macOS-Quellmigrationen | Über Firebird- und Client-Workflow geplant | + +--- + +## Repository-Bereiche + +```text +romexis-base/ + Reusable runtime base image. + +romexis-payload/ + Windows installer payload extraction. + +romexis-firebird-payload/ + macOS Firebird SQL payload extraction. + +romexis/ + Final Romexis Server image. + +romexis-admin/ + Romexis Admin / RomexisConfig noVNC image. + +romexis-mromexis-app/ + mRomexis Web App Tomcat image. + +migration-service/ + Migration orchestration service. + +migration-client/ + Migration helper client. + +scripts/ + Local build helper scripts. + +docker-compose.yml + Base runtime stack. + +docker-compose.mssql.yml + Microsoft SQL Server backend override. + +docker-compose.firebird.yml + Firebird backend override. + +.drone.yml + CI/CD pipeline. +``` diff --git a/Project-Overview.md b/Project-Overview.md index 62a1771..01eb50e 100644 --- a/Project-Overview.md +++ b/Project-Overview.md @@ -1,3 +1,5 @@ +[Deutsch](Project-Overview.de) | **English** + # Project Overview ## Purpose diff --git a/Project-Structure.de.md b/Project-Structure.de.md new file mode 100644 index 0000000..4e05497 --- /dev/null +++ b/Project-Structure.de.md @@ -0,0 +1,104 @@ +**Deutsch** | [English](Project-Structure) + +# Projektstruktur + +```text +. +├── .drone.yml +├── .env.sample +├── docker-compose.yml +├── docker-compose.mssql.yml +├── docker-compose.firebird.yml +├── README.md +├── README.de.md +├── BUILD.md +├── BUILD.de.md +├── DEVELOPERS.md +├── scripts/ +│ ├── build-local.sh +│ └── build-local.ps1 +├── romexis-base/ +│ └── Dockerfile +├── romexis-payload/ +│ ├── Dockerfile +│ ├── romexis-versions.env +│ ├── romexis-copy-map.tsv +│ ├── download-romexis-installer-parts.py +│ └── extract-and-copy-romexis-parts.sh +├── romexis-firebird-payload/ +│ ├── Dockerfile +│ ├── romexis-firebird-versions.env +│ └── helper scripts +├── romexis/ +│ ├── Dockerfile +│ ├── entrypoint.sh +│ ├── init-romexis-db.sh +│ ├── init-romexis-mssql-db.sh +│ ├── init-romexis-firebird-db.sh +│ ├── fix-keystore-alias.sh +│ └── RomexisPropertyAgent.java +├── romexis-admin/ +│ ├── Dockerfile +│ ├── start.sh +│ └── native helper sources +├── romexis-mromexis-app/ +│ ├── Dockerfile +│ └── nginx.conf +├── migration-service/ +│ ├── Dockerfile +│ ├── entrypoint.sh +│ ├── app/ +│ ├── scripts/ +│ └── ssh/ +└── migration-client/ + └── client files +``` + +--- + +## Compose-Dateien + +```text +docker-compose.yml + Base runtime stack. + +docker-compose.mssql.yml + MSSQL backend override. + +docker-compose.firebird.yml + Firebird backend override. +``` + +Das aktive Backend wird in `.env` ausgewählt: + +```env +DATABASE_BACKEND=mssql +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +--- + +## Buildskripte + +```text +scripts/build-local.sh +scripts/build-local.ps1 +``` + +Diese ersetzen den alten lokalen Workflow mit `docker-compose.build.yml`. + +--- + +## Dokumentationsdateien im Wurzelverzeichnis + +Die wichtigsten Dokumentationsdateien bleiben im Wurzelverzeichnis des Repositorys: + +```text +README.md +README.de.md +BUILD.md +BUILD.de.md +DEVELOPERS.md +``` + +Das Wiki stellt eine navigierbare, benutzerorientierte Dokumentationsebene bereit. diff --git a/Project-Structure.md b/Project-Structure.md index 5003366..5b391b4 100644 --- a/Project-Structure.md +++ b/Project-Structure.md @@ -1,3 +1,5 @@ +[Deutsch](Project-Structure.de) | **English** + # Project Structure ```text diff --git a/Quick-Start.de.md b/Quick-Start.de.md new file mode 100644 index 0000000..54712bc --- /dev/null +++ b/Quick-Start.de.md @@ -0,0 +1,208 @@ +**Deutsch** | [English](Quick-Start) + +# Schnellstart + +## 1. Umgebung vorbereiten + +Die Beispiel-Umgebungsdatei kopieren: + +```bash +cp .env.sample .env +``` + +`.env` bearbeiten und mindestens Romexis-Version, Registry-Namespace, Backend-Auswahl und Passwörter festlegen. + +Minimales MSSQL-Beispiel: + +```env +REGISTRY=gitea.buchhorster.de/planmeca +ROMEXIS_VERSION=6.5.3.444.203 +IMAGE_SUFFIX= + +ROMEXIS_IMAGE=romexis-server +MIGRATION_IMAGE=romexis-migration-service +ADMINISTRATION_IMAGE=romexis-admin +MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app + +DATABASE_BACKEND=mssql +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml + +HOST_IP=192.168.65.100 + +MSSQL_PORT=1433 +MSSQL_SA_PASSWORD=Pwr0mex!s!!! +MSSQL_PID=Express + +ROMEXIS_DB_NAME=Romexis_db +ROMEXIS_DB_USER=romexis +ROMEXIS_DB_PASSWORD=romexis + +SERVER_RMI_LOW_PORT=1100 +SERVER_RMI_HIGH_PORT=1120 + +ROMEXIS_DATA_ROOT=/srv/romexis-data +DATABASE_BACKUP_DIR=/srv/romexis-data/sql-backup + +ADMIN_NOVNC_PORT=6080 +ADMIN_VNC_PORT=5900 +ADMIN_VNC_PASSWORD=promax +ADMIN_RESOLUTION=1280x900x24 +ADMIN_LANGUAGE=de +DEBUG_XTERM=false +ADMIN_VNC_LIFECYCLE=true + +MROMEXIS_WEB_PORT=8081 + +MIGRATION_HTTP_PORT=8080 +MIGRATION_SFTP_PORT=2222 +MIGRATION_API_TOKEN=change-me +``` + +Für Firebird die Backend-Auswahl ändern: + +```env +DATABASE_BACKEND=firebird +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +--- + +## 2. Ausgewählten Stack starten + +Nach der Konfiguration von `.env` wird für MSSQL und Firebird derselbe Befehl verwendet: + +```bash +docker compose up -d +``` + +Die wirksame Compose-Konfiguration anzeigen: + +```bash +docker compose config +``` + +--- + +## 3. Protokolle anzeigen + +```bash +docker compose logs -f romexis +``` + +Protokolle des Datenbank-Backends: + +```bash +docker compose logs -f mssql +# or +docker compose logs -f firebird +``` + +Protokolle des Admin-Containers: + +```bash +docker compose logs -f romexis-admin +``` + +Protokolle der mRomexis Web App: + +```bash +docker compose logs -f romexis-app +``` + +--- + +## 4. Browserbasierte Dienste öffnen + +Romexis Admin / RomexisConfig über noVNC: + +```text +http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true +``` + +mRomexis Web App über den Proxy: + +```text +http://localhost:8081 +``` + +Die Ports entsprechend anpassen, wenn `ADMIN_NOVNC_PORT` oder `MROMEXIS_WEB_PORT` in `.env` geändert wurden. + +--- + +## 5. Nach Image-Änderungen neu erstellen + +```bash +docker compose up -d --force-recreate +``` + +Abrufen und neu erstellen: + +```bash +docker compose pull +docker compose up -d --force-recreate +``` + +--- + +## 6. Shells zum Debuggen öffnen + +Romexis-Server: + +```bash +docker compose exec romexis bash +``` + +Shell des Admin-Images: + +```bash +docker compose run --rm --entrypoint /bin/bash romexis-admin +``` + +Shell der mRomexis Web App: + +```bash +docker compose run --rm --entrypoint /bin/bash romexis-app +``` + +--- + +## 7. Lokale Image-Builds + +Linux/macOS: + +```bash +chmod +x scripts/build-local.sh +./scripts/build-local.sh all +``` + +Windows PowerShell: + +```powershell +.\scripts\build-local.ps1 -Targets all +``` + +Einzelne Ziele bauen: + +```bash +./scripts/build-local.sh base server +./scripts/build-local.sh admin mromexis +./scripts/build-local.sh migration +``` + +--- + +## 8. Stack stoppen + +```bash +docker compose down +``` + +Stoppen und Volumes entfernen: + +```bash +docker compose down -v +``` + +Das Entfernen von Volumes mit Vorsicht verwenden, weil dadurch persistente Datenbank- und Anwendungsdaten gelöscht werden. diff --git a/Quick-Start.md b/Quick-Start.md index 55049d5..0b0a8a0 100644 --- a/Quick-Start.md +++ b/Quick-Start.md @@ -1,3 +1,5 @@ +[Deutsch](Quick-Start.de) | **English** + # Quick Start ## 1. Prepare environment diff --git a/Reference-BUILD.de.md b/Reference-BUILD.de.md index 8629840..d552da4 100644 --- a/Reference-BUILD.de.md +++ b/Reference-BUILD.de.md @@ -1,3 +1,5 @@ +**Deutsch** | [English](Reference-BUILD) + # Romexis Docker Build-Prozess [Zurück zum README](README.de.md) | [English](BUILD.md) diff --git a/Reference-BUILD.md b/Reference-BUILD.md index 1fe6ddd..048838b 100644 --- a/Reference-BUILD.md +++ b/Reference-BUILD.md @@ -1,3 +1,5 @@ +[Deutsch](Reference-BUILD.de) | **English** + # Romexis Docker Build Process [Back to README](README.md) | [Deutsch](BUILD.de.md) diff --git a/Reference-DEVELOPERS.de.md b/Reference-DEVELOPERS.de.md index fb72659..ddd7bf6 100644 --- a/Reference-DEVELOPERS.de.md +++ b/Reference-DEVELOPERS.de.md @@ -1,3 +1,5 @@ +**Deutsch** | [English](Reference-DEVELOPERS) + # Entwicklerhinweise Dieses Dokument beschreibt den internen Aufbau des @@ -268,12 +270,16 @@ Beispiele: Die passende Chilkat-Bibliothek wird automatisch anhand von `TARGETARCH` ausgewählt: - TARGETARCH Chilkat-Architektur - ------------ --------------------- - `amd64` `x86_64` - `arm64` `aarch64` +| TARGETARCH | Chilkat-Architektur | +|-----------|----------------------| +| `amd64` | `x86_64` | +| `arm64` | `aarch64` | -Das finale Basisimage wird über `ROMEXIS_BASE_IMAGE` festgelegt. +Das finale Basisimage wird ausgewählt über: + +```text +ROMEXIS_BASE_IMAGE +``` Beispiel: diff --git a/Reference-DEVELOPERS.md b/Reference-DEVELOPERS.md index 234ce9f..cad4c8c 100644 --- a/Reference-DEVELOPERS.md +++ b/Reference-DEVELOPERS.md @@ -1,3 +1,5 @@ +[Deutsch](Reference-DEVELOPERS.de) | **English** + # Developer Notes This document describes the internal structure of the Romexis Docker project and explains how the build components fit together. diff --git a/Reference-MIGRATION_README.de.md b/Reference-MIGRATION_README.de.md new file mode 100644 index 0000000..f4bb73a --- /dev/null +++ b/Reference-MIGRATION_README.de.md @@ -0,0 +1,279 @@ +[**Deutsch**](Reference-MIGRATION_README.de) | [English](Reference-MIGRATION_README) + +# Romexis-Migrationsdienst + +Dieser Container ist ein Migrationshilfsdienst, mit dem eine vorhandene Windows-basierte Planmeca-Romexis-Installation in den Docker-basierten Romexis-Server-Stack migriert wird. + +- **Flask-Web-UI / REST-API** für Migrationsverwaltung, Status, Validierung und Wiederherstellungsorchestrierung +- **SFTP-Upload-Endpunkt** für große Dateien und Verzeichnisbäume +- **Manifest-basierte Migrationsjobs** zur Beschreibung der übertragenen Daten +- **Wiederherstellungs-Hooks** für die Wiederherstellung der SQL-Server-Datenbank und die abschließende Datenplatzierung + +Der Dienst startet, stellt eine Web-UI bereit, erstellt Migrationsjobs, stellt Upload-Zugangsdaten pro Job bereit, nimmt Uploads über SFTP an und zeigt den Migrationszustand an. + +--- + +## Vorgesehener Migrationsablauf + +```text +Existing Windows Romexis Installation + | + | 1. Create SQL Server .bak backup + | 2. Collect Romexis data directories + | 3. Generate manifest.json + | 4. Upload via SFTP/rclone/WinSCP + v +Romexis Migration Service + | + | 5. Validate uploaded files + | 6. Stop Romexis container + | 7. Restore SQL backup + | 8. Move data directories into target volumes + | 9. Start Romexis container + v +Docker-based Romexis Server +``` + +--- + +## Warum SFTP statt Flask-Uploads? + +Romexis-Bildarchive können sehr groß werden. Ein reiner Flask-Upload-Ansatz würde eine besondere Behandlung erfordern für: + +- Upload-Zeitüberschreitungen +- unterbrochene Übertragungen +- Unterstützung zur Wiederaufnahme +- Fortschrittsverfolgung +- große Dateimengen +- große einzelne `.bak`-Dateien + +SFTP eignet sich besser für diese Aufgabe, da es von vielen ausgereiften Werkzeugen unterstützt wird: + +- `rclone` (bevorzugtes Werkzeug) +- WinSCP +- FileZilla +- OpenSSH `sftp` +- PowerShell/OpenSSH +- Automatisierungsskripte + +Die Webanwendung bleibt für Orchestrierung, Status und Wiederherstellungsaktionen zuständig. + +--- + +## Projektstruktur + +```text +. +├── migration-service/ +│ ├── Dockerfile +│ ├── requirements.txt +│ ├── entrypoint.sh +│ ├── app/ +│ │ ├── app.py +│ │ ├── core/ +│ │ │ ├── config.py +│ │ │ ├── migrations.py +│ │ │ └── sftp_users.py +│ │ ├── templates/ +│ │ │ ├── base.html +│ │ │ ├── index.html +│ │ │ ├── migration.html +│ │ │ └── new_migration.html +│ │ └── static/ +│ │ └── style.css +│ ├── scripts/ +│ │ ├── restore-migration.sh +│ │ └── validate-migration.sh +│ └── ssh/ +│ └── sshd_config +│ +├── migration-client/ +│ └── romexis_migration_client.py +│ +└── docs/ + ├── examples/ + │ └── manifest.example.json + ├── MIGRATION_WORKFLOW.md + └── SECURITY.md +``` + +--- + +## Schnellstart + +Migrationsdienst bauen und starten: + +```bash +docker compose -f docker-compose.migration.yml up -d --build +``` + +Web-UI öffnen: + +```text +http://localhost:8080 +``` + +SFTP-Endpunkt: + +```text +localhost:2222 +``` + +Erstelle eine Migration in der Web-UI. Der Dienst erzeugt: + +- Migrations-ID +- SFTP-Benutzername +- SFTP-Passwort +- Upload-Pfad + +Lade anschließend Dateien in das Migrationsverzeichnis hoch. + +--- + +## Erwartetes Upload-Layout + +Jede Migration erhält ihr eigenes Eingangsverzeichnis: + +```text +/incoming// +├── manifest.json +├── database/ +│ └── Romexis_db.bak +├── romexis_images/ +│ └── ... +├── romexis_ergodata/ +│ └── ... +└── romexis_cache/ + └── ... # optional +``` + +Das Cache-Verzeichnis ist optional und kann normalerweise ausgelassen werden. + +--- + +## Manifest + +Die Datei `manifest.json` beschreibt die übertragenen Daten. + +Beispiel: + +```json +{ + "source": { + "hostname": "old-romexis-server", + "romexis_version": "6.5.3", + "database_name": "Romexis_db" + }, + "backup": { + "file": "database/Romexis_db.bak" + }, + "data": { + "images": "romexis_images", + "ergodata": "romexis_ergodata", + "cache": null + } +} +``` + +Ein vollständiges Beispiel ist enthalten in: + +```text +examples/manifest.example.json +``` + +--- + +## Aktueller Stand + +Implementiert: + +- Flask-Web-UI +- REST-API +- Erstellung von Migrationsjobs +- als JSON-Dateien gespeicherter Migrationszustand +- erzeugte Zugangsdaten pro Migration +- SFTP-Server im selben Container +- Vorbereitung des Upload-Verzeichnisses +- Validierungs-Hook +- SQL-Server-Wiederherstellung +- Python-Client + +Noch nicht vollständig implementiert: + +- koordinierter Romexis-Neustart über eine gemeinsame Zustandsdatei +- Prüfsummenvalidierung +- Fortschrittsaggregation +- Authentifizierung für die Web-UI +- produktionsreife Benutzerisolation + +Diese Bestandteile sind bewusst getrennt, damit sie schrittweise implementiert und getestet werden können. + +--- + + +--- + +## Aktuelle Implementierungsänderung + +Der Migrationsdienst unterstützt jetzt sowohl Client-gesteuerte als auch manuelle browserbasierte Migrationen. + +Implementierter Workflow: + +1. Migrationsjob erstellen. +2. Datenbanksicherung über die Web-UI oder den Client-Workflow hochladen. +3. `manifest.json` auf dem Server erzeugen. +4. Datenbanksicherung wiederherstellen. +5. `romexis_images`, `romexis_ergodata` und optional `romexis_cache` über SFTP hochladen. +6. Abschluss des Uploads bestätigen. +7. Upload validieren. +8. Wiederherstellungsworkflow ausführen. +9. Romexis-Neustart über die gemeinsame Zustandsdatei anfordern. +10. Migration abschließen und temporären SFTP-Zugriff entfernen. + +Zusätzlich unterstützte Operation: + +- Migration abbrechen und temporären SFTP-Benutzer entfernen + +Endzustände wie `completed`, `cancelled` und `failed` erstellen nach einem Neustart des Dienstes keine SFTP-Benutzer erneut. + +--- + +## Serverseitige Manifest-Erstellung + +Der Server besitzt das Manifest-Format. Clients und Web-UI sollten ausschließlich Parameter übermitteln. + +Das Wiederherstellungsskript erwartet: + +```json +{ + "backup": { + "file": "database/Romexis_db.bak" + } +} +``` + +Bei manuellen Uploads wird das Manifest automatisch erzeugt, nachdem die Datenbanksicherung über die Web-UI hochgeladen wurde. + +--- + +## Koordination des Romexis-Neustarts + +Nach einer erfolgreichen Datenbankwiederherstellung kann der Migrationsdienst einen Romexis-Neustart anfordern über: + +```text +/data/romexis_images/.romexis_restart_state +``` + +Der Romexis-Entrypoint überwacht diese Zustandsdatei, startet den Romexis-Prozess neu und schreibt das Ergebnis zurück. Der Migrationsdienst liest das Ergebnis, protokolliert es und entfernt die Zustandsdatei. + + +## Entwicklungshinweise + +Die aktuelle Implementierung ist als praktische Grundlage ausgelegt. Sie hält den Übertragungsweg für große Dateien unabhängig von der Webanwendung und ermöglicht, Migrationsworkflows schrittweise zu testen. + +Nächste Schritte: + +- Prüfsummenerzeugung und -validierung hinzufügen. +- Authentifizierung zur Web-UI hinzufügen. +- Migrationslogs pro Job hinzufügen. +- Dry-Run-Wiederherstellungsmodus hinzufügen. diff --git a/Reference-MIGRATION_README.md b/Reference-MIGRATION_README.md index c1c55dd..735f6ce 100644 --- a/Reference-MIGRATION_README.md +++ b/Reference-MIGRATION_README.md @@ -1,3 +1,5 @@ +[Deutsch](Reference-MIGRATION_README.de) | **English** + # Romexis Migration Service This Container is a migration helper service that will be used to migrate an existing Windows-based Planmeca Romexis installation into the Docker-based Romexis Server stack. diff --git a/Reference-MIGRATION_WORKFLOW.de.md b/Reference-MIGRATION_WORKFLOW.de.md new file mode 100644 index 0000000..45127b8 --- /dev/null +++ b/Reference-MIGRATION_WORKFLOW.de.md @@ -0,0 +1,168 @@ +[**Deutsch**](Reference-MIGRATION_WORKFLOW.de) | [English](Reference-MIGRATION_WORKFLOW) + +# Migrationsworkflow + +Dieses Dokument beschreibt den vorgesehenen Workflow zur Migration einer vorhandenen Romexis-Installation in den Docker-basierten Romexis-Server-Stack. + +┌──────────────────────────────┐ +│ Existing Romexis Server │ +└──────────────┬───────────────┘ + │ + │ Romexis Migration Client + │ + ▼ + SFTP / REST API + │ + ▼ +┌──────────────────────────────┐ +│ Romexis Migration Service │ +│ │ +│ • Migration Jobs │ +│ • Upload Validation │ +│ • Restore Workflow │ +└──────────────┬───────────────┘ + │ + ▼ +┌──────────────────────────────┐ +│ Romexis Docker Container │ +│ SQL Server │ +│ Images │ +│ Ergodata │ +└──────────────────────────────┘ + +--- + + +--- + +## Aktualisierter detaillierter Workflow + +```text +created + -> database_uploaded + -> database_restored + -> upload_complete + -> validated + -> restored + -> completed +``` + +Endzustände: + +```text +completed +cancelled +failed +``` + +### Manueller Browser-Workflow + +1. Migrationsjob in der Web-UI erstellen. +2. Datenbanksicherung im Browser hochladen. +3. Der Dienst erstellt automatisch `manifest.json`. +4. Datenbankwiederherstellung auslösen. +5. Dateiverzeichnisse über SFTP hochladen. +6. Abschluss des Uploads bestätigen. +7. Upload validieren. +8. Wiederherstellung ausführen. +9. Migration abschließen und SFTP-Zugriff entfernen. + +### Windows-Client-Workflow + +1. Romexis-Installation erkennen. +2. SQL-Server-Konfiguration erkennen. +3. Datenverzeichnisse erkennen. +4. Migrationsjob erstellen oder verwenden. +5. Datenbanksicherung erstellen. +6. Daten über rclone/SFTP hochladen. +7. API-Endpunkte aufrufen, um den Migrationsworkflow voranzubringen. +8. Logs und Wiederherstellungsstatus anzeigen. + +### Neustart nach der Wiederherstellung + +Der Migrationsdienst und der Romexis-Container kommunizieren über: + +```text +/data/romexis_images/.romexis_restart_state +``` + +Der Migrationsdienst schreibt eine ausstehende Neustartanforderung. Der Romexis-Entrypoint stoppt und startet den Romexis-Prozess neu, schreibt den endgültigen Status und der Migrationsdienst entfernt die Zustandsdatei. + + +## Phase 1: Vorbereitung auf dem Quellsystem + +Das Quellsystem ist üblicherweise ein vorhandener Windows-basierter Romexis-Server. + +Erforderliche Daten: + +- SQL-Server-Datenbanksicherung (`.bak`) +- Romexis-Bildverzeichnis +- Romexis-Ergo-Datenverzeichnis +- optionales Cache-Verzeichnis + +Das Cache-Verzeichnis kann normalerweise ausgelassen werden, da es neu erzeugt werden kann. + +--- + +## Phase 2: Migrationsjob erstellen + +Ein Migrationsjob wird in der Web-UI erstellt. + +Der Dienst erzeugt: + +- Migrations-ID +- SFTP-Benutzername +- SFTP-Passwort +- Upload-Pfad + +--- + +## Phase 3: Daten hochladen + +Empfohlene Werkzeuge: + +- rclone über SFTP +- WinSCP +- FileZilla +- OpenSSH SFTP + +Beispiel mit rclone: + +```bash +rclone copy ./migration-data sftp:upload \ + --transfers 8 \ + --checkers 16 \ + --progress +``` + +--- + +## Phase 4: Upload validieren + +Der Migrationsdienst validiert: + +- Manifest ist vorhanden +- SQL-Sicherung ist vorhanden +- Bildverzeichnis ist vorhanden +- Ergo-Verzeichnis ist vorhanden + +Spätere Versionen sollten ergänzen: + +- Prüfsummenvalidierung +- Vergleich der Dateianzahl +- Validierung der erwarteten Größe + +--- + +## Phase 5: Wiederherstellung + +Der Wiederherstellungsprozess führt aus oder koordiniert: + +1. Romexis-Server-Container stoppen +2. SQL-Server-Datenbanksicherung wiederherstellen +3. Datenverzeichnisse in die Ziel-Volumes kopieren +4. Eigentümer und Berechtigungen korrigieren +5. Romexis-Server-Container starten +6. abschließende Validierung ausführen + +Der aktuelle Workflow verwendet explizite Zustandsübergänge und hält die Neustartkoordination über die gemeinsame Zustandsdatei getrennt. diff --git a/Reference-MIGRATION_WORKFLOW.md b/Reference-MIGRATION_WORKFLOW.md index 35b090b..4dc7041 100644 --- a/Reference-MIGRATION_WORKFLOW.md +++ b/Reference-MIGRATION_WORKFLOW.md @@ -1,3 +1,5 @@ +[Deutsch](Reference-MIGRATION_WORKFLOW.de) | **English** + # Migration Workflow This document describes the target workflow for migrating an existing Romexis installation into the Docker-based Romexis Server stack. diff --git a/Reference-README-compose.de.md b/Reference-README-compose.de.md new file mode 100644 index 0000000..7cffacf --- /dev/null +++ b/Reference-README-compose.de.md @@ -0,0 +1,46 @@ +[**Deutsch**](Reference-README-compose.de) | [English](Reference-README-compose) + +# Überarbeitung von Romexis Docker Compose + +Dieses Dokument wurde in die regulären README-Dateien übernommen. + +Verwende: + +- [README.md](README.md) für die englische Runtime- und Compose-Nutzung +- [README.de.md](README.de.md) für die deutsche Runtime- und Compose-Nutzung +- [BUILD.md](BUILD.md) für englische Build-Details +- [BUILD.de.md](BUILD.de.md) für deutsche Build-Details + +Der wichtige Compose-Workflow ist: + +```env +DATABASE_BACKEND=mssql +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +oder: + +```env +DATABASE_BACKEND=firebird +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Starte den Stack anschließend mit: + +```bash +docker compose up -d +``` + +Lokale Builds werden ausgeführt über: + +```bash +./scripts/build-local.sh all +``` + +oder: + +```powershell +.\scripts\build-local.ps1 -Targets all +``` diff --git a/Reference-README-compose.md b/Reference-README-compose.md index bd77126..4b3db18 100644 --- a/Reference-README-compose.md +++ b/Reference-README-compose.md @@ -1,3 +1,5 @@ +[Deutsch](Reference-README-compose.de) | **English** + # Romexis Docker Compose Refactor This document has been merged into the normal README files. diff --git a/Reference-README.de.md b/Reference-README.de.md index 3ab7f10..d914965 100644 --- a/Reference-README.de.md +++ b/Reference-README.de.md @@ -1,3 +1,5 @@ +**Deutsch** | [English](Reference-README) + # Romexis Docker [English](README.md) | [Build-Prozess](BUILD.de.md) | [Entwicklerdokumentation](DEVELOPERS.md) diff --git a/Reference-README.md b/Reference-README.md index 3929a78..9cfd768 100644 --- a/Reference-README.md +++ b/Reference-README.md @@ -1,3 +1,5 @@ +[Deutsch](Reference-README.de) | **English** + # Romexis Docker [Deutsch](README.de.md) | [Build process](BUILD.md) | [Developer notes](DEVELOPERS.md) diff --git a/Release-Process.de.md b/Release-Process.de.md new file mode 100644 index 0000000..79b84c3 --- /dev/null +++ b/Release-Process.de.md @@ -0,0 +1,69 @@ +**Deutsch** | [English](Release-Process) + +# Release-Prozess + +## Release-Eingaben + +Ein Release umfasst üblicherweise: + +- gebaute und veröffentlichte Container-Images +- aktualisierte Dokumentation +- Release Notes +- optionale Änderungen am Migrationsdienst +- optionale Änderungen am Client + +--- + +## Empfohlene Release-Schritte + +1. Sicherstellen, dass das Repository fehlerfrei gebaut wird. +2. Verfügbarkeit der Payload-Images prüfen. +3. Base-Images für die Zielarchitekturen prüfen. +4. Server-Images für die Zielarchitekturen prüfen. +5. Multiarch-Manifeste prüfen. +6. Docker-Compose-Start testen. +7. Datenbankinitialisierung testen. +8. Start des Migrationsdienstes testen. +9. Release Notes erstellen. +10. Gitea-Release veröffentlichen. +11. Gitea-Pakete prüfen. + +--- + +## Image-Prüfung + +```bash +docker pull gitea.buchhorster.de/planmeca/romexis-server:-amd64 +docker pull gitea.buchhorster.de/planmeca/romexis-server: +``` + +Untersuchen: + +```bash +docker manifest inspect gitea.buchhorster.de/planmeca/romexis-server: +``` + +--- + +## Release Notes sollten Folgendes erwähnen + +- neue Funktionen +- Änderungen am Migrationsdienst +- Änderungen am Datenbank-Backend +- Breaking Changes +- erforderliche Änderungen an Umgebungsvariablen +- bekannte Einschränkungen + +--- + +## Gitea-Bereiche + +Gitea wird wie folgt verwendet: + +| Bereich | Zweck | +|---|---| +| Code | Quellcode und Dockerfiles | +| Releases | Menschenlesbare, versionierte Release Notes | +| Packages | Veröffentlichte Container-Images | +| Wiki | Betriebs- und Entwicklerdokumentation | +| Issues | Fehler, Funktionswünsche und Planung | diff --git a/Release-Process.md b/Release-Process.md index 43e573f..8ebc659 100644 --- a/Release-Process.md +++ b/Release-Process.md @@ -1,3 +1,5 @@ +[Deutsch](Release-Process.de) | **English** + # Release Process ## Release Inputs diff --git a/Romexis-Admin.de.md b/Romexis-Admin.de.md new file mode 100644 index 0000000..2476a7e --- /dev/null +++ b/Romexis-Admin.de.md @@ -0,0 +1,174 @@ +**Deutsch** | [English](Romexis-Admin) + +# Romexis Admin + +Der Dienst `romexis-admin` bietet browserbasierten Zugriff auf Romexis Admin / RomexisConfig. + +Er ist vom Romexis-Server-Container getrennt, damit der Serverprozess auf die Backend-Laufzeit konzentriert bleibt, während die administrative Konfiguration in einem eigenen grafischen Container erfolgt. + +--- + +## Laufzeitkomponenten + +Der Admin-Container startet die grafische Laufzeitumgebung mit: + +```text +Xvfb +Openbox +xcompmgr +x11vnc +noVNC / websockify +``` + +Openbox und xcompmgr sind erforderlich, weil Romexis Admin Swing-/AWT-Dialoge mit Transparenz- und Transluzenzfunktionen verwendet. + +Das Openbox-Kontextmenü des Root-Desktops ist im Startskript deaktiviert, weil es in der noVNC-Laufzeit nicht nützlich ist. + +--- + +## Zugriff + +Admin-Oberfläche über noVNC öffnen: + +```text +http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true +``` + +Wenn `ADMIN_NOVNC_PORT` geändert wird, muss der Port entsprechend angepasst werden. + +--- + +## VNC-Lifecycle-Modus + +Wenn aktiviert, wird RomexisConfig erst gestartet, wenn sich ein VNC-/noVNC-Client verbindet. + +```env +ADMIN_VNC_LIFECYCLE=true +``` + +Verhalten: + +```text +first VNC client connects -> start RomexisConfig +last VNC client disconnects -> stop RomexisConfig after a short grace period +``` + +Wenn der Benutzer RomexisConfig manuell schließt, während die VNC-Sitzung noch verbunden ist, wird es erst bei der nächsten VNC-Verbindungssitzung neu gestartet. + +Wenn deaktiviert: + +```env +ADMIN_VNC_LIFECYCLE=false +``` + +RomexisConfig startet sofort mit dem Container. + +--- + +## Lokalisierter Startbildschirm + +Im VNC-Lifecycle-Modus wird beim Start der VNC-Sitzung und während des Starts von RomexisConfig ein kleiner Startbildschirm angezeigt. + +Die Sprache wird gesteuert über: + +```env +ADMIN_LANGUAGE=de +``` + +Unterstützte Werte: + +```text +de +en +``` + +Dieselbe Variable wird RomexisConfig als Startparameter `language=` übergeben. + +--- + +## Debug-xterm + +Innerhalb der VNC-Sitzung kann ein Debug-xterm gestartet werden: + +```env +DEBUG_XTERM=true +``` + +Standard: + +```env +DEBUG_XTERM=false +``` + +Dies ist nützlich, um die Laufzeit-Displayumgebung zu untersuchen, ohne den Container-Entrypoint zu ändern. + +--- + +## Typische Compose-Einstellungen + +```env +ADMIN_NOVNC_PORT=6080 +ADMIN_VNC_PORT=5900 +ADMIN_VNC_PASSWORD=promax +ADMIN_RESOLUTION=1280x900x24 +ADMIN_JAVA_OPTS=-Xms256m -Xmx1024m +ADMIN_LANGUAGE=de +DEBUG_XTERM=false +ADMIN_VNC_LIFECYCLE=true +ENABLE_PROPERTY_AGENT=false +``` + +--- + +## PropertyAgent im Admin + +Der Romexis PropertyAgent ist für den Admin-Container standardmäßig deaktiviert: + +```env +ENABLE_PROPERTY_AGENT=false +``` + +Grund: `RxProperties` ist während der Java-Agent-Phase `premain` beim Start von RomexisConfig nicht immer sichtbar. Der Server-Container verwendet den PropertyAgent weiterhin für die serverseitige Injektion von Laufzeiteigenschaften. + +--- + +## Protokolle und Debugging + +Protokolle anzeigen: + +```bash +docker compose logs -f romexis-admin +``` + +Eine Shell im Admin-Image öffnen: + +```bash +docker compose run --rm --entrypoint /bin/bash romexis-admin +``` + +Wenn ein gestoppter Container untersucht werden muss: + +```bash +docker cp romexis-admin:/opt/romexis/admin ./admin-debug +``` + +--- + +## Wichtige Laufzeitabhängigkeiten + +Das Admin-Image benötigt Pakete wie: + +```text +xvfb +openbox +xcompmgr +x11vnc +x11-utils +novnc +websockify +openjfx +libopenjfx-java +libopenjfx-jni +``` + +`x11-utils` stellt `xmessage` bereit, das für den Startbildschirm verwendet wird. diff --git a/Romexis-Admin.md b/Romexis-Admin.md index fefb10a..6c3a793 100644 --- a/Romexis-Admin.md +++ b/Romexis-Admin.md @@ -1,3 +1,5 @@ +[Deutsch](Romexis-Admin.de) | **English** + # Romexis Admin The `romexis-admin` service provides browser-based access to Romexis Admin / RomexisConfig. diff --git a/Runtime-Layout.de.md b/Runtime-Layout.de.md new file mode 100644 index 0000000..8a4a042 --- /dev/null +++ b/Runtime-Layout.de.md @@ -0,0 +1,138 @@ +**Deutsch** | [English](Runtime-Layout) + +# Laufzeitlayout + +## Persistente Daten + +Empfohlenes persistentes Wurzelverzeichnis: + +```text +/srv/romexis-data +``` + +Typische Verzeichnisse: + +```text +/srv/romexis-data/sconfig +/srv/romexis-data/programdata +/srv/romexis-data/romexis_images +/srv/romexis-data/romexis_ergodata +/srv/romexis-data/romexis_cache +/srv/romexis-data/sql-backup +/srv/romexis-data/firebird +``` + +--- + +## Laufzeitdienste + +```text +romexis + Main Romexis Server process. + +mssql + Microsoft SQL Server backend when DATABASE_BACKEND=mssql. + +firebird + Firebird backend when DATABASE_BACKEND=firebird. + +romexis-admin + Browser-accessible Romexis Admin / RomexisConfig runtime. + +romexis-app + Tomcat-based mRomexis Web App. + +proxy + OpenResty/Nginx proxy for mRomexis Web App. + +romexis-migration + Optional migration service for MSSQL workflows. +``` + +--- + +## Pfade im Romexis-Container + +```text +/opt/romexis +/opt/romexis/server +/opt/romexis/sconfig +/programdata/planmeca/romexis + +/data/romexis_images +/data/romexis_ergodata +/data/romexis_cache +``` + +--- + +## Pfade im Admin-Container + +```text +/opt/romexis/admin +/opt/romexis/client +/opt/romexis/sconfig +/programdata/Planmeca/Romexis/Admin +/tmp/romexis-admin-vnc-state +``` + +Der Admin-Container bietet Browserzugriff über noVNC und verwendet VNC-Statusdateien, um RomexisConfig abhängig von aktiven Sitzungen zu starten oder zu stoppen. + +--- + +## Pfade der mRomexis Web App + +```text +/usr/local/tomcat/webapps/ROOT.war +``` + +Die WAR-Datei stammt aus dem Romexis-Payload: + +```text +/opt/romexis/broker/mromexis-html.war +``` + +--- + +## Datenbankpfade + +### MSSQL + +```text +/var/opt/mssql +/var/opt/mssql/backup +``` + +### Firebird + +```text +/firebird/data/romexis.fdb +``` + +--- + +## Neustart-Statusdatei + +Wird zur Koordination einer Wiederherstellung durch den Migrationsdienst verwendet: + +```text +/data/romexis_images/.romexis_restart_state +``` + +--- + +## Laufzeitskripte + +```text +/entrypoint.sh +/opt/init-romexis-db.sh +/opt/init-romexis-mssql-db.sh +/opt/init-romexis-firebird-db.sh +/opt/fix-keystore-alias.sh +``` + +Admin-Startskript: + +```text +/usr/local/bin/start.sh +``` diff --git a/Runtime-Layout.md b/Runtime-Layout.md index d55cb10..7e2a4cc 100644 --- a/Runtime-Layout.md +++ b/Runtime-Layout.md @@ -1,3 +1,5 @@ +[Deutsch](Runtime-Layout.de) | **English** + # Runtime Layout ## Persistent Data diff --git a/Security.de.md b/Security.de.md new file mode 100644 index 0000000..a632c4b --- /dev/null +++ b/Security.de.md @@ -0,0 +1,94 @@ +**Deutsch** | [English](Security) + +# Sicherheit + +## Repository-Sicherheit + +Das Repository darf keine proprietären Romexis-Anwendungsbinärdateien enthalten. + +Installerpakete werden während der Payload-Builds von offiziellen URLs heruntergeladen. + +--- + +## Geheimnisse + +Sensible Werte sollten aus folgenden Quellen stammen: + +```text +.env +Drone secrets +Docker Compose environment +external secret stores +``` + +Wichtige Werte: + +```text +MSSQL_SA_PASSWORD +ROMEXIS_DB_PASSWORD +FIREBIRD_PASSWORD +MIGRATION_API_TOKEN +SFTP passwords +Registry credentials +``` + +--- + +## Sicherheit des Migrationsdienstes + +Migrationsjobs erzeugen temporäre SFTP-Zugangsdaten. + +Regeln: + +- Zugangsdaten sollten für jeden Job eindeutig sein. +- Zugangsdaten sollten nach Abschluss entfernt werden. +- Abgebrochene Jobs sollten ihre Zugangsdaten entfernen. +- Abgeschlossene Jobs sollten beim Start keine SFTP-Benutzer neu erstellen. +- Fehlgeschlagene Jobs sollten keine SFTP-Benutzer neu erstellen, sofern sie nicht ausdrücklich reaktiviert wurden. + +--- + +## Netzwerkfreigaben + +Nur erforderliche Ports freigeben. + +Typische Ports: + +```text +Romexis RMI ports +MSSQL 1433, if external access is required +Firebird 3050, if external access is required +Migration Web UI 8080 +Migration SFTP 2222 +``` + +In der Produktion müssen die Dienste hinter geeigneten Firewallregeln platziert werden. + +--- + +## Dateiberechtigungen + +Persistente Verzeichnisse müssen für die jeweiligen Containerbenutzer beschreibbar sein. + +Besondere Sorgfalt ist erforderlich für: + +```text +/var/opt/mssql +/firebird/data +/data/romexis_images +/data/romexis_ergodata +/data/romexis_cache +``` + +--- + +## Hinweise für den Produktivbetrieb + +Vor dem Produktivbetrieb: + +- alle Standardpasswörter ändern +- freigegebene Ports einschränken +- HTTPS bzw. einen Reverse Proxy für die Weboberfläche des Migrationsdienstes verwenden +- starke API-Tokens verwenden +- Test-Migrationsjobs entfernen +- Backup- und Wiederherstellungsverfahren prüfen diff --git a/Security.md b/Security.md index 6ed660a..c490d7b 100644 --- a/Security.md +++ b/Security.md @@ -1,3 +1,5 @@ +[Deutsch](Security.de) | **English** + # Security ## Repository Security diff --git a/Server-Image.de.md b/Server-Image.de.md new file mode 100644 index 0000000..3323a60 --- /dev/null +++ b/Server-Image.de.md @@ -0,0 +1,102 @@ +**Deutsch** | [English](Server-Image) + +# Server-Image + +Verzeichnis: + +```text +romexis/ +``` + +Das endgültige Romexis-Server-Image kombiniert das vorbereitete Payload, das Runtime-Base-Image, das Firebird-Payload und die Laufzeitskripte. + +--- + +## Build-Eingaben + +```text +ROMEXIS_BASE_IMAGE +ROMEXIS_PAYLOAD_IMAGE +ROMEXIS_FIREBIRD_PAYLOAD_IMAGE +ROMEXIS_VERSION +TARGETARCH +IMAGE_SUFFIX +CHILKAT_VERSION +``` + +Beispielvorgaben: + +```dockerfile +ARG TARGETARCH=amd64 +ARG ROMEXIS_VERSION=6.5.3.444.203 +ARG IMAGE_SUFFIX= + +ARG ROMEXIS_BASE_IMAGE=gitea.buchhorster.de/planmeca/romexis-base-jre:11-${TARGETARCH}${IMAGE_SUFFIX} +ARG ROMEXIS_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-payload:${ROMEXIS_VERSION}${IMAGE_SUFFIX} +ARG ROMEXIS_FIREBIRD_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest${IMAGE_SUFFIX} +``` + +--- + +## Build-Stufen + +```text +Stage 1: romexis-payload + Imports /opt/romexis and /opt/romexis-mssql-db. + +Stage 2: romexis-firebird-payload + Imports /opt/romexis-firebird-db. + +Stage 3: agent-build + Compiles RomexisPropertyAgent.java. + +Stage 4: final image + Assembles runtime image. +``` + +--- + +## Laufzeitskripte + +Das endgültige Image enthält: + +```text +/entrypoint.sh +/opt/init-romexis-db.sh +/opt/init-romexis-mssql-db.sh +/opt/init-romexis-firebird-db.sh +/opt/fix-keystore-alias.sh +``` + +--- + +## Java Property Agent + +Das Image enthält: + +```text +/opt/romexis/server/RomexisPropertyAgent.jar +``` + +Dies ermöglicht die Injektion von Laufzeiteigenschaften, bevor Romexis startet. + +Beispielmuster für Umgebungsvariablen: + +```text +PROPERTY_AGENT_SET_KEY_= +``` + +--- + +## Laufzeitvalidierung + +Das Dockerfile sollte während des Builds wichtige Payload-Ausgaben prüfen, insbesondere: + +```text +/opt/romexis/server/RomexisServer.jar +/opt/romexis/version +/opt/romexis-mssql-db +/opt/romexis-firebird-db +``` + +Ein frühzeitiger Fehler ist einem unvollständigen Laufzeitimage vorzuziehen. diff --git a/Server-Image.md b/Server-Image.md index af1d056..42a2f1f 100644 --- a/Server-Image.md +++ b/Server-Image.md @@ -1,3 +1,5 @@ +[Deutsch](Server-Image.de) | **English** + # Server Image Directory: diff --git a/Source-README-References.de.md b/Source-README-References.de.md new file mode 100644 index 0000000..9e61acc --- /dev/null +++ b/Source-README-References.de.md @@ -0,0 +1,15 @@ +**Deutsch** | [English](Source-README-References) + +# Referenzen auf Quelldokumente + +Diese Quelldokumente wurden als Grundlage für das Wiki-Paket verwendet. + +- [BUILD.de](Reference-BUILD.de) +- [BUILD](Reference-BUILD) +- [README.de](Reference-README.de) +- [README](Reference-README) +- [README Compose Refactor](Reference-README-compose) +- [DEVELOPERS.de](Reference-DEVELOPERS.de) +- [DEVELOPERS](Reference-DEVELOPERS) +- [MIGRATION_README](Reference-MIGRATION_README) +- [MIGRATION_WORKFLOW](Reference-MIGRATION_WORKFLOW) diff --git a/Source-README-References.md b/Source-README-References.md index 1b9d05f..69fc3d4 100644 --- a/Source-README-References.md +++ b/Source-README-References.md @@ -1,3 +1,5 @@ +[Deutsch](Source-README-References.de) | **English** + # Source README References These source documents were used as the basis for the wiki package. diff --git a/Troubleshooting.de.md b/Troubleshooting.de.md new file mode 100644 index 0000000..d8948a4 --- /dev/null +++ b/Troubleshooting.de.md @@ -0,0 +1,228 @@ +**Deutsch** | [English](Troubleshooting) + +# Fehlersuche + +## Wirksame Compose-Konfiguration untersuchen + +Da das aktive Backend über `.env` ausgewählt wird, mit Folgendem beginnen: + +```bash +docker compose config +``` + +Prüfen, ob das erwartete Backend-Override geladen wurde. + +--- + +## Falsches Datenbank-Backend startet + +`.env` prüfen: + +```env +DATABASE_BACKEND=mssql +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +oder: + +```env +DATABASE_BACKEND=firebird +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Anschließend die Umgebung des laufenden Containers untersuchen: + +```bash +docker compose exec romexis env | grep -E 'SERVER_DB|ROMEXIS_DB|MSSQL|FIREBIRD' +``` + +Erwartete Backend-Kennungen: + +```text +SERVER_DB=5 # MSSQL +SERVER_DB=4 # Firebird +``` + +--- + +## Firebird-Modus startet weiterhin die MSSQL-Initialisierung + +Wenn `SERVER_DB` fehlt, kann der Entrypoint standardmäßig MSSQL verwenden. + +Prüfen: + +```bash +docker compose exec romexis env | grep SERVER_DB +``` + +Das Firebird-Compose-Override muss Folgendes setzen: + +```env +SERVER_DB=4 +``` + +--- + +## `MSSQL_SA_PASSWORD` wird im Firebird-Modus benötigt + +Dies bedeutet, dass weiterhin das alte MSSQL-Initialisierungsskript ausgeführt wird oder alter Skriptinhalt im Image vorhanden ist. + +Im Romexis-Container prüfen: + +```bash +docker compose exec romexis cat /opt/init-romexis-db.sh +docker compose exec romexis ls -lah /opt/init-romexis-* +``` + +Neu bauen und erstellen: + +```bash +docker buildx prune -a -f +./scripts/build-local.sh server +docker compose up -d --force-recreate +``` + +--- + +## Firebird zeigt die unixODBC-isql-Hilfe + +Wenn Folgendes erscheint: + +```text +unixODBC - isql and iusql +``` + +wird das falsche `isql`-Werkzeug verwendet. + +Verwenden: + +```bash +isql-fb +``` + +oder setzen: + +```bash +export ISQL=isql-fb +``` + +--- + +## Admin-Container startet RomexisConfig nicht + +Protokolle prüfen: + +```bash +docker compose logs -f romexis-admin +``` + +Wenn `ADMIN_VNC_LIFECYCLE=true` gesetzt ist, startet RomexisConfig erst, nachdem sich ein VNC-/noVNC-Client verbunden hat. + +Öffnen: + +```text +http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true +``` + +--- + +## Admin-JavaFX- oder Transluzenzfehler + +Romexis Admin benötigt Openbox und xcompmgr. + +Das Admin-Image sollte Folgendes enthalten: + +```text +openbox +xcompmgr +x11-utils +openjfx +libopenjfx-java +libopenjfx-jni +``` + +Fehler wie `TRANSLUCENT translucency is not supported` bedeuten üblicherweise, dass der Compositor fehlt oder nicht läuft. + +--- + +## Admin-Startbildschirm wird nicht angezeigt + +Der Startbildschirm verwendet `xmessage` aus `x11-utils`. + +Prüfen: + +```bash +docker compose run --rm --entrypoint which romexis-admin xmessage +``` + +--- + +## Build der mRomexis Web App schlägt wegen fehlender WAR-Datei fehl + +`mromexis-html.war` existiert nur in Romexis 6.5.3 und neuer. + +Payload prüfen: + +```bash +docker run --rm --entrypoint find gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203 /opt/romexis -name 'mromexis-html.war' +``` + +--- + +## Backend-Aufrufe der mRomexis Web App schlagen fehl + +Proxy-Protokolle prüfen: + +```bash +docker compose logs -f proxy +``` + +Erreichbarkeit des Romexis-Backends aus dem Proxy-Container prüfen: + +```bash +docker compose exec proxy wget -O- http://romexis:8093/ || true +``` + +--- + +## Build verwendet weiterhin alte Dateien + +Lokalen Buildcache bereinigen: + +```bash +docker buildx prune -a -f +``` + +Anschließend mit dem lokalen Skript neu bauen: + +```bash +./scripts/build-local.sh all +``` + +Laufzeit-Stack neu erstellen: + +```bash +docker compose up -d --force-recreate +``` + +--- + +## Container zum Debuggen mit Bash starten + +Romexis-Server: + +```bash +docker compose exec romexis bash +``` + +Shell des Admin-Images: + +```bash +docker compose run --rm --entrypoint /bin/bash romexis-admin +``` + +Shell des mRomexis-Web-App-Images: + +```bash +docker compose run --rm --entrypoint /bin/bash romexis-app +``` diff --git a/Troubleshooting.md b/Troubleshooting.md index 4d29137..a053e5f 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -1,3 +1,5 @@ +[Deutsch](Troubleshooting.de) | **English** + # Troubleshooting ## Inspect effective Compose configuration diff --git a/_Footer.md b/_Footer.md index d9dffe8..82b8b74 100644 --- a/_Footer.md +++ b/_Footer.md @@ -1,11 +1,7 @@ --- -Romexis Docker Project Wiki +Romexis Docker Project Wiki / Romexis-Docker-Projekt-Wiki -Repository areas: - -- **Code**: source files, Dockerfiles and helper scripts -- **Releases**: published project releases and release notes -- **Packages**: container images in the Gitea package registry -- **Wiki**: operational and developer documentation +[English Home](Home) · [Deutsche Startseite](Home.de) · [English source documents](Source-README-References) · [Deutsche Quelldokumente](Source-README-References.de) · [Security](Security) · [Sicherheit](Security.de) +Internal operations and development wiki / Internes Betriebs- und Entwicklungswiki diff --git a/_Sidebar.md b/_Sidebar.md index c3f9dea..fa6d283 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -1,8 +1,13 @@ # Romexis Docker Wiki +[English](#english) · [Deutsch](#deutsch) + +## English + - [Home](Home) -## Getting Started +### Getting Started + - [Project Overview](Project-Overview) - [Architecture](Architecture) - [Quick Start](Quick-Start) @@ -12,7 +17,8 @@ - [Configuration](Configuration) - [Container Images](Container-Images) -## Runtime Services +### Runtime Services + - [Romexis Admin](Romexis-Admin) - [mRomexis Web App](mRomexis-WebApp) - [Runtime Layout](Runtime-Layout) @@ -20,7 +26,8 @@ - [Troubleshooting](Troubleshooting) - [Security](Security) -## Build System +### Build System + - [Build System](Build-System) - [Local Build Scripts](Local-Build-Scripts) - [Payload Images](Payload-Images) @@ -28,22 +35,82 @@ - [Server Image](Server-Image) - [CI/CD Pipeline](CI-CD-Pipeline) -## Database +### Database + - [Database Backends](Database-Backends) - [Microsoft SQL Server](Microsoft-SQL-Server) - [Firebird](Firebird) -## Migration +### Migration + - [Migration Service](Migration-Service) - [Migration Workflow](Migration-Workflow) - [Migration Client](Migration-Client) -## Development +### Development + - [Developer Guide](Developer-Guide) - [Java Property Agent](Java-Property-Agent) - [Project Structure](Project-Structure) - [Release Process](Release-Process) - [FAQ](FAQ) -## Source Documents +### Source Documents + - [Source README References](Source-README-References) + +## Deutsch + +- [Startseite](Home.de) + +### Erste Schritte + +- [Projektübersicht](Project-Overview.de) +- [Architektur](Architecture.de) +- [Schnellstart](Quick-Start.de) +- [Nutzung mit Docker + WSL unter Windows](Docker-Desktop-WSL-Windows.de) +- [Compose-Runtime](Compose-Runtime.de) +- [Konfiguration](Configuration.de) +- [Container-Images](Container-Images.de) + +### Runtime-Dienste + +- [Romexis Admin](Romexis-Admin.de) +- [mRomexis Web App](mRomexis-WebApp.de) +- [Runtime-Layout](Runtime-Layout.de) +- [Sicherung und Wiederherstellung](Backup-and-Restore.de) +- [Fehlerbehebung](Troubleshooting.de) +- [Sicherheit](Security.de) + +### Build-System + +- [Build-System](Build-System.de) +- [Lokale Build-Skripte](Local-Build-Scripts.de) +- [Payload-Images](Payload-Images.de) +- [Base-Image](Base-Image.de) +- [Server-Image](Server-Image.de) +- [CI/CD-Pipeline](CI-CD-Pipeline.de) + +### Datenbank + +- [Datenbank-Backends](Database-Backends.de) +- [Microsoft SQL Server](Microsoft-SQL-Server.de) +- [Firebird](Firebird.de) + +### Migration + +- [Migrationsdienst](Migration-Service.de) +- [Migrationsworkflow](Migration-Workflow.de) +- [Migrationsclient](Migration-Client.de) + +### Entwicklung + +- [Entwicklerhandbuch](Developer-Guide.de) +- [Java Property Agent](Java-Property-Agent.de) +- [Projektstruktur](Project-Structure.de) +- [Release-Prozess](Release-Process.de) +- [FAQ](FAQ.de) + +### Quelldokumente + +- [README-Quellreferenzen](Source-README-References.de) diff --git a/mRomexis-WebApp.de.md b/mRomexis-WebApp.de.md new file mode 100644 index 0000000..73d514b --- /dev/null +++ b/mRomexis-WebApp.de.md @@ -0,0 +1,123 @@ +**Deutsch** | [English](mRomexis-WebApp) + +# mRomexis Web App + +Der Dienst `romexis-app` stellt das Planmeca-mRomexis-Webfrontend als separaten Container bereit. + +Die Webanwendung wird von Tomcat ausgeliefert und bleibt vom Romexis-Server-Container getrennt. + +--- + +## Versionsanforderung + +Die WAR-Datei der mRomexis Web App ist nur in Romexis 6.5.3 und neuer verfügbar. + +Erwarteter Payload-Pfad: + +```text +/opt/romexis/broker/mromexis-html.war +``` + +Während des Image-Builds wird diese WAR-Datei wie folgt nach Tomcat kopiert: + +```text +/usr/local/tomcat/webapps/ROOT.war +``` + +Ältere Romexis-Payload-Versionen enthalten die WAR-Datei nicht und können daher kein gültiges mRomexis-Web-App-Image bauen. + +--- + +## Laufzeitdienste + +```text +romexis-app + Tomcat container serving ROOT.war. + +proxy + OpenResty/Nginx proxy exposing the app and rewriting backend proxy requests. + +romexis + Romexis backend service used by the web app through the internal proxy target. +``` + +--- + +## Zugriff + +Die mRomexis Web App über den konfigurierten Proxy-Port öffnen: + +```text +http://localhost:8081 +``` + +Wenn `MROMEXIS_WEB_PORT` geändert wird, muss der Port entsprechend angepasst werden. + +--- + +## Proxy-Verhalten + +Der Proxy verarbeitet Anforderungen der Webanwendung und schreibt mRomexis-Backend-Proxy-Aufrufe auf den internen Romexis-Dienst um. + +Der Proxy vertraut nicht dem vom Browser gelieferten Host aus `/proxy?url=...`. + +Stattdessen extrahiert er ausschließlich Pfad und Query-String und leitet die Anfrage weiter an: + +```text +http://romexis:8093 +``` + +Dies vermeidet die Pflege interner IP-Adressen und verhindert, dass der Endpunkt zu einem offenen HTTP-Proxy wird. + +--- + +## Image-Tags + +```text +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-amd64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-arm64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app: +gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest +``` + +--- + +## Lokaler Build + +Build über das lokale Hilfsskript: + +```bash +./scripts/build-local.sh mromexis +``` + +Oder manuell: + +```bash +docker buildx build --platform linux/amd64 --provenance=false --sbom=false --build-arg TARGETARCH=amd64 --build-arg ROMEXIS_VERSION=6.5.3.444.203 --build-arg ROMEXIS_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203 -t gitea.buchhorster.de/planmeca/romexis-mromexis-app:6.5.3.444.203-amd64 --load ./romexis-mromexis-app +``` + +--- + +## Fehlersuche + +### WAR-Datei nicht gefunden + +Wenn der Build beim Kopieren von `mromexis-html.war` fehlschlägt, muss geprüft werden, ob die ausgewählte Romexis-Payload-Version 6.5.3 oder neuer ist. + +```bash +docker run --rm --entrypoint find gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203 /opt/romexis -name 'mromexis-html.war' +``` + +### Webanwendung startet, Backend-Aufrufe schlagen jedoch fehl + +Proxy-Protokolle prüfen: + +```bash +docker compose logs -f proxy +``` + +Prüfen, ob der Romexis-Backend-Dienst intern erreichbar ist: + +```bash +docker compose exec proxy wget -O- http://romexis:8093/ || true +``` diff --git a/mRomexis-WebApp.md b/mRomexis-WebApp.md index cb40cde..1c894eb 100644 --- a/mRomexis-WebApp.md +++ b/mRomexis-WebApp.md @@ -1,3 +1,5 @@ +[Deutsch](mRomexis-WebApp.de) | **English** + # mRomexis Web App The `romexis-app` service provides the Planmeca mRomexis Web frontend as a separate container.