Update Wiki for Compose/Admin runtime changes

- Document the new Compose runtime structure and backend selection
- Add Wiki pages for Romexis Admin and mRomexis Web App
- Add documentation for local build scripts
- Update Quick Start, Configuration, Build System and CI/CD pages
- Extend runtime, image and troubleshooting documentation
- Update sidebar navigation for the new Wiki structure

Architecture.md

@@ -1,20 +1,22 @@
-Willkommen im Wiki.# Architecture
+# Architecture
 
 ## High-Level Runtime Architecture
 
-Default Microsoft SQL Server mode:
+The runtime is split into a base Compose stack and a selected database backend override.
+
+### Microsoft SQL Server mode
 
 ```text
-+----------------------+
++----------------------+          +----------------------+
-|   Romexis Clients    |
+|   Romexis Clients    |          | Browser / noVNC User |
-+----------+-----------+
++----------+-----------+          +----------+-----------+
-           |
+           |                                 |
-           | RMI / Romexis protocol ports
+           | RMI / Romexis ports            | HTTP / WebSocket
-           v
+           v                                 v
-+----------------------+
++----------------------+          +----------------------+
-| Romexis Server       |
+| Romexis Server       |          | Romexis Admin        |
-| Docker Container     |
+| Docker Container     |          | noVNC Container      |
-+----------+-----------+
++----------+-----------+          +----------------------+
            |
            | JDBC
            v
@@ -24,19 +26,19 @@ Default Microsoft SQL Server mode:
 +----------------------+
 ```
 
-Firebird mode:
+### Firebird mode
 
 ```text
-+----------------------+
++----------------------+          +----------------------+
-|   Romexis Clients    |
+|   Romexis Clients    |          | Browser / noVNC User |
-+----------+-----------+
++----------+-----------+          +----------+-----------+
-           |
+           |                                 |
-           | RMI / Romexis protocol ports
+           | RMI / Romexis ports            | HTTP / WebSocket
-           v
+           v                                 v
-+----------------------+
++----------------------+          +----------------------+
-| Romexis Server       |
+| Romexis Server       |          | Romexis Admin        |
-| Docker Container     |
+| Docker Container     |          | noVNC Container      |
-+----------+-----------+
++----------+-----------+          +----------------------+
            |
            | JDBC / Jaybird
            v
@@ -46,123 +48,128 @@ Firebird mode:
 +----------------------+
 ```
 
+### mRomexis Web App
+
+```text
++----------------------+
+| Browser              |
++----------+-----------+
+           |
+           | HTTP
+           v
++----------------------+
+| OpenResty / Nginx    |
+| proxy container      |
++----------+-----------+
+           |
+           +------------------------------+
+           |                              |
+           v                              v
++----------------------+        +----------------------+
+| mRomexis Web App     |        | Romexis Server       |
+| Tomcat Container     |        | Backend port 8093    |
++----------------------+        +----------------------+
+```
+
+The mRomexis proxy rewrites backend proxy requests to the internal `romexis` service. It does not trust arbitrary hosts supplied by the browser.
+
 ---
 
 ## Image Architecture
 
 ```text
 romexis-payload:<version>
-  /opt/romexis
+        |
-  /opt/romexis-mssql-db
+        +--> romexis-server:<version>
-  /opt/romexis/version
+        |
-
+        +--> romexis-admin:<version>
-romexis-firebird-payload:latest
+        |
-  /opt/romexis-firebird-db
+        +--> romexis-mromexis-app:<version>
-  Firebird SQL scripts
-  Firebird backup/restore helpers
-  romexis_new.fdb template/reference
 
 romexis-base-jre:11-<arch>
-  Java 11
-  JavaFX/OpenJFX
-  database client tools
-  system dependencies
-
-romexis-server:<version>-<arch>
-  Romexis payload
-  Firebird payload
-  base runtime
-  Java property agent
-  initialization scripts
-  entrypoint
-```
-
----
-
-## Why Payload Images?
-
-The original Dockerfile downloaded and extracted installer files inside the final server build.
-
-That worked, but had drawbacks:
-
-- repeated large downloads
-- slow builds
-- harder debugging
-- installer extraction tightly coupled to server image build
-- poor reuse across architectures
-
-Payload images solve this by making the extracted installer content a reusable build artifact.
-
----
-
-## Runtime Data Layout
-
-The runtime stack uses persistent volumes or host directories for:
-
-```text
-/data/romexis_images
-/data/romexis_ergodata
-/data/romexis_cache
-/opt/romexis/sconfig
-/opt/romexis/programdata
-```
-
-Database data is backend-specific:
-
-```text
-Microsoft SQL Server:
-  /var/opt/mssql
-
-Firebird:
-  /firebird/data/romexis.fdb
-```
-
----
-
-## Startup Flow
-
-```text
-entrypoint.sh
         |
-  |-- prepare persistent directories
+        +--> romexis-server:<version>-<arch>
-  |-- generate database URL if needed
+
-  |-- write Romexis configuration
+romexis-firebird-payload:latest
-  |-- run /opt/init-romexis-db.sh
-  |     |
-  |     |-- route to MSSQL init if SERVER_DB=5
-  |     |-- route to Firebird init if SERVER_DB=4
         |
-  |-- fix keystore alias
+        +--> romexis-server:<version>-<arch>
-  |-- start Romexis Server
 ```
 
 ---
 
-## Database Initialization Router
+## Compose Architecture
-
-The runtime uses a small router script:
 
 ```text
-/opt/init-romexis-db.sh
+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.
 ```
 
-It detects the backend using:
+The selected backend is loaded through:
+
+```env
+DATABASE_BACKEND=mssql
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+---
+
+## Persistent Data Flow
 
 ```text
-ROMEXIS_DB_URL
+/srv/romexis-data/
-SERVER_DB
+  sconfig/
+  programdata/
+  romexis_images/
+  romexis_cache/
+  romexis_ergodata/
+  sql-backup/
+  firebird/
 ```
 
-Supported backend identifiers:
+The same persistent data root can be used across server recreations. Backend-specific data stays in the selected database volume or host directory.
 
-| Value | Backend |
+---
-|---|---|
-| `SERVER_DB=5` | Microsoft SQL Server |
-| `SERVER_DB=4` | Firebird |
 
-Backend-specific logic is split into:
+## Admin Runtime Architecture
+
+`romexis-admin` provides a graphical Linux container for Romexis Admin / RomexisConfig.
+
+It starts:
 
 ```text
-/opt/init-romexis-mssql-db.sh
+Xvfb
-/opt/init-romexis-firebird-db.sh
+Openbox
+xcompmgr
+x11vnc
+noVNC / websockify
 ```
+
+RomexisConfig can be started on demand when a VNC/noVNC client connects and stopped again when the last client disconnects.
+
+---
+
+## mRomexis Web App Architecture
+
+`romexis-app` is a Tomcat image containing:
+
+```text
+/usr/local/tomcat/webapps/ROOT.war
+```
+
+The WAR is copied from the Romexis payload:
+
+```text
+/opt/romexis/broker/mromexis-html.war
+```
+
+This file exists only in Romexis 6.5.3 and newer.

Build-System.md

@@ -1,12 +1,13 @@
 # Build System
 
-The build system is split into independent layers.
+The build system is split into independent layers and service images.
 
 ```text
 romexis-payload
         |
-        v
+        +--> romexis-server
-romexis-server
+        +--> romexis-admin
+        +--> romexis-mromexis-app
         ^
         |
 romexis-base-jre
@@ -23,7 +24,7 @@ romexis-server
 
 ### Payload build
 
-The payload build extracts the official Romexis installer.
+The payload build extracts the official Romexis Windows installer.
 
 It produces:
 
@@ -33,6 +34,8 @@ It produces:
 /opt/romexis/version
 ```
 
+It also provides files consumed by other service images, including Admin files and the mRomexis Web App WAR when available.
+
 ### Firebird payload build
 
 The Firebird payload build extracts the macOS installer database package.
@@ -68,38 +71,111 @@ The final server image imports:
 - Java property agent
 - runtime helper scripts
 
+### Admin image build
+
+The Admin image imports Romexis Admin files from the payload and adds a browser-accessible X11/noVNC runtime.
+
+Important runtime components:
+
+```text
+Xvfb
+Openbox
+xcompmgr
+x11vnc
+noVNC/websockify
+JavaFX
+```
+
+### mRomexis Web App build
+
+The mRomexis Web App image copies:
+
+```text
+/opt/romexis/broker/mromexis-html.war
+```
+
+from the Romexis payload into Tomcat as:
+
+```text
+/usr/local/tomcat/webapps/ROOT.war
+```
+
+This is only possible for Romexis 6.5.3 and newer.
+
 ---
 
-## Local Build Commands
+## Local Build Scripts
+
+Local builds are handled through:
+
+```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
+```
+
+Build individual image groups:
+
+```bash
+./scripts/build-local.sh base server
+./scripts/build-local.sh admin mromexis
+./scripts/build-local.sh migration
+```
+
+---
+
+## Manual Docker Build Examples
 
 Build payload:
 
 ```bash
-docker build   --build-arg ROMEXIS_VERSION=6.5.3.444.203   -t gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203   ./romexis-payload
+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
-```
-
-Build Firebird payload:
-
-```bash
-docker build   --build-arg ROMEXIS_VERSION=6.5.3.444.203   -t gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest   ./romexis-firebird-payload
 ```
 
 Build server image:
 
 ```bash
-docker build   --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   ./romexis
+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
+```
+
+Build Admin image:
+
+```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
+```
+
+Build mRomexis Web App:
+
+```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
 ```
 
 ---
 
-## Debug Build
+## Runtime Compose Relationship
 
-Disable cache and show full logs:
+The runtime Compose files use multi-architecture manifest tags instead of architecture-specific tags.
 
-```bash
+Feature branches use `IMAGE_SUFFIX`:
-docker build   --no-cache   --progress=plain   --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   ./romexis
+
+```env
+IMAGE_SUFFIX=-feature-romexis-admin
 ```
 
+Runtime Compose image references then resolve to branch-specific manifests.
+
 ---
 
 ## Docker Cache Cleanup

CI-CD-Pipeline.md

@@ -15,12 +15,31 @@ romexis-base-jre:11-amd64
 romexis-base-jre:11-arm64
 romexis-server:<version>-amd64
 romexis-server:<version>-arm64
-romexis-server:<version> multiarch manifest
+romexis-admin:<version>-amd64
-migration-service
+romexis-admin:<version>-arm64
+romexis-mromexis-app:<version>-amd64
+romexis-mromexis-app:<version>-arm64
+romexis-migration-service:amd64
+romexis-migration-service:arm64
+multiarch manifests
 ```
 
 ---
 
+## Branch Suffix Handling
+
+For `main`, image tags are published without a suffix.
+
+For feature branches, the branch name is normalized and appended as an image suffix:
+
+```text
+-feature-romexis-admin
+```
+
+This allows feature branch images and manifests to be tested without overwriting `main` images.
+
+---
+
 ## Payload Build Logic
 
 The Windows payload build checks version definitions and copy-map changes.
@@ -70,6 +89,46 @@ Then builds the final runtime image for each architecture.
 
 ---
 
+## Admin Build
+
+The Admin build consumes the Romexis payload and builds:
+
+```text
+romexis-admin:<version>-amd64
+romexis-admin:<version>-arm64
+romexis-admin:<version>
+romexis-admin:latest
+```
+
+The final image contains the graphical noVNC runtime and Romexis Admin / RomexisConfig files.
+
+---
+
+## mRomexis Web App Build
+
+mRomexis Web App images are built only for Romexis versions where:
+
+```text
+version >= 6.5.3
+```
+
+Older versions are skipped because the payload does not contain:
+
+```text
+/opt/romexis/broker/mromexis-html.war
+```
+
+Published tags:
+
+```text
+romexis-mromexis-app:<version>-amd64
+romexis-mromexis-app:<version>-arm64
+romexis-mromexis-app:<version>
+romexis-mromexis-app:latest
+```
+
+---
+
 ## Push vs Load
 
 In CI, use `--push` for buildx output when publishing images.
@@ -104,18 +163,14 @@ romexis-firebird-payload:latest
 
 then the Firebird payload pipeline must push `latest`.
 
-Build command should include:
+### mRomexis build skipped
 
-```bash
+Check the Romexis version. mRomexis Web App is built only for 6.5.3 and newer.
--t "$FIREBIRD_PAYLOAD_IMAGE:latest"
-```
 
 ### Payload missing from final image
 
 Check the final image:
 
 ```bash
-docker run --rm --entrypoint find \
+docker run --rm --entrypoint find   gitea.buchhorster.de/planmeca/romexis-server:<tag>   /opt -maxdepth 3 -type f
-  gitea.buchhorster.de/planmeca/romexis-server:<tag> \
-  /opt -maxdepth 3 -type f
 ```

Compose-Runtime.md

@@ -0,0 +1,180 @@
+# Compose Runtime
+
+The runtime Compose setup is split into a common base file and backend-specific override files.
+
+---
+
+## Files
+
+```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` is no longer required for local development. Local image builds are handled through `scripts/build-local.*`.
+
+---
+
+## Backend Selection
+
+The selected backend is controlled in `.env`.
+
+### 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
+```
+
+On native Windows shells the Compose file separator may need to be `;` instead of `:`:
+
+```env
+COMPOSE_PATH_SEPARATOR=;
+COMPOSE_FILE=docker-compose.yml;docker-compose.${DATABASE_BACKEND}.yml
+```
+
+After this, the stack can always be started with:
+
+```bash
+docker compose up -d
+```
+
+Inspect the effective configuration:
+
+```bash
+docker compose config
+```
+
+---
+
+## Base Runtime Services
+
+The base Compose file contains the shared services:
+
+```text
+romexis
+romexis-admin
+romexis-app
+proxy
+```
+
+Backend-specific files add or override database services and database-related environment variables.
+
+---
+
+## MSSQL Override
+
+The MSSQL override typically provides:
+
+```text
+mssql
+romexis-migration
+```
+
+It also configures the Romexis server for the MSSQL backend, for example:
+
+```env
+SERVER_DB=5
+MSSQL_HOST=mssql
+ROMEXIS_DB_NAME=Romexis_db
+```
+
+---
+
+## Firebird Override
+
+The Firebird override typically provides:
+
+```text
+firebird
+```
+
+It configures the Romexis server for the Firebird backend, for example:
+
+```env
+SERVER_DB=4
+FIREBIRD_HOST=firebird
+ROMEXIS_DB_USER=sysdba
+```
+
+---
+
+## Image Tags and Branch Suffixes
+
+The runtime Compose files use multi-architecture 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}
+```
+
+For `main`, `IMAGE_SUFFIX` stays empty:
+
+```env
+IMAGE_SUFFIX=
+```
+
+For feature branches:
+
+```env
+IMAGE_SUFFIX=-feature-romexis-admin
+```
+
+This prevents feature branch images from overwriting the runtime images used by `main`.
+
+---
+
+## Common Commands
+
+Start the selected backend stack:
+
+```bash
+docker compose up -d
+```
+
+Recreate services after image updates:
+
+```bash
+docker compose up -d --force-recreate
+```
+
+Show logs:
+
+```bash
+docker compose logs -f
+```
+
+Show a single service:
+
+```bash
+docker compose logs -f romexis
+docker compose logs -f romexis-admin
+docker compose logs -f romexis-app
+```
+
+Stop the stack:
+
+```bash
+docker compose down
+```
+
+Remove volumes only when persistent test data may be deleted:
+
+```bash
+docker compose down -v
+```

Configuration.md

@@ -8,43 +8,74 @@ Configuration is mostly handled through environment variables in `.env` and Dock
 
 | Variable | Description |
 |---|---|
-| `ROMEXIS_VERSION` | Romexis version to run |
-| `TARGETARCH` | Target architecture suffix, e.g. `amd64` or `arm64` |
 | `REGISTRY` | Container registry namespace |
-| `ROMEXIS_IMAGE` | Romexis Server image name |
+| `ROMEXIS_VERSION` | Romexis version to run |
+| `IMAGE_SUFFIX` | Optional branch-specific image suffix |
+| `DATABASE_BACKEND` | Selected backend, usually `mssql` or `firebird` |
+| `COMPOSE_FILE` | Compose file chain based on selected backend |
 | `HOST_IP` | Host IP address exposed to Romexis clients |
 | `ROMEXIS_DATA_ROOT` | Root directory for persistent Romexis data |
 
 Example:
 
 ```env
+REGISTRY=gitea.buchhorster.de/planmeca
 ROMEXIS_VERSION=6.5.3.444.203
-TARGETARCH=amd64
+IMAGE_SUFFIX=
-REGISTRY=gitea.buchhorster.de/patrick
+DATABASE_BACKEND=mssql
-ROMEXIS_IMAGE=romexis-server
+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
 ```
 
 ---
 
+## Image Name Variables
+
+```env
+ROMEXIS_IMAGE=romexis-server
+MIGRATION_IMAGE=romexis-migration-service
+ADMINISTRATION_IMAGE=romexis-admin
+MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app
+```
+
+These are combined with `REGISTRY`, `ROMEXIS_VERSION` and `IMAGE_SUFFIX` by the Compose files.
+
+---
+
 ## Database Backend Selection
 
-Romexis uses `SERVER_DB` to identify the database backend.
+Backend selection is controlled by Compose file selection, not only by `SERVER_DB`.
 
-| Value | Backend |
+### MSSQL
-|---|---|
+
-| `5` | Microsoft SQL Server |
+```env
-| `4` | Firebird |
+DATABASE_BACKEND=mssql
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+The MSSQL override then sets the Romexis backend values, for example:
 
 ```env
 SERVER_DB=5
+MSSQL_HOST=mssql
 ```
 
-or:
+### Firebird
+
+```env
+DATABASE_BACKEND=firebird
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+The Firebird override then sets the Romexis backend values, for example:
 
 ```env
 SERVER_DB=4
+FIREBIRD_HOST=firebird
 ```
 
 ---
@@ -72,7 +103,6 @@ jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCert
 ## Firebird Settings
 
 ```env
-SERVER_DB=4
 FIREBIRD_PORT=3050
 FIREBIRD_USER=sysdba
 FIREBIRD_PASSWORD=pwr0mex!
@@ -94,6 +124,63 @@ ROMEXIS_DB_PASSWORD=pwr0mex!
 
 ---
 
+## RMI Ports
+
+```env
+SERVER_RMI_LOW_PORT=1100
+SERVER_RMI_HIGH_PORT=1120
+```
+
+These ports must be reachable from Romexis clients.
+
+---
+
+## Romexis Admin Settings
+
+```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
+```
+
+Important behavior:
+
+- `ADMIN_LANGUAGE` is used for the splash screen and as the `language=` parameter for RomexisConfig.
+- `DEBUG_XTERM=true` starts an optional debug terminal inside the noVNC session.
+- `ADMIN_VNC_LIFECYCLE=true` starts RomexisConfig on first VNC/noVNC connect and stops it after the last disconnect.
+- The Admin container uses Openbox and xcompmgr as required runtime components.
+
+---
+
+## mRomexis Web App Settings
+
+```env
+MROMEXIS_WEB_PORT=8081
+```
+
+The mRomexis Web App container is exposed through the proxy service. The backend proxy target is rewritten internally to the Romexis server service.
+
+---
+
+## Migration Service Settings
+
+```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` is shared between the migration service and the database backend for database restore workflows.
+
+---
+
 ## Database Initialization Version Limit
 
 The database initializer derives the schema target from:
@@ -118,24 +205,14 @@ If the container Romexis version is newer than the configured max, the script pr
 
 ---
 
-## RMI Ports
+## Property Agent
+
+The Java Property Agent can set Romexis `RxProperties` from environment variables.
+
+Syntax:
 
 ```env
-SERVER_RMI_LOW_PORT=1100
+PROPERTY_AGENT_SET_<RXPROPERTY_NAME>=<value>
-SERVER_RMI_HIGH_PORT=1120
 ```
 
-These ports must be reachable from Romexis clients.
+This is primarily relevant for the Romexis server runtime. In the Admin container the PropertyAgent is disabled by default.
-
----
-
-## Migration Service Settings
-
-```env
-MIGRATION_HTTP_PORT=8080
-MIGRATION_SFTP_PORT=2222
-MIGRATION_API_TOKEN=change-me
-DATABASE_BACKUP_DIR=/srv/mssql-backup
-```
-
-`DATABASE_BACKUP_DIR` is shared between the migration service and the database backend for database restore workflows.

Container-Images.md

@@ -7,55 +7,57 @@ Images are published to the Gitea package registry namespace used by the project
 ## Main Images
 
 ```text
-gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64
-gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64
-
 gitea.buchhorster.de/planmeca/romexis-payload:<version>
 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:<version>-amd64
 gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
 gitea.buchhorster.de/planmeca/romexis-server:<version>
 
-gitea.buchhorster.de/planmeca/romexis-migration-service:<tag>
+gitea.buchhorster.de/planmeca/romexis-admin:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-admin:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-admin:<version>
+gitea.buchhorster.de/planmeca/romexis-admin:latest
+
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>
+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 Strategy
 
-### Base image
+### Payload image
 
-Base images are architecture-specific:
+The Windows payload image is versioned by Romexis version and is architecture-independent:
-
-```text
-romexis-base-jre:11-amd64
-romexis-base-jre:11-arm64
-```
-
-### Windows payload image
-
-The Windows payload image is versioned by Romexis version:
 
 ```text
 romexis-payload:6.5.3.444.203
 ```
 
-It is architecture-independent.
+### Base image
 
-### Firebird payload image
+Base images are architecture-specific and also published as a manifest:
-
-The Firebird payload contains the currently maintained Firebird SQL payload and is consumed as a shared image:
 
 ```text
-romexis-firebird-payload:latest
+romexis-base-jre:11-amd64
+romexis-base-jre:11-arm64
+romexis-base-jre:11
 ```
 
-The Firebird SQL payload is not tied to the server image architecture.
-
 ### Server image
 
-Server images are architecture-specific and also published as a multi-architecture manifest:
+Server images are architecture-specific and published as a multi-architecture manifest:
 
 ```text
 romexis-server:6.5.3.444.203-amd64
@@ -63,26 +65,91 @@ romexis-server:6.5.3.444.203-arm64
 romexis-server:6.5.3.444.203
 ```
 
+### Admin image
+
+The Admin image uses the Romexis payload and provides the browser/noVNC Admin runtime:
+
+```text
+romexis-admin:<version>-amd64
+romexis-admin:<version>-arm64
+romexis-admin:<version>
+romexis-admin:latest
+```
+
+### mRomexis Web App image
+
+The mRomexis Web App image is versioned by Romexis version:
+
+```text
+romexis-mromexis-app:<version>-amd64
+romexis-mromexis-app:<version>-arm64
+romexis-mromexis-app:<version>
+romexis-mromexis-app:latest
+```
+
+It can only be built for Romexis versions that contain:
+
+```text
+/opt/romexis/broker/mromexis-html.war
+```
+
+This is expected for Romexis 6.5.3 and newer.
+
+---
+
+## Branch Image Suffixes
+
+For `main`, `IMAGE_SUFFIX` stays empty:
+
+```env
+IMAGE_SUFFIX=
+```
+
+For feature branches, use a branch-specific suffix:
+
+```env
+IMAGE_SUFFIX=-feature-romexis-admin
+```
+
+Example resolved image:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-feature-romexis-admin
+```
+
+This prevents feature branch builds from overwriting or being confused with `main` runtime images.
+
 ---
 
 ## Pulling Images
 
-```bash
-docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-amd64
-```
-
 For multiarch usage:
 
 ```bash
 docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203
 ```
 
----
+Admin image:
-
-## Local Tagging
-
-If Docker Compose expects a registry image but you built locally, tag it accordingly:
 
 ```bash
-docker tag   romexis-server:local   gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-amd64
+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
+```
+
+---
+
+## Runtime Compose Image References
+
+Compose uses manifest tags instead of architecture-specific 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}
 ```

Database-Backends.md

@@ -1,16 +1,77 @@
-Willkommen im Wiki.# Database Backends
+# Database Backends
 
-Romexis supports multiple database backends. This Docker project currently treats Microsoft SQL Server as the default backend and Firebird as the parallel backend under development.
+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.
+
+---
+
+## Compose Backend Selection
+
+The database backend is selected in `.env` with `DATABASE_BACKEND` and `COMPOSE_FILE`.
+
+### 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
+```
+
+The backend-specific Compose override sets the actual Romexis backend variables.
 
 ---
 
 ## Backend Identifiers
 
+Romexis itself still uses `SERVER_DB` internally.
+
 | `SERVER_DB` | Backend |
 |---|---|
 | `5` | Microsoft SQL Server |
 | `4` | Firebird |
 
+For normal operation, do not set `SERVER_DB` manually in the base `.env` unless you are debugging. Let the backend-specific Compose override set it.
+
+---
+
+## Backend Services
+
+### MSSQL
+
+The MSSQL override starts the `mssql` service and configures Romexis to connect to:
+
+```text
+mssql:1433
+```
+
+Typical values:
+
+```env
+MSSQL_SA_PASSWORD=Pwr0mex!s!!!
+ROMEXIS_DB_NAME=Romexis_db
+ROMEXIS_DB_USER=romexis
+ROMEXIS_DB_PASSWORD=romexis
+```
+
+### Firebird
+
+The Firebird override starts the `firebird` service and configures Romexis to connect through Jaybird.
+
+Typical values:
+
+```env
+FIREBIRD_USER=sysdba
+FIREBIRD_PASSWORD=pwr0mex!
+FIREBIRD_DB_PATH=/firebird/data/romexis.fdb
+```
+
 ---
 
 ## Initialization Scripts
@@ -58,15 +119,6 @@ Example:
 
 The scripts do not rely on plain numeric order because Romexis update markers do not sort naturally.
 
-Example:
-
-```text
-6.0 -> 600
-6.1 -> 610
-6.3 -> 63
-6.4 -> 64
-```
-
 ---
 
 ## Maximum Schema Version

Home.md

@@ -2,9 +2,9 @@
 
 Welcome to the Romexis Docker project wiki.
 
-This wiki documents the Docker-based Romexis Server stack, the build system, the payload image architecture, database backends, migration service and development workflow.
+This wiki documents the Docker-based Romexis runtime stack, the backend-specific Compose layout, the local build scripts, the payload image architecture, the Romexis Admin container, the mRomexis Web App container, database backends, migration tooling and CI/CD workflow.
 
-> This project provides a reproducible Docker environment for running Planmeca Romexis Server on Linux, MacOS or WSL with Windows while keeping the build process close to the original installer layout. Romexis application binaries are not stored in the repository. They are extracted from official installer packages during the build process.
+> This project provides a reproducible Docker environment for running Planmeca Romexis Server on Linux, macOS or WSL with Windows while keeping the build process close to the original installer layout. Romexis application binaries are not stored in the repository. They are extracted from official installer packages during the build process.
 
 ---
 
@@ -15,10 +15,14 @@ This wiki documents the Docker-based Romexis Server stack, the build system, the
 | [Project Overview](Project-Overview) | High-level goals, features and supported platforms |
 | [Architecture](Architecture) | Image layers, runtime containers and data flow |
 | [Quick Start](Quick-Start) | Minimal steps to run the stack |
+| [Compose Runtime](Compose-Runtime) | Base Compose file, backend overrides and `.env` selection |
 | [Configuration](Configuration) | Environment variables and runtime configuration |
-| [Container Images](Container-Images) | Registry images, tags and manifests |
+| [Container Images](Container-Images) | Registry images, tags, manifests and branch suffixes |
-| [Build System](Build-System) | Payload, base and server build workflow |
+| [Romexis Admin](Romexis-Admin) | Browser-based RomexisConfig/Admin container via noVNC |
-| [Database Backends](Database-Backends) | MSSQL and Firebird database architecture |
+| [mRomexis Web App](mRomexis-WebApp) | Separate Tomcat-based mRomexis Web frontend container |
+| [Build System](Build-System) | Payload, base, server, admin and web app build workflow |
+| [Local Build Scripts](Local-Build-Scripts) | Local build helper scripts for Linux/macOS and Windows |
+| [Database Backends](Database-Backends) | MSSQL and Firebird backend architecture |
 | [Migration Service](Migration-Service) | Web UI, REST API, SFTP and restore workflow |
 | [Migration Workflow](Migration-Workflow) | Manual and client-assisted migration process |
 | [CI/CD Pipeline](CI-CD-Pipeline) | Drone pipeline and publishing process |
@@ -42,28 +46,55 @@ romexis-base/
 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.
 
-docs/
+scripts/
-  Contains extended project documentation.
+  Contains local build helpers such as build-local.sh and build-local.ps1.
 ```
 
 ---
 
+## Current Runtime Layout
+
+The runtime is split into a base Compose file and backend-specific override files:
+
+```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.
+```
+
+The active backend is selected in `.env` through `DATABASE_BACKEND` and `COMPOSE_FILE`.
+
+---
+
 ## Recommended Reading Order
 
 1. [Project Overview](Project-Overview)
 2. [Architecture](Architecture)
-3. [Quick Start](Quick-Start)
+3. [Compose Runtime](Compose-Runtime)
-4. [Configuration](Configuration)
+4. [Quick Start](Quick-Start)
-5. [Database Backends](Database-Backends)
+5. [Configuration](Configuration)
-6. [Migration Service](Migration-Service)
+6. [Romexis Admin](Romexis-Admin)
-7. [Build System](Build-System)
+7. [mRomexis Web App](mRomexis-WebApp)
-8. [Developer Guide](Developer-Guide)
+8. [Database Backends](Database-Backends)
+9. [Build System](Build-System)
+10. [Developer Guide](Developer-Guide)
 
 ---
 
@@ -71,6 +102,9 @@ docs/
 
 - No Romexis application binaries are committed to the repository.
 - Official Planmeca installer packages are downloaded during payload builds.
+- Runtime backend selection is controlled through `.env` and Docker Compose file selection.
 - Microsoft SQL Server remains the default and most tested backend.
-- Firebird support is being introduced in parallel for macOS/ARM64-oriented scenarios.
+- Firebird support is available through a dedicated Compose override.
+- Romexis Admin is provided through a separate browser/noVNC container.
+- mRomexis Web App is provided through a separate Tomcat-based container and requires Romexis 6.5.3 or newer.
 - The migration service is designed for moving existing Windows-based Romexis installations into the Docker stack.

Local-Build-Scripts.md

@@ -0,0 +1,122 @@
+# Local Build Scripts
+
+Local image builds are handled through dedicated helper scripts.
+
+`docker-compose.build.yml` is no longer required.
+
+---
+
+## Files
+
+```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
+```
+
+---
+
+## Build Targets
+
+Available target groups:
+
+```text
+all
+base
+server
+admin
+mromexis
+migration
+```
+
+Examples:
+
+```bash
+./scripts/build-local.sh base server
+./scripts/build-local.sh admin mromexis
+./scripts/build-local.sh migration
+```
+
+PowerShell examples:
+
+```powershell
+.\scripts\build-local.ps1 -Targets base,server
+.\scripts\build-local.ps1 -Targets admin,mromexis
+```
+
+---
+
+## Environment Variables
+
+The scripts use the same variables as the runtime Compose setup.
+
+Important examples:
+
+```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
+```
+
+For feature branches:
+
+```env
+IMAGE_SUFFIX=-feature-romexis-admin
+```
+
+---
+
+## Relationship to Runtime Compose
+
+The build scripts create the image tags expected by the runtime Compose files.
+
+Runtime Compose uses manifest-style image references such as:
+
+```text
+${REGISTRY}/${ROMEXIS_IMAGE}:${ROMEXIS_VERSION}${IMAGE_SUFFIX}
+${REGISTRY}/${ADMINISTRATION_IMAGE}:latest${IMAGE_SUFFIX}
+${REGISTRY}/${MROMEXIS_WEBAPP_IMAGE}:${ROMEXIS_VERSION}${IMAGE_SUFFIX}
+```
+
+This allows the same `.env` to be used for local builds and runtime startup.
+
+---
+
+## Typical Workflow
+
+```bash
+cp .env.sample .env
+nano .env
+
+./scripts/build-local.sh all
+
+docker compose up -d
+```
+
+Inspect the selected runtime stack:
+
+```bash
+docker compose config
+```

Project-Overview.md

@@ -8,21 +8,48 @@ The project is designed to:
 
 - run Romexis Server in containers
 - keep runtime configuration externalized
+- select the database backend through Docker Compose configuration
 - avoid manual Windows-style setup steps
 - support persistent application and database data
+- provide browser-based access to Romexis Admin / RomexisConfig
+- provide mRomexis Web App as a separate web container
 - support migration from existing installations
-- support repeatable CI/CD builds
+- support repeatable local and CI/CD builds
 - prepare a path for both Microsoft SQL Server and Firebird database backends
 
 ---
 
+## Main Runtime Services
+
+```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.
+```
+
+---
+
 ## Design Principles
 
 ### No Romexis binaries in Git
 
 The repository does not contain Romexis application binaries.
 
-Instead, the build process downloads official installer packages and extracts only the required server components into payload images.
+Instead, the build process downloads official installer packages and extracts only the required server, admin and web components into payload images.
 
 ### Layered image architecture
 
@@ -30,46 +57,55 @@ The build system is split into reusable layers:
 
 ```text
 Payload image
-  Contains extracted Romexis application files and SQL payload.
+  Contains extracted Romexis application files, SQL payload and web/admin artifacts.
 
 Base image
   Contains reusable runtime dependencies such as Java, JavaFX and database tools.
 
-Server image
+Service images
-  Combines payload + base + runtime scripts + Java agent.
+  Build server, admin, migration and mRomexis runtime containers from the prepared layers.
 ```
 
-This keeps individual images easier to maintain and avoids repeated installer downloads when the payload already exists.
-
 ### Architecture-independent payloads
 
-The Romexis payload itself is architecture independent. Architecture-specific parts such as Chilkat native libraries remain in the final server image.
+The Romexis payload itself is architecture independent. Architecture-specific parts such as native libraries remain in service runtime images.
 
-This allows the same payload to be reused for both:
+The same payload can be reused for:
 
 ```text
 linux/amd64
 linux/arm64
 ```
 
-### Database backend flexibility
+### Compose-based backend selection
 
-Microsoft SQL Server remains the default backend.
+Database backends are selected through `.env`:
 
-Firebird support is being added in parallel because macOS-based Romexis installations use Firebird and because this path is more realistic for ARM64 environments.
+```env
+DATABASE_BACKEND=mssql
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+The backend-specific Compose override sets the correct database service and Romexis database environment values.
 
 ---
 
 ## Main Features
 
 - Romexis Server 6.5 Docker runtime
-- Microsoft SQL Server 2022 support
+- Microsoft SQL Server 2022 backend
-- Firebird backend preparation
+- Firebird backend through Compose override
 - automatic database initialization
 - persistent runtime volumes
-- Java Property Agent for runtime property injection
+- Java Property Agent for server-side runtime property injection
 - versioned payload images
-- multi-architecture base and server images
+- multi-architecture service images
+- Romexis Admin container with browser/noVNC access
+- VNC-session-controlled Admin lifecycle
+- localized Admin splash screen
+- mRomexis Web App container for Romexis 6.5.3 and newer
+- OpenResty/Nginx proxy for mRomexis backend requests
+- local build scripts for Linux/macOS and Windows
 - Drone CI/CD pipeline
 - migration service with Web UI, REST API and SFTP
 - Windows migration client
@@ -84,7 +120,9 @@ Firebird support is being added in parallel because macOS-based Romexis installa
 | linux/amd64 | Primary supported target |
 | linux/arm64 | Supported for Romexis runtime images |
 | Microsoft SQL Server on amd64 | Default backend |
-| Firebird on amd64/arm64 | In progress / experimental |
+| Firebird on amd64/arm64 | Supported through dedicated Compose override |
+| Romexis Admin via noVNC | Browser-based access |
+| mRomexis Web App | Requires Romexis 6.5.3 or newer |
 | macOS source migrations | Planned through Firebird and client workflow |
 
 ---
@@ -99,25 +137,34 @@ romexis-payload/
   Windows installer payload extraction.
 
 romexis-firebird-payload/
-  macOS installer Firebird SQL payload extraction.
+  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.
 
-docs/
+scripts/
-  Extended documentation.
+  Local build helper scripts.
 
 docker-compose.yml
-  Default runtime stack.
+  Base runtime stack.
+
+docker-compose.mssql.yml
+  Microsoft SQL Server backend override.
 
 docker-compose.firebird.yml
-  Firebird runtime variant.
+  Firebird backend override.
 
 .drone.yml
   CI/CD pipeline.

Project-Structure.md

@@ -5,14 +5,16 @@
 ├── .drone.yml
 ├── .env.sample
 ├── docker-compose.yml
+├── docker-compose.mssql.yml
 ├── docker-compose.firebird.yml
 ├── README.md
 ├── README.de.md
-├── docs/
+├── BUILD.md
-│   ├── BUILD.md
+├── BUILD.de.md
-│   ├── DEVELOPERS.md
+├── DEVELOPERS.md
-│   ├── MIGRATION_README.md
+├── scripts/
-│   └── MIGRATION_WORKFLOW.md
+│   ├── build-local.sh
+│   └── build-local.ps1
 ├── romexis-base/
 │   └── Dockerfile
 ├── romexis-payload/
@@ -33,6 +35,13 @@
 │   ├── 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
@@ -45,19 +54,49 @@
 
 ---
 
-## Root README Files
+## Compose Files
 
-Only the main README files should stay at repository root:
+```text
+docker-compose.yml
+  Base runtime stack.
+
+docker-compose.mssql.yml
+  MSSQL backend override.
+
+docker-compose.firebird.yml
+  Firebird backend override.
+```
+
+The active backend is selected in `.env`:
+
+```env
+DATABASE_BACKEND=mssql
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+---
+
+## Build Scripts
+
+```text
+scripts/build-local.sh
+scripts/build-local.ps1
+```
+
+These replace the old local `docker-compose.build.yml` workflow.
+
+---
+
+## Root Documentation Files
+
+The main documentation files stay at repository root:
 
 ```text
 README.md
 README.de.md
+BUILD.md
+BUILD.de.md
+DEVELOPERS.md
 ```
 
-Extended documentation belongs in:
+The wiki provides a navigable user-facing documentation layer.
-
-```text
-docs/
-```
-
-The wiki can then provide a navigable, user-facing documentation layer.

Quick-Start.md

@@ -8,34 +8,25 @@ Copy the sample environment file:
 cp .env.sample .env
 ```
 
-Edit `.env` and set at least:
+Edit `.env` and set at least the Romexis version, registry namespace, backend selection and passwords.
+
+Minimal MSSQL example:
 
 ```env
-ROMEXIS_VERSION=6.5.3.444.203
-TARGETARCH=amd64
-
-REGISTRY=gitea.buchhorster.de/patrick
-ROMEXIS_IMAGE=romexis-server
-
-HOST_IP=<your-server-ip>
-
-MSSQL_SA_PASSWORD=<strong-password>
-ROMEXIS_DB_PASSWORD=<strong-password>
-```
-
-or create minimal one 
-
-```env
-ROMEXIS_VERSION=6.5.3.444.203
-TARGETARCH=amd64
-
 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
 
-SERVER_DB=5
+DATABASE_BACKEND=mssql
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
 
-HOST_IP=192.168.65.100 # Replace IP with Host IP
+HOST_IP=192.168.65.100
 
 MSSQL_PORT=1433
 MSSQL_SA_PASSWORD=Pwr0mex!s!!!
@@ -49,111 +40,158 @@ SERVER_RMI_LOW_PORT=1100
 SERVER_RMI_HIGH_PORT=1120
 
 ROMEXIS_DATA_ROOT=/srv/romexis-data
-DATABASE_BACKUP_DIR=/srv/mssql-backup
+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
 ```
 
+For Firebird, change the backend selection:
+
+```env
+DATABASE_BACKEND=firebird
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
 
 ---
 
-## 2. Start default MSSQL stack
+## 2. Start the selected stack
+
+After `.env` is configured, the same command is used for MSSQL and Firebird:
 
 ```bash
 docker compose up -d
 ```
 
-Show logs:
+Show the effective Compose configuration:
+
+```bash
+docker compose config
+```
+
+---
+
+## 3. Show logs
 
 ```bash
 docker compose logs -f romexis
+```
+
+Database backend logs:
+
+```bash
 docker compose logs -f mssql
+# or
+docker compose logs -f firebird
+```
+
+Admin container logs:
+
+```bash
+docker compose logs -f romexis-admin
+```
+
+mRomexis Web App logs:
+
+```bash
+docker compose logs -f romexis-app
 ```
 
 ---
 
-## 3. Start Firebird stack
+## 4. Open browser-based services
 
-If using the Firebird compose variant (with firebird setiings in .env file):
+Romexis Admin / RomexisConfig through noVNC:
 
-```bash
+```text
-docker compose -f docker-compose.firebird.yml up -d
+http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true
 ```
 
-Or combine the base compose file with a Firebird override:
+mRomexis Web App through the proxy:
+
+```text
+http://localhost:8081
+```
+
+Adjust the ports if `ADMIN_NOVNC_PORT` or `MROMEXIS_WEB_PORT` were changed in `.env`.
+
+---
+
+## 5. Recreate after image changes
 
 ```bash
-docker compose   -f docker-compose.yml   -f docker-compose.firebird.yml   up -d
+docker compose up -d --force-recreate
+```
+
+Pull and recreate:
+
+```bash
+docker compose pull
+docker compose up -d --force-recreate
 ```
 
 ---
 
-## 4. Recreate after image changes
+## 6. Open shells for debugging
 
-```bash
+Romexis server:
-docker compose up --force-recreate -d
-```
-
-With rebuild:
-
-```bash
-docker compose up --build --force-recreate -d
-```
-
-No cache rebuild:
-
-```bash
-docker compose build --no-cache --pull
-docker compose up --force-recreate -d
-```
-
----
-
-## 5. Open a shell in the Romexis container
-
-```bash
-docker exec -it romexis-server bash
-```
-
-If bash is unavailable:
-
-```bash
-docker exec -it romexis-server sh
-```
-
-With Compose:
 
 ```bash
 docker compose exec romexis bash
 ```
 
----
+Admin image shell:
-
-## 6. Check database initialization
-
-Inside the Romexis container:
 
 ```bash
-/opt/init-romexis-db.sh
+docker compose run --rm --entrypoint /bin/bash romexis-admin
 ```
 
-Verbose database initialization:
+mRomexis Web App shell:
 
 ```bash
-DB_CREATE_VERBOSE=1 /opt/init-romexis-db.sh
+docker compose run --rm --entrypoint /bin/bash romexis-app
-```
-
-For Firebird debugging:
-
-```bash
-ISQL=isql-fb DB_CREATE_VERBOSE=1 bash -x /opt/init-romexis-firebird-db.sh
 ```
 
 ---
 
-## 7. Stop the stack
+## 7. Local 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
+```
+
+Build individual targets:
+
+```bash
+./scripts/build-local.sh base server
+./scripts/build-local.sh admin mromexis
+./scripts/build-local.sh migration
+```
+
+---
+
+## 8. Stop the stack
 
 ```bash
 docker compose down
@@ -165,4 +203,4 @@ Stop and remove volumes:
 docker compose down -v
 ```
 
-Use volume removal carefully because it deletes persistent database/application data.
+Use volume removal carefully because it deletes persistent database and application data.

Reference-BUILD.de.md

@@ -2,7 +2,7 @@
 
 [Zurück zum README](README.de.md) | [English](BUILD.md)
 
-Dieses Dokument beschreibt den vollständigen Build-Prozess für die Multiarch-Romexis-Docker-Images.
+Dieses Dokument beschreibt den Build-Prozess für die Romexis-Docker-Image-Familien.
 
 ---
 
@@ -11,92 +11,178 @@ Dieses Dokument beschreibt den vollständigen Build-Prozess für die Multiarch-R
 Das Build-System ist darauf ausgelegt, folgende Ziele zu erfüllen:
 
 - reproduzierbare Docker-Builds
-- wiederverwendbares Runtime-Basisimage
+- wiederverwendbare Image-Schichten
+- lokale Entwickler-Builds über Skripte
 - native `amd64`- und `arm64`-Images
 - Multiarch-Manifeste
 - minimale finale Runtime-Images
 - wartbare Installer-Extraktionslogik
-- klare Trennung zwischen Laufzeitabhängigkeiten und Romexis-Anwendungsdateien
+- klare Trennung zwischen Payload-Extraktion, gemeinsamen Laufzeitabhängigkeiten und dienstspezifischen Runtime-Images
 
 ---
 
-## Image-Typen
+## Image-Familien
+
+### Romexis Payload Image
+
+Gebaut aus:
+
+```text
+romexis-payload/Dockerfile
+```
+
+Enthält den extrahierten Installer-Payload:
+
+```text
+/opt/romexis
+/opt/romexis-mssql-db
+```
+
+Das Payload Image ist architekturunabhängig und enthält weder Java noch Chilkat noch Runtime-Dienste.
+
+Tag:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-payload:<version>
+```
 
 ### Romexis Base Image
 
-Das Base Image wird aus `romexis-base/Dockerfile` gebaut.
+Gebaut aus:
 
-Es enthält gemeinsame Laufzeitabhängigkeiten:
+```text
+romexis-base/Dockerfile
+```
 
-- Azul Zulu Java 11 Runtime mit JavaFX/OpenJFX-Unterstützung
+Enthält gemeinsame Server-Laufzeitabhängigkeiten wie Java, JavaFX/OpenJFX-Unterstützung, SQL-Werkzeuge, Firebird-Clientbibliotheken und gemeinsame Betriebssystembibliotheken.
-- Microsoft SQL Server Kommandozeilenwerkzeuge
-- Firebird-Clienttools und Bibliotheken
-- gemeinsame Betriebssystem-Laufzeitbibliotheken
 
 Tags:
 
 ```text
 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
 ```
 
-Das Base Image ist bewusst vom Romexis Server Image getrennt, damit es nicht für jede Romexis-Version erneut gebaut werden muss.
-
 ### Romexis Server Image
 
-Das Server Image wird aus `romexis/Dockerfile` gebaut.
+Gebaut aus:
 
-Es enthält:
+```text
+romexis/Dockerfile
+```
 
-- extrahierte Romexis-Serverdateien
+Verwendet:
-- Romexis-Datenbank-SQL-Skripte
-- native Chilkat-Laufzeitbibliothek
-- Romexis Java Property Agent
-- Runtime-Hilfsskripte
-- Entrypoint- und Initialisierungslogik
 
-Architekturspezifische Tags:
+```text
+romexis-payload:<version>
+romexis-base-jre:11-<arch>
+```
+
+Ergänzt:
+
+- native Chilkat-Laufzeit
+- Romexis Java PropertyAgent
+- Server-Entrypoint
+- Datenbankinitialisierung
+- KeyVault- und Pfadvorbereitung
+
+Tags:
 
 ```text
 gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
 gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
-```
-
-Multiarch-Manifest-Tag:
-
-```text
 gitea.buchhorster.de/planmeca/romexis-server:<version>
 ```
 
----
+### Romexis Migration Service Image
 
-## Build-Argumente
+Gebaut aus dem Migration-Service-Verzeichnis.
 
-### Gemeinsame Argumente
+Stellt Web/API-Dienst für Migrations- und Restore-Workflows bereit.
 
-| Argument | Beschreibung |
+Tags:
-|---------|--------------|
-| `TARGETARCH` | Zielarchitektur, normalerweise `amd64` oder `arm64`. |
-| `ROMEXIS_VERSION` | Angeforderte Romexis-Version oder Versionspräfix. |
 
-### Base-Image-Argumente
+```text
+gitea.buchhorster.de/planmeca/romexis-migration-service:amd64
+gitea.buchhorster.de/planmeca/romexis-migration-service:arm64
+gitea.buchhorster.de/planmeca/romexis-migration-service:latest
+```
 
-| Argument | Beschreibung |
+### Romexis Admin Image
-|---------|--------------|
-| `IMAGE_VERSION` | OCI-Image-Label-Version des Base Images. |
 
-### Server-Image-Argumente
+Gebaut aus:
 
-| Argument | Beschreibung |
+```text
-|---------|--------------|
+romexis-admin/Dockerfile
-| `ROMEXIS_BASE_IMAGE` | Basisimage-Referenz für die finale Romexis-Server-Stage. |
+```
-| `CHILKAT_VERSION` | Version der nativen Chilkat-Bibliothek. |
+
+Verwendet das Romexis Payload Image und stellt eine browserbasierte Romexis Admin / RomexisConfig Umgebung bereit.
+
+Das Image enthält:
+
+- Romexis Admin Dateien aus dem Payload Image
+- Xvfb
+- Openbox
+- xcompmgr
+- x11vnc
+- noVNC/websockify
+- JavaFX Runtime-Unterstützung
+- DxService Linux-Kompatibilitäts-Shim
+- optionales Debug-xterm
+- lokalisierten VNC-Start-Splashscreen
+
+Tags:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-admin:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-admin:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-admin:<version>
+gitea.buchhorster.de/planmeca/romexis-admin:latest
+```
+
+### mRomexis WebApp Image
+
+Gebaut aus:
+
+```text
+romexis-mromexis-app/Dockerfile
+```
+
+Verwendet das Romexis Payload Image und kopiert:
+
+```text
+/opt/romexis/broker/mromexis-html.war
+```
+
+in eine Tomcat-Runtime als:
+
+```text
+/usr/local/tomcat/webapps/ROOT.war
+```
+
+Wichtig:
+
+```text
+mromexis-html.war existiert erst ab Romexis 6.5.3.
+```
+
+Builds für ältere Romexis-Versionen werden bewusst übersprungen.
+
+Tags:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest
+```
 
 ---
 
 ## Versionsauflösung
 
-Romexis-Versionen werden in folgender Datei definiert:
+Unterstützte Romexis-Versionen werden in folgender Datei definiert:
 
 ```text
 romexis-payload/romexis-versions.env
@@ -110,106 +196,84 @@ Format:
 
 Build-Eingabe:
 
-```bash
+```env
-ROMEXIS_VERSION=6.5.3
+ROMEXIS_VERSION=6.5.3.444.203
 ```
 
-Das Dockerfile löst den neuesten passenden Eintrag auf und schreibt die tatsächlich verwendete Version nach:
+Die CI-Pipeline iteriert über diese Datei und baut die benötigten Image-Familien für die verfügbaren Versionen.
-
-```text
-/opt/romexis/version
-```
-
-Dadurch kann lokal oder in CI mit stabilen Versionspräfixen gebaut werden, während das Image intern die exakte Romexis-Version enthält.
 
 ---
 
-## Installer-Download und Extraktion
+## Lokale Builds
 
-Das Repository enthält keine Romexis-Binaries.
+`docker-compose.build.yml` wird nicht mehr verwendet.
 
-Während der `romexis-build`-Stage:
+Lokale Builds werden ausgeführt über:
-
-1. Die passende Installer-URL wird aus `romexis-versions.env` gelesen.
-2. `download-romexis-installer-parts.py` lädt nur die benötigten Installerbestandteile herunter.
-3. Die InstallShield-CAB-Datei wird durch `extract-and-copy-romexis-parts.sh` verarbeitet.
-4. Die finale Romexis-Verzeichnisstruktur wird unter `/opt/romexis` aufgebaut.
-5. SQL-Server-Initialisierungsskripte werden nach `/opt/romexis-mssql-db` kopiert.
-
----
-
-## Mapping-basierte Extraktion
-
-Die Datei:
 
 ```text
-romexis-payload/romexis-copy-map.tsv
+scripts/build-local.sh
+scripts/build-local.ps1
 ```
 
-ist die zentrale Zuordnung zwischen Installer-Komponenten und Zielverzeichnissen.
+### Linux/macOS
-
-Format:
-
-```text
-Source<TAB>Destination
-Broker_jar	/opt/romexis/broker
-Server_jar	/opt/romexis/server
-Server_Program_64bit/server/*.xml	/opt/romexis/server
-```
-
-Das Extraktionsskript nutzt diese Datei für zwei Schritte:
-
-1. Ermitteln, welche Top-Level-CAB-Komponenten extrahiert werden müssen.
-2. Kopieren der gemappten Dateien und Verzeichnisse an ihre Zielorte.
-
-Bei Glob-Mappings wie:
-
-```text
-Server_Program_64bit/server/*.xml
-```
-
-wird die komplette Top-Level-Komponente `Server_Program_64bit` extrahiert, aber nur passende XML-Dateien werden in das Zielverzeichnis kopiert.
-
-Dadurch bleibt das Dockerfile unabhängig vom internen Romexis-Installerlayout.
-
----
-
-## Lokaler Build mit Docker Compose
-
-Verwendet wird:
-
-```text
-docker-compose.build.yml
-```
-
-### Base Image bauen
 
 ```bash
-TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
+chmod +x scripts/build-local.sh
+./scripts/build-local.sh all
 ```
 
-### Romexis Server Image bauen
+### Windows PowerShell
 
-```bash
+```powershell
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
+.\scripts\build-local.ps1 -Targets all
 ```
 
-### Lokal gebauten Stack starten
+### Ausgewählte Image-Familien bauen
 
 ```bash
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d
+./scripts/build-local.sh base server
+./scripts/build-local.sh admin mromexis
+./scripts/build-local.sh migration
 ```
 
-### Build ohne Cache
+Typische `.env` Werte für lokale Builds:
 
-```bash
+```env
-TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build --no-cache romexis-base
+REGISTRY=gitea.buchhorster.de/planmeca
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build --no-cache romexis
+ROMEXIS_VERSION=6.5.3.444.203
+IMAGE_SUFFIX=
+TARGETARCH=amd64
+
+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
 ```
 
 ---
 
-## Manueller Docker Build
+## Manuelle Docker-Build-Beispiele
+
+Manuelle Builds sind hilfreich, um einzelne Image-Familien zu debuggen.
+
+### Payload
+
+```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
+```
 
 ### Base Image
 
@@ -227,52 +291,6 @@ docker buildx build \
 
 ### Server Image
 
-```bash
-docker buildx build \
-  --platform linux/amd64 \
-  --provenance=false \
-  --sbom=false \
-  --build-arg TARGETARCH=amd64 \
-  --build-arg ROMEXIS_VERSION=6.5.3 \
-  --build-arg ROMEXIS_BASE_IMAGE=gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64 \
-  -t gitea.buchhorster.de/planmeca/romexis-server:6.5.3-amd64 \
-  --load \
-  ./romexis
-```
-
----
-
-
----
-
-## Payload-Build-Schicht
-
-Installer-Download und Extraktion finden jetzt in `romexis-payload/` statt.
-
-Das Payload Image enthält nur:
-
-```text
-/opt/romexis
-/opt/romexis-mssql-db
-```
-
-Es enthält weder Java noch Chilkat. Dadurch bleibt das Payload architekturunabhängig.
-
-Manueller Payload-Build:
-
-```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
-```
-
-Das Server Image verwendet danach dieses Payload:
-
 ```bash
 docker buildx build \
   --platform linux/amd64 \
@@ -287,54 +305,96 @@ docker buildx build \
   ./romexis
 ```
 
-In CI wird das Server Image mit Buildx `--push` veröffentlicht, um den langsamen lokalen Export und das Entpacken durch `--load` zu vermeiden.
+### Admin Image
+
+```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-admin:6.5.3.444.203-amd64 \
+  --load \
+  ./romexis-admin
+```
+
+### mRomexis WebApp
+
+```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
+```
 
 ---
 
-## Aktueller CI/CD-Ablauf
+## Drone CI/CD Ablauf
 
-Die Drone-Pipeline folgt jetzt dieser Reihenfolge:
+Die Drone-Pipeline baut und veröffentlicht die Image-Familien in mehreren Stufen.
+
+Grobe Reihenfolge:
 
 ```text
-payload -> base amd64 -> server amd64 -> migration amd64 -> base arm64 -> server arm64 -> migration arm64 -> manifests
+payload
+-> base amd64
+-> server amd64
+-> migration amd64
+-> admin amd64
+-> mRomexis amd64
+-> base arm64
+-> server arm64
+-> migration arm64
+-> admin arm64
+-> mRomexis arm64
+-> manifests
 ```
 
-Payload-Rebuild-Regeln:
+Die genaue Reihenfolge kann auf mehrere Architektur-Pipelines aufgeteilt sein.
+
+### Payload-Rebuild-Regeln
 
 - neue Version in `romexis-versions.env`: nur neues Payload Image bauen
 - geänderte URL einer bestehenden Version: diese Version neu bauen
 - geänderte `romexis-copy-map.tsv`, Payload-Dockerfile oder Hilfsskripte: alle Payload-Versionen neu bauen
 - vorhandenes Payload ohne relevante Änderung: überspringen
 
-Veröffentlichte Image-Familien:
+### mRomexis-Versionsregel
+
+mRomexis-WebApp-Images werden nur gebaut, wenn gilt:
 
 ```text
-romexis-payload:<version>
+version >= 6.5.3
-romexis-base-jre:11-amd64
-romexis-base-jre:11-arm64
-romexis-base-jre:11
-romexis-server:<version>-amd64
-romexis-server:<version>-arm64
-romexis-server:<version>
-romexis-migration-service:amd64
-romexis-migration-service:arm64
-romexis-migration-service:latest
 ```
 
+Ältere Versionen werden übersprungen, weil das Payload kein `mromexis-html.war` enthält.
 
-## CI/CD Build-Ablauf
+### Manifest-Veröffentlichung
 
-Die Drone-Pipeline folgt dieser Reihenfolge:
+Zuerst werden architekturspezifische Tags erstellt:
 
-1. `romexis-base-jre:11-amd64` bauen und veröffentlichen.
+```text
-2. `romexis-server:<version>-amd64` bauen und veröffentlichen.
+<image>:<version>-amd64
-3. `romexis-base-jre:11-arm64` bauen und veröffentlichen.
+<image>:<version>-arm64
-4. `romexis-server:<version>-arm64` bauen und veröffentlichen.
+```
-5. Multiarch-Manifest erstellen und veröffentlichen.
 
-Das Publishing erfolgt bewusst seriell, um Registry-Last und parallele Upload-Probleme zu vermeiden.
+Danach erstellt Drone das Multiarch-Manifest:
 
-Buildx wird mit folgenden Optionen verwendet:
+```text
+<image>:<version>
+```
+
+Für ausgewählte Dienste wird zusätzlich ein `latest` Alias aus der Default-Romexis-Version in `.env.sample` erzeugt.
+
+Buildx verwendet:
 
 ```bash
 --provenance=false
@@ -345,22 +405,64 @@ Dies verbessert die Kompatibilität mit Registries, die OCI-Attestations nicht z
 
 ---
 
-## Empfohlene Build-Reihenfolge
+## Zusammenhang zwischen Runtime Compose und Build
 
-Für lokale Entwicklung:
+Die Runtime-Compose-Dateien verwenden Manifest-Tags statt architekturspezifischer Tags.
 
-```bash
+Für `main` bleibt `IMAGE_SUFFIX` leer:
-TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
+
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
+```env
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d
+IMAGE_SUFFIX=
 ```
 
-Für CI:
+Für Feature-Branches wird ein Branch-Suffix verwendet:
 
-```text
+```env
-base amd64 -> server amd64 -> base arm64 -> server arm64 -> manifest
+IMAGE_SUFFIX=-feature-romexis-admin
 ```
 
+Die Runtime-Compose-Image-Referenzen lösen dadurch auf die passenden branch-spezifischen Manifeste auf.
+
+---
+
+## Wartungshinweise
+
+### Neue Romexis-Version hinzufügen
+
+1. Installer-URL in `romexis-payload/romexis-versions.env` ergänzen.
+2. Prüfen, ob die Copy-Map weiterhin zum Installerlayout passt.
+3. Payload Image bauen oder durch CI bauen lassen.
+4. Server/Admin/mRomexis-Images bauen, sofern zutreffend.
+5. Stack starten und Server, Admin und WebApp testen.
+
+### Änderungen am Installerlayout
+
+1. `romexis-payload/romexis-copy-map.tsv` aktualisieren.
+2. Payload Image neu bauen.
+3. Benötigte Dateien unter `/opt/romexis` prüfen.
+4. Abhängige Runtime-Images neu bauen.
+
+### Änderungen am Admin Image
+
+Prüfen:
+
+- JavaFX-Native-Libraries
+- `/usr/lib/jni` Symlinks
+- Openbox-Start
+- xcompmgr-Start
+- noVNC-Zugriff
+- VNC-Lifecycle-Verhalten
+- Admin-Sprache als Startparameter
+
+### Änderungen an der mRomexis WebApp
+
+Prüfen:
+
+- `mromexis-html.war` existiert im Payload
+- Tomcat deployed `ROOT.war`
+- Proxy-Endpunkt ist kein offener Proxy
+- Versionsfilter überspringt weiterhin nicht unterstützte Romexis-Versionen
+
 ---
 
 ## Build-Artefakte
@@ -377,23 +479,19 @@ Das finale Server Image enthält:
 /entrypoint.sh
 ```
 
-Temporäre Installerdateien werden während des Builds entfernt.
+Das finale Admin Image enthält:
 
----
+```text
+/opt/romexis/admin
+/opt/romexis/admin/RomexisPropertyAgent.jar
+/opt/romexis/admin/libDxService.so
+/opt/romexis/admin/libDxService_64.so
+/opt/romexis/admin/RxClientClinic.jar
+/usr/local/bin/start.sh
+```
 
-## Wartungshinweise
+Das finale mRomexis-WebApp-Image enthält:
 
-Neue Romexis-Version hinzufügen:
+```text
-
+/usr/local/tomcat/webapps/ROOT.war
-1. Installer-URL in `romexis-payload/romexis-versions.env` ergänzen.
+```
-2. Image mit neuer Version oder neuem Versionspräfix bauen.
-3. `/opt/romexis/version` prüfen.
-4. Container starten und Datenbankinitialisierung prüfen.
-5. Client-Verbindung über konfigurierte RMI-Adresse und Ports testen.
-
-Wenn sich das Installerlayout ändert:
-
-1. `romexis-payload/romexis-copy-map.tsv` aktualisieren.
-2. Server Image neu bauen.
-3. Prüfen, ob alle benötigten Dateien in `/opt/romexis` vorhanden sind.
-4. Dockerfile nur ändern, wenn neue Build-Werkzeuge erforderlich sind.

Reference-BUILD.md

@@ -2,7 +2,7 @@
 
 [Back to README](README.md) | [Deutsch](BUILD.de.md)
 
-This document describes the complete build process for the multi-architecture Romexis Docker images.
+This document describes the build process for the Romexis Docker image families.
 
 ---
 
@@ -11,92 +11,178 @@ This document describes the complete build process for the multi-architecture Ro
 The build system is designed to provide:
 
 - reproducible Docker builds
-- a reusable runtime base image
+- reusable image layers
+- local developer builds through scripts
 - native `amd64` and `arm64` images
 - multi-architecture manifests
 - minimal final runtime images
 - maintainable installer extraction logic
-- clear separation between runtime dependencies and Romexis application files
+- clear separation between payload extraction, shared runtime dependencies and service-specific runtime images
 
 ---
 
-## Image Types
+## Image Families
+
+### Romexis Payload Image
+
+Built from:
+
+```text
+romexis-payload/Dockerfile
+```
+
+Contains the extracted installer payload:
+
+```text
+/opt/romexis
+/opt/romexis-mssql-db
+```
+
+The payload image is architecture-independent and does not contain Java, Chilkat or runtime services.
+
+Tag:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-payload:<version>
+```
 
 ### Romexis Base Image
 
-The base image is built from `romexis-base/Dockerfile`.
+Built from:
 
-It contains shared runtime dependencies:
+```text
+romexis-base/Dockerfile
+```
 
-- Azul Zulu Java 11 runtime with JavaFX/OpenJFX support
+Contains shared server runtime dependencies such as Java, JavaFX/OpenJFX support, SQL tooling, Firebird client libraries and common OS libraries.
-- Microsoft SQL Server command-line tools
-- Firebird client tools and libraries
-- common operating system runtime libraries
 
 Tags:
 
 ```text
 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
 ```
 
-The base image is intentionally separated from the Romexis Server image so it does not need to be rebuilt for every Romexis version.
-
 ### Romexis Server Image
 
-The server image is built from `romexis/Dockerfile`.
+Built from:
 
-It contains:
+```text
+romexis/Dockerfile
+```
 
-- extracted Romexis server files
+Consumes:
-- Romexis database SQL scripts
-- native Chilkat runtime library
-- Romexis Java property agent
-- runtime helper scripts
-- entrypoint and initialization logic
 
-Architecture-specific tags:
+```text
+romexis-payload:<version>
+romexis-base-jre:11-<arch>
+```
+
+Adds:
+
+- native Chilkat runtime
+- Romexis Java PropertyAgent
+- server entrypoint
+- database initialization scripts
+- KeyVault and path preparation logic
+
+Tags:
 
 ```text
 gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
 gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
-```
-
-Multi-architecture manifest tag:
-
-```text
 gitea.buchhorster.de/planmeca/romexis-server:<version>
 ```
 
----
+### Romexis Migration Service Image
 
-## Build Arguments
+Built from the migration service directory.
 
-### Common arguments
+Provides the web/API service for migration and restore workflows.
 
-| Argument | Description |
+Tags:
-|---------|-------------|
-| `TARGETARCH` | Target architecture, usually `amd64` or `arm64`. |
-| `ROMEXIS_VERSION` | Requested Romexis version or version prefix. |
 
-### Base image arguments
+```text
+gitea.buchhorster.de/planmeca/romexis-migration-service:amd64
+gitea.buchhorster.de/planmeca/romexis-migration-service:arm64
+gitea.buchhorster.de/planmeca/romexis-migration-service:latest
+```
 
-| Argument | Description |
+### Romexis Admin Image
-|---------|-------------|
-| `IMAGE_VERSION` | OCI image label version for the base image. |
 
-### Server image arguments
+Built from:
 
-| Argument | Description |
+```text
-|---------|-------------|
+romexis-admin/Dockerfile
-| `ROMEXIS_BASE_IMAGE` | Base image reference used by the final Romexis Server stage. |
+```
-| `CHILKAT_VERSION` | Native Chilkat library version. |
+
+Consumes the Romexis payload and provides a browser-accessible Romexis Admin / RomexisConfig environment.
+
+The image includes:
+
+- Romexis Admin files from the payload image
+- Xvfb
+- Openbox
+- xcompmgr
+- x11vnc
+- noVNC/websockify
+- JavaFX runtime support
+- DxService Linux compatibility shim
+- optional debug xterm
+- localized VNC startup splash screen
+
+Tags:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-admin:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-admin:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-admin:<version>
+gitea.buchhorster.de/planmeca/romexis-admin:latest
+```
+
+### mRomexis Web App Image
+
+Built from:
+
+```text
+romexis-mromexis-app/Dockerfile
+```
+
+Consumes the Romexis payload and copies:
+
+```text
+/opt/romexis/broker/mromexis-html.war
+```
+
+into a Tomcat runtime as:
+
+```text
+/usr/local/tomcat/webapps/ROOT.war
+```
+
+Important:
+
+```text
+mromexis-html.war exists only in Romexis 6.5.3 and newer.
+```
+
+Builds for older Romexis versions are intentionally skipped.
+
+Tags:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest
+```
 
 ---
 
 ## Version Resolution
 
-Romexis versions are defined in:
+Supported Romexis versions are defined in:
 
 ```text
 romexis-payload/romexis-versions.env
@@ -110,108 +196,86 @@ Format:
 
 Build input:
 
-```bash
+```env
-ROMEXIS_VERSION=6.5.3
+ROMEXIS_VERSION=6.5.3.444.203
 ```
 
-The Dockerfile resolves the newest matching entry and writes the resolved version to:
+The CI pipeline iterates over this file and builds the required image families for the available versions.
-
-```text
-/opt/romexis/version
-```
-
-This makes it possible to build using a stable prefix while still tagging the final image with the exact resolved Romexis version in CI.
 
 ---
 
-## Installer Download and Extraction
+## Local Builds
 
-The build does not store Romexis binaries in the repository.
+`docker-compose.build.yml` is no longer used.
 
-During the `romexis-build` stage:
+Local builds are handled by:
-
-1. The selected installer URL is read from `romexis-versions.env`.
-2. `download-romexis-installer-parts.py` downloads only the required installer parts.
-3. The InstallShield CAB file is processed by `extract-and-copy-romexis-parts.sh`.
-4. The final Romexis directory layout is assembled under `/opt/romexis`.
-5. SQL Server initialization scripts are copied to `/opt/romexis-mssql-db`.
-
----
-
-## Mapping-Based Extraction
-
-The file:
 
 ```text
-romexis-payload/romexis-copy-map.tsv
+scripts/build-local.sh
+scripts/build-local.ps1
 ```
 
-is the central mapping between installer components and final target directories.
+### Linux/macOS
-
-Format:
-
-```text
-Source<TAB>Destination
-Broker_jar	/opt/romexis/broker
-Server_jar	/opt/romexis/server
-Server_Program_64bit/server/*.xml	/opt/romexis/server
-```
-
-The extraction script uses this file for two steps:
-
-1. Determine which top-level CAB components must be extracted.
-2. Copy the mapped files and directories to their final destinations.
-
-For glob mappings such as:
-
-```text
-Server_Program_64bit/server/*.xml
-```
-
-the complete top-level component `Server_Program_64bit` is extracted, but only matching XML files are copied to the final destination.
-
-This keeps the Dockerfile independent from the Romexis installer layout and makes future installer changes easier to maintain.
-
----
-
-## Local Build with Docker Compose
-
-Use:
-
-```text
-docker-compose.build.yml
-```
-
-### Build the base image
 
 ```bash
-TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
+chmod +x scripts/build-local.sh
+./scripts/build-local.sh all
 ```
 
-### Build the Romexis Server image
+### Windows PowerShell
 
-```bash
+```powershell
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
+.\scripts\build-local.ps1 -Targets all
 ```
 
-### Start the locally built stack
+### Build selected image families
 
 ```bash
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d
+./scripts/build-local.sh base server
+./scripts/build-local.sh admin mromexis
+./scripts/build-local.sh migration
 ```
 
-### Build without cache
+Typical `.env` values for local builds:
 
-```bash
+```env
-TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build --no-cache romexis-base
+REGISTRY=gitea.buchhorster.de/planmeca
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build --no-cache romexis
+ROMEXIS_VERSION=6.5.3.444.203
+IMAGE_SUFFIX=
+TARGETARCH=amd64
+
+ROMEXIS_IMAGE=romexis-server
+MIGRATION_IMAGE=romexis-migration-service
+ADMINISTRATION_IMAGE=romexis-admin
+MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app
+```
+
+For a feature branch:
+
+```env
+IMAGE_SUFFIX=-feature-romexis-admin
 ```
 
 ---
 
-## Manual Docker Build
+## Manual Docker Build Examples
 
-### Base image
+Manual builds are useful for debugging a single image family.
+
+### Payload
+
+```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
+```
+
+### Base Image
 
 ```bash
 docker buildx build \
@@ -225,53 +289,7 @@ docker buildx build \
   ./romexis-base
 ```
 
-### Server image
+### Server Image
-
-```bash
-docker buildx build \
-  --platform linux/amd64 \
-  --provenance=false \
-  --sbom=false \
-  --build-arg TARGETARCH=amd64 \
-  --build-arg ROMEXIS_VERSION=6.5.3 \
-  --build-arg ROMEXIS_BASE_IMAGE=gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64 \
-  -t gitea.buchhorster.de/planmeca/romexis-server:6.5.3-amd64 \
-  --load \
-  ./romexis
-```
-
----
-
-
----
-
-## Payload Build Layer
-
-Installer download and extraction now happen in `romexis-payload/`.
-
-The payload image contains only:
-
-```text
-/opt/romexis
-/opt/romexis-mssql-db
-```
-
-It does not contain Java or Chilkat. This keeps the payload architecture-independent.
-
-Manual payload build:
-
-```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
-```
-
-The server image then consumes this payload:
 
 ```bash
 docker buildx build \
@@ -287,54 +305,96 @@ docker buildx build \
   ./romexis
 ```
 
-In CI the server image is published with Buildx `--push` instead of `--load` to avoid the slow local image export/unpack step.
+### Admin Image
+
+```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-admin:6.5.3.444.203-amd64 \
+  --load \
+  ./romexis-admin
+```
+
+### mRomexis Web App
+
+```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
+```
 
 ---
 
-## Current CI/CD Flow
+## Drone CI/CD Flow
 
-The Drone pipeline now follows this order:
+The Drone pipeline builds and publishes the image families in stages.
+
+High-level flow:
 
 ```text
-payload -> base amd64 -> server amd64 -> migration amd64 -> base arm64 -> server arm64 -> migration arm64 -> manifests
+payload
+-> base amd64
+-> server amd64
+-> migration amd64
+-> admin amd64
+-> mRomexis amd64
+-> base arm64
+-> server arm64
+-> migration arm64
+-> admin arm64
+-> mRomexis arm64
+-> manifests
 ```
 
-Payload rebuild rules:
+The exact order may be split across separate architecture pipelines.
+
+### Payload rebuild rules
 
 - new version in `romexis-versions.env`: build only the new payload image
 - changed URL for an existing version: rebuild that version
 - changed `romexis-copy-map.tsv`, payload Dockerfile or helper scripts: rebuild all payload versions
 - existing payload with no relevant change: skip
 
-Published image families:
+### mRomexis version rule
+
+mRomexis Web App images are built only for Romexis versions where:
 
 ```text
-romexis-payload:<version>
+version >= 6.5.3
-romexis-base-jre:11-amd64
-romexis-base-jre:11-arm64
-romexis-base-jre:11
-romexis-server:<version>-amd64
-romexis-server:<version>-arm64
-romexis-server:<version>
-romexis-migration-service:amd64
-romexis-migration-service:arm64
-romexis-migration-service:latest
 ```
 
+Older versions are skipped because the payload does not contain `mromexis-html.war`.
 
-## CI/CD Build Flow
+### Manifest publishing
 
-The Drone pipeline follows this order:
+Architecture-specific tags are created first:
 
-1. Build and push `romexis-base-jre:11-amd64`.
+```text
-2. Build and push `romexis-server:<version>-amd64`.
+<image>:<version>-amd64
-3. Build and push `romexis-base-jre:11-arm64`.
+<image>:<version>-arm64
-4. Build and push `romexis-server:<version>-arm64`.
+```
-5. Create and push the multi-architecture manifest.
 
-Publishing is intentionally serialized to reduce registry contention and avoid concurrent upload issues.
+Then Drone creates the multi-architecture manifest:
 
-Buildx is used with:
+```text
+<image>:<version>
+```
+
+For selected services, a `latest` alias is also created from the default Romexis version configured in `.env.sample`.
+
+Buildx uses:
 
 ```bash
 --provenance=false
@@ -345,22 +405,64 @@ This improves compatibility with registries that do not handle OCI attestations
 
 ---
 
-## Recommended Build Order
+## Runtime Compose and Build Relationship
 
-For local development:
+The runtime Compose files use manifest tags instead of architecture-specific tags.
 
-```bash
+For `main`, `IMAGE_SUFFIX` is empty:
-TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
+
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
+```env
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d
+IMAGE_SUFFIX=
 ```
 
-For CI:
+For feature branches, use a branch suffix:
 
-```text
+```env
-base amd64 -> server amd64 -> base arm64 -> server arm64 -> manifest
+IMAGE_SUFFIX=-feature-romexis-admin
 ```
 
+Runtime Compose image references then resolve to the corresponding branch-specific manifests.
+
+---
+
+## Maintenance Notes
+
+### Add a new Romexis version
+
+1. Add the installer URL to `romexis-payload/romexis-versions.env`.
+2. Ensure the copy map still matches the installer layout.
+3. Build or let CI build the payload image.
+4. Build server/admin/mRomexis images as applicable.
+5. Start the stack and verify server, Admin and Web App behavior.
+
+### Installer layout changes
+
+1. Update `romexis-payload/romexis-copy-map.tsv`.
+2. Rebuild the payload image.
+3. Verify required files under `/opt/romexis`.
+4. Rebuild dependent runtime images.
+
+### Admin image changes
+
+Check:
+
+- JavaFX native libraries
+- `/usr/lib/jni` symlinks
+- Openbox startup
+- xcompmgr startup
+- noVNC access
+- VNC lifecycle behavior
+- Admin language startup parameter
+
+### mRomexis Web App changes
+
+Check:
+
+- `mromexis-html.war` exists in the payload
+- Tomcat deploys `ROOT.war`
+- proxy endpoint is not open to arbitrary hosts
+- version filtering still skips unsupported Romexis versions
+
 ---
 
 ## Build Artifacts
@@ -377,23 +479,19 @@ The final server image contains:
 /entrypoint.sh
 ```
 
-Temporary installer files are removed during the build.
+The final Admin image contains:
 
----
+```text
+/opt/romexis/admin
+/opt/romexis/admin/RomexisPropertyAgent.jar
+/opt/romexis/admin/libDxService.so
+/opt/romexis/admin/libDxService_64.so
+/opt/romexis/admin/RxClientClinic.jar
+/usr/local/bin/start.sh
+```
 
-## Maintenance Notes
+The final mRomexis Web App image contains:
 
-When adding support for a new Romexis version:
+```text
-
+/usr/local/tomcat/webapps/ROOT.war
-1. Add the installer URL to `romexis-payload/romexis-versions.env`.
+```
-2. Build the image using the new version or version prefix.
-3. Verify `/opt/romexis/version`.
-4. Start the container and check database initialization logs.
-5. Confirm client connectivity through the configured RMI host and ports.
-
-When the installer layout changes:
-
-1. Update `romexis-payload/romexis-copy-map.tsv`.
-2. Rebuild the server image.
-3. Confirm that all required files exist in `/opt/romexis`.
-4. Keep the Dockerfile unchanged unless new build tools are required.

Reference-README-compose.md

@@ -0,0 +1,44 @@
+# Romexis Docker Compose Refactor
+
+This document has been merged into the normal README files.
+
+Use:
+
+- [README.md](README.md) for English runtime and Compose usage
+- [README.de.md](README.de.md) for German runtime and Compose usage
+- [BUILD.md](BUILD.md) for English build details
+- [BUILD.de.md](BUILD.de.md) for German build details
+
+The important Compose workflow is:
+
+```env
+DATABASE_BACKEND=mssql
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+or:
+
+```env
+DATABASE_BACKEND=firebird
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+Then start the stack with:
+
+```bash
+docker compose up -d
+```
+
+Local builds are handled through:
+
+```bash
+./scripts/build-local.sh all
+```
+
+or:
+
+```powershell
+.\scripts\build-local.ps1 -Targets all
+```

Reference-README.de.md

@@ -1,227 +1,158 @@
 # Romexis Docker
 
-[English](README.md) | [Deutsch](README.de.md) | [Build-Prozess](BUILD.de.md) | [Entwicklerdokumentation](DEVELOPERS.md) | [![Build Status](https://drone.buchhorster.de/api/badges/planmeca/romexis-server-docker/status.svg?ref=refs/heads/main)]
+[English](README.md) | [Build-Prozess](BUILD.de.md) | [Entwicklerdokumentation](DEVELOPERS.md)
 
-> Containerisierte Ausführung von Planmeca Romexis Server 6.5 unter Linux mit Docker, Microsoft SQL Server und einem wiederverwendbaren Multiarch-Romexis-Basisimage.
+> Containerisierte Bereitstellung von Planmeca Romexis Server unter Linux mit Docker, Datenbank-Backend-Auswahl über Docker Compose, optionalem Migration Service, browserbasiertem Romexis Admin und separatem mRomexis WebApp Container.
 
 ---
 
 ## Überblick
 
-Dieses Projekt baut und betreibt den Planmeca Romexis Server in Docker.
+Dieses Projekt baut und betreibt Planmeca Romexis Dienste in Docker.
 
-Der Build-Prozess extrahiert die benötigten Romexis-Serverdateien direkt aus dem offiziellen Romexis-Windows-Installer. Im Repository werden keine Romexis-Programmbinaries gespeichert.
+Die benötigten Romexis-Programmdateien werden während des Builds aus dem offiziellen Romexis-Windows-Installer extrahiert. Im Repository werden keine Romexis-Binaries gespeichert.
 
-Der aktuelle Build ist in Payload-, Base- und Server-Image-Schichten aufgeteilt:
+Der Runtime-Stack ist in klar getrennte Dienste aufgeteilt:
 
-1. **Romexis Base Image**
+- **Romexis Server**  
-   - Stellt Java 11 mit JavaFX-Unterstützung bereit.
+  Hauptdienst mit RMI-Ports, Datenbankzugriff, KeyVault-Vorbereitung und Laufzeitkonfiguration.
-   - Enthält Microsoft SQL Server Kommandozeilenwerkzeuge.
-   - Enthält Firebird-Clientbibliotheken.
-   - Wird separat für `amd64` und `arm64` gebaut.
 
-2. **Romexis Server Image**
+- **Datenbank-Backend**  
-   - Baut auf dem Romexis Base Image auf.
+  Auswahl über `DATABASE_BACKEND` und `COMPOSE_FILE` in der `.env`. Unterstützte Compose-Backends sind aktuell `mssql` und `firebird`.
-   - Lädt und extrahiert den ausgewählten Romexis-Installer.
-   - Erstellt die finale `/opt/romexis`-Verzeichnisstruktur.
-   - Fügt Java Property Agent, Laufzeitskripte und Datenbankinitialisierung hinzu.
 
-Diese Trennung reduziert Duplikate, vereinfacht die Wartung und erlaubt die Wiederverwendung des Laufzeit-Basisimages für unterschiedliche Romexis-Versionen.
+- **Romexis Migration Service**  
+  Optionaler Web/API-Dienst für Restore- und Migrationsabläufe.
+
+- **Romexis Admin**  
+  Browserbasierter Admin-/RomexisConfig-Container über Xvfb, Openbox, xcompmgr, x11vnc und noVNC.
+
+- **mRomexis WebApp**  
+  Separater Tomcat-Container für die mRomexis-Weboberfläche ab Romexis 6.5.3.
 
 ---
 
-## Features
+## Hauptfunktionen
 
-- Romexis Server 6.5 in Docker
+- Romexis Server in Docker
-- Microsoft SQL Server 2022 Unterstützung
+- Microsoft SQL Server und Firebird als Compose-Backends
-- Automatische Datenbankinitialisierung
+- Backend-Auswahl über `.env`
-- Persistente Speicherung aller Nutzdaten
+- Lokale Build-Skripte für reproduzierbare Entwickler-Builds
-- Automatische Vorbereitung von KeyVault und ProgramData
+- Multiarch-Images für `amd64` und `arm64`
-- Unterstützung vorhandener Datenbank-Volumes
+- Payload-Image für Installer-Extraktion
-- Multi-Stage Docker Build
+- Wiederverwendbares Base-Runtime-Image
-- Multiarch-Image-Publishing für `amd64` und `arm64`
+- Server-Image aus Payload- und Base-Image
-- Dediziertes wiederverwendbares Romexis Base Image
+- Migration-Service-Image
-- Mapping-basierte Installer-Extraktion über `romexis-copy-map.tsv`
+- Romexis-Admin-Image mit Browser/noVNC-Zugriff
-- Selektive InstallShield-CAB-Extraktion
+- mRomexis-WebApp-Image
-- Romexis-Installerversionen werden über `romexis-versions.env` verwaltet
+- Branch-spezifische Image-Suffixe über `IMAGE_SUFFIX`
-- Keine Windows Registry erforderlich
+- Java PropertyAgent für serverseitige Runtime-Properties
-- Kein RomexisConfig-Aufruf erforderlich
+- Drone CI/CD mit Multiarch-Manifesten
-- Linux-kompatible Laufzeitpfade
-- Java-Property-Injection über `RomexisPropertyAgent`
-- CI/CD Build-Unterstützung über Drone
 
 ---
 
-## Architektur
+## Runtime-Compose-Struktur
+
+Die Laufzeitumgebung ist in eine Basis-Compose-Datei und backend-spezifische Override-Dateien aufgeteilt:
 
 ```text
-+----------------------+
+.env.sample
-|   Romexis Clients    |
+docker-compose.yml
-+----------+-----------+
+docker-compose.mssql.yml
-           |
+docker-compose.firebird.yml
-           | RMI / Romexis-Protokollports
+scripts/build-local.sh
-           v
+scripts/build-local.ps1
-+----------------------+
-|   Romexis Server     |
-|      Docker          |
-+----------+-----------+
-           |
-           | JDBC
-           v
-+----------------------+
-| Microsoft SQL Server |
-|      Docker          |
-+----------------------+
 ```
 
----
+Die Basisdatei enthält datenbankunabhängige Dienste wie:
-
-## Unterstützte Plattformen
-
-Der Build-Prozess unterstützt folgende Zielarchitekturen:
-
-| Architektur | Docker-Plattform | Tag-Suffix |
-|------------|------------------|------------|
-| x86_64     | `linux/amd64`    | `-amd64`   |
-| ARM64      | `linux/arm64`    | `-arm64`   |
-
-Die Drone-Pipeline erstellt architekturspezifische Images und veröffentlicht anschließend ein Multiarch-Manifest ohne Architektur-Suffix.
-
----
-
-## Voraussetzungen
-
-### Laufzeithost
-
-- Linux-Host
-- Docker Engine
-- Docker Compose Plugin
-- Netzwerkverbindung zwischen Romexis-Clients und den veröffentlichten RMI-Ports
-
-### Build-Host
-
-- Docker Engine mit BuildKit-Unterstützung
-- Docker Buildx
-- Docker Compose Plugin
-- Zugriff auf die Romexis-Installer-Download-URLs aus `romexis-payload/romexis-versions.env`
-- Zugriff auf die konfigurierte Container-Registry
-- Ausreichend Speicherplatz für Installer-Extraktion und Docker-Build-Cache
-
-### Empfohlene Ressourcen
-
-- 8 GB RAM
-- 4 CPU-Kerne
-- 20 GB freier Speicherplatz für den Betrieb
-- Zusätzlicher freier Speicherplatz auf Build-Hosts für Build-Cache und extrahierte Installerdateien
-
----
-
-## Container Images
-
-Die Images werden in der Gitea Container Registry des Projekts veröffentlicht.
-
-### Image-Struktur
 
 ```text
-gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64
+romexis
-gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64
+romexis-admin
-
+romexis-app
-gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
+proxy
-gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
-gitea.buchhorster.de/planmeca/romexis-server:<version>
 ```
 
-Die architekturspezifischen Tags werden für das Multiarch-Manifest verwendet.
+Die Backend-Override-Dateien ergänzen oder überschreiben datenbankspezifische Dienste und Umgebungsvariablen:
 
-### Beispiel-Pull
+```text
+docker-compose.mssql.yml
+docker-compose.firebird.yml
+```
+
+`docker-compose.build.yml` wird nicht mehr benötigt. Lokale Image-Builds laufen über `scripts/build-local.*`.
+
+---
+
+## Backend-Auswahl über `.env`
+
+Der Stack kann mit einem einheitlichen Befehl gestartet werden, wenn das gewünschte Backend in `.env` gesetzt ist.
+
+### MSSQL
+
+```env
+DATABASE_BACKEND=mssql
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+Start:
 
 ```bash
-docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203
+docker compose up -d
 ```
 
-### Installierte Romexis-Version prüfen
+### Firebird
+
+```env
+DATABASE_BACKEND=firebird
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+Start:
 
 ```bash
-docker run --rm \
+docker compose up -d
-  --entrypoint cat \
+```
-  gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203 \
+
-  /opt/romexis/version
+In nativen Windows-Shells kann als Compose-Dateitrenner `;` statt `:` erforderlich sein:
+
+```env
+COMPOSE_PATH_SEPARATOR=;
+COMPOSE_FILE=docker-compose.yml;docker-compose.${DATABASE_BACKEND}.yml
+```
+
+Die effektive Konfiguration prüfen:
+
+```bash
+docker compose config
 ```
 
 ---
 
-## Versionsverwaltung
+## Schnellstart
 
-Die Datei `romexis-payload/romexis-versions.env` ordnet unterstützte Romexis-Versionen den offiziellen Installer-URLs zu.
+Runtime-Konfiguration erstellen:
-
-Beispiel:
-
-```text
-6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip
-6_5_2_189_213=https://content.planmeca.com/files/Planmeca_Romexis_6.5.2.189.213_Win.zip
-```
-
-Das Build-Argument `ROMEXIS_VERSION` kann eine vollständige Version oder ein Präfix enthalten.
-
-Beispiel:
 
 ```bash
-ROMEXIS_VERSION=6.5.3
+cp .env.sample .env
 ```
 
-Der Build löst dies zur neuesten passenden Version auf, zum Beispiel:
+Mindestens anpassen:
 
-```text
+```env
-6.5.3.444.203
+DATABASE_BACKEND=mssql
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+
+ROMEXIS_VERSION=6.5.3.444.203
+IMAGE_SUFFIX=
 ```
 
-Die aufgelöste Version wird im Image gespeichert:
+Stack starten:
-
-```text
-/opt/romexis/version
-```
-
----
-
-## Projektstruktur
-
-```text
-.
-├── docker-compose.yml
-├── docker-compose.build.yml
-├── README.md
-├── README.de.md
-├── BUILD.md
-├── BUILD.de.md
-├── DEVELOPERS.md
-│
-├── romexis-base
-│   └── Dockerfile
-│
-├── romexis
-│   ├── Dockerfile
-│   ├── entrypoint.sh
-│   ├── fix-keystore-alias.sh
-│   ├── init-romexis-db.sh
-│   ├── RomexisPropertyAgent.java
-│   ├── 
-│
-└── data
-    ├── programdata
-    ├── sconfig
-    ├── romexis_images
-    ├── romexis_cache
-    └── romexis_ergodata
-```
-
----
-
-## Betrieb mit fertigen Images
-
-Für den normalen Betrieb wird `docker-compose.yml` verwendet.
 
 ```bash
-ROMEXIS_VERSION=6.5.3.444.203 docker compose up -d
+docker compose up -d
 ```
 
 Logs anzeigen:
@@ -230,19 +161,7 @@ Logs anzeigen:
 docker compose logs -f
 ```
 
-Nur Romexis:
+Stack stoppen:
-
-```bash
-docker compose logs -f romexis
-```
-
-Nur SQL Server:
-
-```bash
-docker compose logs -f mssql
-```
-
-Umgebung stoppen:
 
 ```bash
 docker compose down
@@ -250,96 +169,236 @@ docker compose down
 
 ---
 
-## Lokaler Build mit Docker Compose
+## Runtime-Dienste
 
-Für lokale Builds wird `docker-compose.build.yml` verwendet.
+### Romexis Server
 
-Das Base Image muss vor dem Romexis Server Image gebaut werden, da das Server-Dockerfile das Basisimage über das Build-Argument `ROMEXIS_BASE_IMAGE` verwendet.
+Der Dienst `romexis` startet den eigentlichen Romexis-Backend-Prozess.
+
+Er bereitet vor:
+
+- Romexis-Server-Properties
+- KeyVault- und ProgramData-Pfade
+- Datenbankverbindung
+- Linux-Datenpfade
+- RMI-Host und RMI-Ports
+- optionale Datenbankinitialisierung
+
+Logs:
 
 ```bash
-TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
+docker compose logs -f romexis
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d
 ```
 
-Für einen ARM64-Build-Host:
+Installierte Romexis-Version prüfen:
 
 ```bash
-TARGETARCH=arm64 docker compose -f docker-compose.build.yml --profile build build romexis-base
+docker exec -it romexis-server cat /opt/romexis/version
-TARGETARCH=arm64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
 ```
 
-Weitere Details stehen in [BUILD.de.md](BUILD.de.md).
+### Datenbank-Backend
 
----
+Das aktive Backend wird über `COMPOSE_FILE` geladen.
 
+Für MSSQL ergänzt die Override-Datei den SQL-Server-Dienst und konfiguriert Romexis für Microsoft SQL Server.
 
----
+Für Firebird ergänzt die Override-Datei den Firebird-Dienst und konfiguriert Romexis für Firebird.
 
-## Aktueller Architekturstand
+Prüfen:
 
-Das Projekt verwendet inzwischen drei Build-Schichten statt nur Base- und Server-Image:
+```bash
+docker compose ps
+docker compose logs -f
+docker compose config
+```
 
-1. **Romexis Payload Image**
+### Migration Service
-   - wird aus `romexis-payload/Dockerfile` gebaut
-   - lädt und extrahiert den offiziellen Romexis-Installer
-   - enthält `/opt/romexis` und `/opt/romexis-mssql-db`
-   - ist architekturunabhängig und wird als `romexis-payload:<version>` getaggt
 
-2. **Romexis Base Image**
+Der Migration Service unterstützt Romexis-Migrationen und Restore-Workflows.
-   - wird aus `romexis-base/Dockerfile` gebaut
-   - enthält Java, JavaFX, SQL-Tools und gemeinsame Runtime-Bibliotheken
-   - ist architekturspezifisch
 
-3. **Romexis Server Image**
+Er stellt bereit:
-   - wird aus `romexis/Dockerfile` gebaut
-   - verwendet Payload Image und Base Image
-   - ergänzt Chilkat, Java Property Agent, Laufzeitskripte und Startlogik
-
-Durch das Payload Image müssen Installer-ZIP und CAB-Dateien nicht bei jedem Server-Build erneut heruntergeladen und extrahiert werden.
-
----
-
-## Migration Service
-
-Das Repository enthält jetzt einen Romexis Migration Service und einen Windows Migration Client.
-
-Der Migration Service stellt bereit:
 
 - Web UI und REST API für Migrationsjobs
-- temporäre SFTP-Zugangsdaten pro Job
+- Datenbankbackup-Upload
-- Datenbankbackup-Upload über den Browser
+- temporären SFTP-Zugang pro Migrationsjob
-- automatische serverseitige `manifest.json`-Erzeugung
+- serverseitige `manifest.json`-Erzeugung
-- SQL Server Datenbank-Restore
+- Datenbank-Restore
-- Upload-Validierung
+- Datei-Restore
-- Datei-Restore-Workflow
+- Validierung und Bereinigung
-- Abbruch und Bereinigung von Migrationen
-- Abschluss einer Migration mit Entfernung des SFTP-Zugangs
 - koordinierten Romexis-Neustart über eine gemeinsame State-Datei
 
-Unterstützte Migrationswege:
+Die Neustartkoordination erfolgt über:
-
-1. **Windows Migration Client**
-   - erkennt Romexis-Installation, SQL-Server-Konfiguration und Datenverzeichnisse
-   - erstellt oder nutzt ein Datenbankbackup
-   - lädt Daten per rclone/SFTP hoch
-   - kommuniziert mit der Migration Service API
-
-2. **Manueller Browser- und SFTP-Workflow**
-   - Migrationsjob im Web UI erstellen
-   - Datenbankbackup über den Browser hochladen
-   - Manifest vom Server erzeugen lassen
-   - `romexis_images`, `romexis_ergodata` und optional `romexis_cache` per SFTP hochladen
-   - validieren, wiederherstellen und Migration abschließen
-
-Der Romexis-Neustart nach dem Restore wird über folgende Datei koordiniert:
 
 ```text
 /data/romexis_images/.romexis_restart_state
 ```
 
-Der Migration Service schreibt die Neustartanforderung, der Romexis-Entrypoint führt den Neustart aus und schreibt den finalen Status zurück.
+### Romexis Admin
 
+Der Dienst `romexis-admin` stellt Romexis Admin / RomexisConfig über noVNC bereit.
+
+Beim Containerstart werden die grafischen Runtime-Komponenten gestartet:
+
+```text
+Xvfb -> Openbox -> xcompmgr -> x11vnc -> noVNC
+```
+
+RomexisConfig selbst kann erst beim Aufbau einer VNC/noVNC-Verbindung gestartet werden. Dadurch läuft das Admin-Tool nicht dauerhaft im Hintergrund.
+
+Admin UI öffnen:
+
+```text
+http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true
+```
+
+Typische Admin-Variablen:
+
+```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
+```
+
+`ADMIN_LANGUAGE` unterstützt:
+
+```text
+de
+en
+```
+
+Der gleiche Sprachwert wird für den Splashscreen und den `language=` Parameter von RomexisConfig verwendet.
+
+`DEBUG_XTERM=true` öffnet zusätzlich ein Debug-Terminal in der VNC-Sitzung.
+
+`ADMIN_VNC_LIFECYCLE=true` bedeutet:
+
+- erster VNC/noVNC-Client verbindet sich -> RomexisConfig startet
+- letzter VNC/noVNC-Client trennt sich -> RomexisConfig wird beendet
+- während des Starts wird ein lokalisierter Splashscreen angezeigt
+
+### mRomexis WebApp
+
+Der Dienst `romexis-app` stellt die mRomexis Weboberfläche als eigenständige Tomcat-Anwendung bereit.
+
+Wichtig:
+
+```text
+mromexis-html.war existiert erst ab Romexis 6.5.3.
+```
+
+Ältere Payload-Versionen enthalten diese WAR-Datei nicht und können daher kein gültiges mRomexis-WebApp-Image bauen.
+
+Die WebApp wird normalerweise über den Proxy-Dienst veröffentlicht. Der Proxy behandelt auch den `/proxy?url=...` Endpunkt der Anwendung.
+
+Der Proxy schreibt mRomexis-Proxy-Anfragen auf den internen Romexis-Backend-Dienst um, anstatt dem vom Browser gelieferten Host zu vertrauen. Dadurch müssen keine internen IP-Adressen gepflegt werden und der Endpunkt wird nicht zu einem offenen HTTP-Proxy.
+
+Typische Variable:
+
+```env
+MROMEXIS_WEB_PORT=8081
+```
+
+mRomexis WebApp öffnen:
+
+```text
+http://localhost:8081/
+```
+
+---
+
+## Container Images
+
+Das Projekt verwendet folgende Image-Familien:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-payload:<version>
+
+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:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-server:<version>
+
+gitea.buchhorster.de/planmeca/romexis-migration-service:amd64
+gitea.buchhorster.de/planmeca/romexis-migration-service:arm64
+gitea.buchhorster.de/planmeca/romexis-migration-service:latest
+
+gitea.buchhorster.de/planmeca/romexis-admin:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-admin:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-admin:<version>
+gitea.buchhorster.de/planmeca/romexis-admin:latest
+
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest
+```
+
+Für Feature-Branches wird `IMAGE_SUFFIX` an den Tag angehängt:
+
+```env
+IMAGE_SUFFIX=-feature-romexis-admin
+```
+
+Beispiel:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-feature-romexis-admin
+```
+
+---
+
+## Lokale Image-Builds
+
+Lokale Builds laufen über Skripte.
+
+Linux/macOS:
+
+```bash
+chmod +x scripts/build-local.sh
+./scripts/build-local.sh all
+```
+
+Windows PowerShell:
+
+```powershell
+.\scripts\build-local.ps1 -Targets all
+```
+
+Nur ausgewählte Image-Familien bauen:
+
+```bash
+./scripts/build-local.sh base server
+./scripts/build-local.sh admin mromexis
+./scripts/build-local.sh migration
+```
+
+Typische lokale `.env` Werte:
+
+```env
+REGISTRY=gitea.buchhorster.de/planmeca
+ROMEXIS_VERSION=6.5.3.444.203
+IMAGE_SUFFIX=
+TARGETARCH=amd64
+
+ROMEXIS_IMAGE=romexis-server
+MIGRATION_IMAGE=romexis-migration-service
+ADMINISTRATION_IMAGE=romexis-admin
+MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app
+```
+
+Weitere Build-Details stehen in [BUILD.de.md](BUILD.de.md).
+
+---
 
 ## Persistente Datenverzeichnisse
 
@@ -358,7 +417,7 @@ Enthält persistente Romexis-Serverkonfiguration.
 Gemountet nach:
 
 ```text
-/programdata/Planmeca/Romexis
+/programdata/planmeca/romexis
 ```
 
 Entspricht dem Windows-Pfad `%ProgramData%\Planmeca\Romexis` und enthält KeyVault sowie sicherheitsrelevante Dateien.
@@ -397,27 +456,27 @@ Speichert Ergo- und Zusatzdaten.
 
 ## Datenbankinitialisierung
 
-Beim ersten Start:
+Beim ersten Start kann der Server-Entrypoint das konfigurierte Datenbank-Backend initialisieren.
 
-1. SQL Server startet.
+Typische Aufgaben beim ersten Start:
-2. Romexis wartet, bis SQL Server als erreichbar gilt.
-3. Die Datenbank `Romexis_db` wird erstellt, falls sie fehlt.
-4. Der Datenbankbenutzer `romexis` wird erstellt, falls er fehlt.
-5. Romexis-Schema- und Update-Skripte werden importiert.
-6. Linux-Datenpfade werden in die Datenbank geschrieben.
 
-Die Initialisierung wird übersprungen, wenn Datenbank und Romexis-Benutzer bereits existieren.
+1. Auf das gewählte Datenbank-Backend warten.
+2. Romexis-Datenbank erstellen, falls sie fehlt.
+3. Romexis-Datenbankbenutzer erstellen, falls er fehlt.
+4. Schema- und Update-Skripte importieren, sofern zutreffend.
+5. Linux-Datenpfade in die Datenbank schreiben.
+6. Romexis Server starten.
 
-Deaktivieren:
+Initialisierung deaktivieren:
 
-```yaml
+```env
-ROMEXIS_INIT_DB: "0"
+ROMEXIS_INIT_DB=0
 ```
 
-Ausführliche SQL-Ausgabe:
+Ausführliche SQL-Ausgabe aktivieren:
 
-```yaml
+```env
-DB_CREATE_VERBOSE: "true"
+DB_CREATE_VERBOSE=true
 ```
 
 ---
@@ -430,113 +489,94 @@ Romexis erwartet einen Windows-ähnlichen `ProgramData`-Pfad. Der Entrypoint set
 ProgramData=/programdata
 ```
 
-Der KeyVault-Pfad wird in `romexis_server.properties` geschrieben:
+Der KeyVault-Pfad wird in `romexis_server.properties` geschrieben.
 
-```properties
+Fehlende Schlüsseldateien werden bei Bedarf aus den im Image enthaltenen Defaults initialisiert.
-SERVER_KEYVAULT_PATH=/programdata/Planmeca/Romexis/sconfig
-```
-
-Der Entrypoint initialisiert fehlende Schlüsseldateien aus den im Image enthaltenen Defaults:
-
-- `static_keys_default.p12` -> `static_keys.p12`
-- `initial_keyvault.p12` -> `keyvault.p12`
 
 ---
 
-## RomexisConfig
+## RomexisConfig und Admin-Konfiguration
 
-`RomexisConfig` wird absichtlich nicht ausgeführt.
+Der Server-Container führt RomexisConfig beim Start nicht aus.
 
-In einem Linux-Container kann RomexisConfig versuchen, über Advapi32/JNA auf Windows-Registry-Funktionen zuzugreifen. Die notwendigen Aufgaben übernimmt stattdessen der Docker-Entrypoint.
+Administrative Konfiguration erfolgt über den separaten `romexis-admin` Container. Dadurch bleibt der Server-Container auf den Backend-Prozess fokussiert und wird nicht mit einem grafischen Konfigurationstool vermischt.
-
-Ersetzte Aufgaben:
-
-- KeyVault-Vorbereitung
-- ProgramData-Handling
-- Datenbankkonfiguration
-- Linux-Pfadkonfiguration
-- Runtime-Property-Injection
 
 ---
 
 ## Erweiterte Konfiguration
 
-### Datenbank-URL
-
-Standardmäßig erzeugt der Entrypoint:
-
-```text
-jdbc:sqlserver://<host>:<port>;databaseName=<database>;encrypt=true;trustServerCertificate=true;
-```
-
-Eine vollständige JDBC-URL kann explizit gesetzt werden:
-
-```yaml
-ROMEXIS_DB_URL: "jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;"
-```
-
 ### Datenbank-Backend
 
-```yaml
+Die Backend-Auswahl erfolgt auf Compose-Ebene:
-SERVER_DB: "5"
+
+```env
+DATABASE_BACKEND=mssql
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
 ```
 
-Wert `5` steht für Microsoft SQL Server.
+Die backend-spezifische Compose-Override-Datei setzt anschließend die passenden Romexis-Datenbankvariablen.
 
 ### RMI Host und Ports
 
-```yaml
+```env
-SERVER_RMI_HOSTNAME: "192.168.65.177"
+SERVER_RMI_HOSTNAME=192.168.65.177
-SERVER_RMI_LOW_PORT: "1100"
+SERVER_RMI_LOW_PORT=1100
-SERVER_RMI_HIGH_PORT: "1120"
+SERVER_RMI_HIGH_PORT=1120
 ```
 
 `SERVER_RMI_HOSTNAME` muss für Romexis-Clients erreichbar sein.
 
-### Property Agent
+### PropertyAgent
 
-Der Java Property Agent kann Romexis `RxProperties` über Umgebungsvariablen setzen.
+Der Java PropertyAgent kann Romexis `RxProperties` über Umgebungsvariablen setzen.
 
 Syntax:
 
-```yaml
+```env
-PROPERTY_AGENT_SET_<RXPROPERTY_NAME>: "<Wert>"
+PROPERTY_AGENT_SET_<RXPROPERTY_NAME>=<Wert>
 ```
 
-Standardverhalten:
+Beispiel:
 
-```yaml
+```env
-PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES: "true"
+PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true
 ```
 
-Diese Einstellung ist für zuverlässiges KeyVault-Handling unter Docker/Linux erforderlich.
+Dies ist hauptsächlich für die Romexis-Server-Laufzeit relevant. Im Admin-Container ist der PropertyAgent standardmäßig deaktiviert.
 
 ---
 
 ## Troubleshooting
 
-### SQL Server prüfen
+### Effektive Compose-Konfiguration prüfen
 
 ```bash
-docker compose logs mssql
+docker compose config
 ```
 
-### Romexis prüfen
+### Alle Dienste prüfen
 
 ```bash
-docker compose logs romexis
+docker compose ps
+docker compose logs -f
 ```
 
-### SQL-Server-Verbindung testen
+### Romexis Server prüfen
 
 ```bash
-docker exec -it romexis-mssql \
+docker compose logs -f romexis
-  /opt/mssql-tools18/bin/sqlcmd \
+```
-  -C \
+
-  -S localhost \
+### Admin Container prüfen
-  -U sa \
+
-  -P 'Pwr0mex!s!!!' \
+```bash
-  -Q "SELECT 1"
+docker compose logs -f romexis-admin
+```
+
+### Shell im Admin-Service öffnen
+
+```bash
+docker compose run --rm --entrypoint /bin/bash romexis-admin
 ```
 
 ### Aufgelöste Romexis-Version prüfen
@@ -547,14 +587,7 @@ docker exec -it romexis-server cat /opt/romexis/version
 
 ### Keystore-Alias-Probleme
 
-Falls Romexis meldet:
+Falls Romexis einen fehlenden Server-Zertifikat-Alias meldet:
-
-```text
-Failed to get keystore entry by alias:
-server_certificate_...
-```
-
-ausführen:
 
 ```bash
 docker exec -it romexis-server /opt/fix-keystore-alias.sh
@@ -564,11 +597,11 @@ docker exec -it romexis-server /opt/fix-keystore-alias.sh
 
 ## Bekannte Einschränkungen
 
-- Nur Serverbetrieb wurde getestet.
+- Romexis-Binaries sind nicht Bestandteil dieses Repositorys.
-- `RomexisConfig` wird im Container nicht unterstützt.
+- Das mRomexis-WebApp-Image erfordert Romexis 6.5.3 oder neuer.
-- Microsoft SQL Server ist das primär unterstützte Datenbank-Backend.
+- Romexis Admin wird über eine browserbasierte VNC-Sitzung bereitgestellt, nicht als native Desktop-Anwendung.
-- Firebird-Clientbibliotheken sind im Base Image enthalten, die aktuelle Compose-Laufzeitumgebung fokussiert SQL Server.
+- Multiarch-Images werden gebaut und veröffentlicht; die funktionale Validierung hängt von Plattform und verfügbaren Romexis-Komponenten ab.
-- Multiarch-Images werden vom Build-Prozess unterstützt; die funktionale Validierung hängt von Plattform und verfügbaren Romexis-Komponenten ab.
+- Vor produktivem Einsatz sind Backups, Lizenzprüfung und umgebungsspezifische Tests erforderlich.
 
 ---
 
@@ -578,7 +611,7 @@ docker exec -it romexis-server /opt/fix-keystore-alias.sh
 
 Planmeca Romexis ist proprietäre Software.
 
-Dieses Repository enthält keine Romexis-Programmdateien. Der offizielle Installer wird während des Builds anhand von `romexis-versions.env` heruntergeladen.
+Dieses Repository enthält keine Romexis-Programmdateien. Der offizielle Installer wird während des Builds anhand von `romexis-payload/romexis-versions.env` heruntergeladen.
 
 ### Chilkat
 

Reference-README.md

@@ -1,227 +1,158 @@
 # Romexis Docker
 
-[English](README.md) | [Deutsch](README.de.md) | [Build process](BUILD.md) | [Developer notes](DEVELOPERS.md) | [![Build Status](https://drone.buchhorster.de/api/badges/planmeca/romexis-server-docker/status.svg?ref=refs/heads/main)]
+[Deutsch](README.de.md) | [Build process](BUILD.md) | [Developer notes](DEVELOPERS.md)
 
-> Containerized deployment of Planmeca Romexis Server 6.5 on Linux using Docker, Microsoft SQL Server and a reusable multi-architecture Romexis base image.
+> Containerized deployment of Planmeca Romexis Server on Linux with Docker, database backend selection through Docker Compose, optional migration tooling, browser-based Romexis Admin access and a separate mRomexis Web App container.
 
 ---
 
 ## Overview
 
-This project builds and runs the Planmeca Romexis Server in Docker.
+This project builds and runs Planmeca Romexis services in Docker.
 
-The build process extracts the required Romexis server files directly from the official Romexis Windows installer package. No Romexis application binaries are stored in this repository.
+Romexis application files are extracted from the official Romexis Windows installer during the build process. No Romexis binaries are stored in this repository.
 
-The current build system is split into payload, base and server image layers:
+The runtime stack is split into clearly separated services:
 
-1. **Romexis Base Image**
+- **Romexis Server**  
-   - Provides the Java 11 runtime with JavaFX support.
+  Main Romexis backend service with RMI ports, database access, KeyVault preparation and runtime configuration.
-   - Provides Microsoft SQL Server command-line tools.
-   - Provides Firebird client libraries.
-   - Is built separately for `amd64` and `arm64`.
 
-2. **Romexis Server Image**
+- **Database backend**  
-   - Uses the Romexis base image.
+  Selected through `DATABASE_BACKEND` and `COMPOSE_FILE` in `.env`. Supported Compose backends are currently `mssql` and `firebird`.
-   - Downloads and extracts the selected Romexis installer.
-   - Builds the final `/opt/romexis` directory structure.
-   - Adds the Java property agent, runtime scripts and database initialization files.
 
-This separation keeps the final image easier to maintain and allows the shared runtime base image to be reused across multiple Romexis builds.
+- **Romexis Migration Service**  
+  Optional web/API service for restoring Romexis database backups and data directories.
+
+- **Romexis Admin**  
+  Browser-accessible Admin / RomexisConfig container using Xvfb, Openbox, xcompmgr, x11vnc and noVNC.
+
+- **mRomexis Web App**  
+  Separate Tomcat-based container for the mRomexis Web frontend available in Romexis 6.5.3 and newer.
 
 ---
 
-## Features
+## Main Features
 
-- Romexis Server 6.5 in Docker
+- Romexis Server in Docker
-- Microsoft SQL Server 2022 support
+- Microsoft SQL Server and Firebird backend Compose overlays
-- Automatic database initialization
+- Runtime backend selection using `.env`
-- Persistent storage for all application data
+- Local build scripts for repeatable developer builds
-- Automatic KeyVault and ProgramData preparation
+- Multi-architecture images for `amd64` and `arm64`
-- Support for existing database volumes
+- Payload image layer for installer extraction
-- Multi-stage Docker build
+- Reusable base runtime image
-- Multi-architecture image publishing for `amd64` and `arm64`
+- Server image built from payload and base images
-- Dedicated reusable Romexis base image
+- Migration Service image
-- Mapping-based installer extraction using `romexis-copy-map.tsv`
+- Romexis Admin image with browser/noVNC access
-- Selective InstallShield CAB extraction
+- mRomexis Web App image
-- Romexis installer versions managed through `romexis-versions.env`
+- Branch-specific image suffix support through `IMAGE_SUFFIX`
-- No Windows Registry required
+- Java PropertyAgent support for server-side runtime properties
-- No RomexisConfig execution required
+- Drone CI/CD support with multi-architecture manifests
-- Linux-compatible runtime paths
-- Java property injection through `RomexisPropertyAgent`
-- CI/CD build support through Drone
 
 ---
 
-## Architecture
+## Runtime Compose Structure
+
+The runtime is split into a base Compose file and backend-specific override files:
 
 ```text
-+----------------------+
+.env.sample
-|   Romexis Clients    |
+docker-compose.yml
-+----------+-----------+
+docker-compose.mssql.yml
-           |
+docker-compose.firebird.yml
-           | RMI / Romexis protocol ports
+scripts/build-local.sh
-           v
+scripts/build-local.ps1
-+----------------------+
-|   Romexis Server     |
-|      Docker          |
-+----------+-----------+
-           |
-           | JDBC
-           v
-+----------------------+
-| Microsoft SQL Server |
-|      Docker          |
-+----------------------+
 ```
 
----
+The base file contains database-independent services such as:
-
-## Supported Platforms
-
-The build system supports the following target architectures:
-
-| Architecture | Docker platform | Tag suffix |
-|-------------|-----------------|------------|
-| x86_64      | `linux/amd64`   | `-amd64`   |
-| ARM64       | `linux/arm64`   | `-arm64`   |
-
-The Drone pipeline builds architecture-specific images and then publishes a multi-architecture manifest without an architecture suffix.
-
----
-
-## Requirements
-
-### Runtime host
-
-- Linux host
-- Docker Engine
-- Docker Compose plugin
-- Network access between Romexis clients and the published RMI ports
-
-### Build host
-
-- Docker Engine with BuildKit support
-- Docker Buildx
-- Docker Compose plugin
-- Access to the Romexis installer download URLs listed in `romexis-payload/romexis-versions.env`
-- Access to the configured container registry
-- Sufficient disk space for installer extraction and image builds
-
-### Recommended resources
-
-- 8 GB RAM
-- 4 CPU cores
-- 20 GB free disk space for runtime
-- Additional free disk space on build hosts for Docker build cache and extracted installer files
-
----
-
-## Container Images
-
-Images are published to the Gitea Container Registry namespace used by the project.
-
-### Image layout
 
 ```text
-gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64
+romexis
-gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64
+romexis-admin
-
+romexis-app
-gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
+proxy
-gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
-gitea.buchhorster.de/planmeca/romexis-server:<version>
 ```
 
-The architecture-specific tags are used internally by the multi-architecture manifest.
+The backend override files add or override database-specific services and environment values:
 
-### Example pull
+```text
+docker-compose.mssql.yml
+docker-compose.firebird.yml
+```
+
+`docker-compose.build.yml` is no longer required. Local image builds are handled by `scripts/build-local.*`.
+
+---
+
+## Backend Selection with `.env`
+
+The stack can be started with a single command by defining the selected backend in `.env`.
+
+### MSSQL
+
+```env
+DATABASE_BACKEND=mssql
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+Start:
 
 ```bash
-docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203
+docker compose up -d
 ```
 
-### Verify installed Romexis version
+### Firebird
+
+```env
+DATABASE_BACKEND=firebird
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+Start:
 
 ```bash
-docker run --rm \
+docker compose up -d
-  --entrypoint cat \
+```
-  gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203 \
+
-  /opt/romexis/version
+On native Windows shells the Compose file separator may need to be `;` instead of `:`:
+
+```env
+COMPOSE_PATH_SEPARATOR=;
+COMPOSE_FILE=docker-compose.yml;docker-compose.${DATABASE_BACKEND}.yml
+```
+
+To verify which files and values are active:
+
+```bash
+docker compose config
 ```
 
 ---
 
-## Version Handling
+## Quick Start
 
-The file `romexis-payload/romexis-versions.env` maps supported Romexis versions to official installer URLs.
+Create your runtime configuration:
-
-Example entries:
-
-```text
-6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip
-6_5_2_189_213=https://content.planmeca.com/files/Planmeca_Romexis_6.5.2.189.213_Win.zip
-```
-
-The build argument `ROMEXIS_VERSION` may contain either a full version or a prefix.
-
-Example:
 
 ```bash
-ROMEXIS_VERSION=6.5.3
+cp .env.sample .env
 ```
 
-The build resolves this to the newest matching entry, for example:
+Edit at least:
 
-```text
+```env
-6.5.3.444.203
+DATABASE_BACKEND=mssql
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+
+ROMEXIS_VERSION=6.5.3.444.203
+IMAGE_SUFFIX=
 ```
 
-The resolved version is stored inside the image:
+Start the stack:
-
-```text
-/opt/romexis/version
-```
-
----
-
-## Project Structure
-
-```text
-.
-├── docker-compose.yml
-├── docker-compose.build.yml
-├── README.md
-├── README.de.md
-├── BUILD.md
-├── BUILD.de.md
-├── DEVELOPERS.md
-│
-├── romexis-base
-│   └── Dockerfile
-│
-├── romexis
-│   ├── Dockerfile
-│   ├── entrypoint.sh
-│   ├── fix-keystore-alias.sh
-│   ├── init-romexis-db.sh
-│   ├── RomexisPropertyAgent.java
-│   ├── 
-│
-└── data
-    ├── programdata
-    ├── sconfig
-    ├── romexis_images
-    ├── romexis_cache
-    └── romexis_ergodata
-```
-
----
-
-## Runtime with pre-built images
-
-Use `docker-compose.yml` for normal runtime operation.
 
 ```bash
-ROMEXIS_VERSION=6.5.3.444.203 docker compose up -d
+docker compose up -d
 ```
 
 View logs:
@@ -230,19 +161,7 @@ View logs:
 docker compose logs -f
 ```
 
-Romexis only:
+Stop the stack:
-
-```bash
-docker compose logs -f romexis
-```
-
-SQL Server only:
-
-```bash
-docker compose logs -f mssql
-```
-
-Stop the environment:
 
 ```bash
 docker compose down
@@ -250,96 +169,238 @@ docker compose down
 
 ---
 
-## Local build with Docker Compose
+## Runtime Services
 
-Use `docker-compose.build.yml` for local builds.
+### Romexis Server
 
-The base image must be built before the Romexis Server image because the server Dockerfile uses the base image via the `ROMEXIS_BASE_IMAGE` build argument.
+The `romexis` service runs the main Romexis backend.
+
+It prepares:
+
+- Romexis server properties
+- KeyVault and ProgramData paths
+- database connection configuration
+- Linux data paths
+- RMI host and port settings
+- optional database initialization
+
+Useful logs:
 
 ```bash
-TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
+docker compose logs -f romexis
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
-TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d
 ```
 
-For an ARM64 build host:
+Check the installed Romexis version:
 
 ```bash
-TARGETARCH=arm64 docker compose -f docker-compose.build.yml --profile build build romexis-base
+docker exec -it romexis-server cat /opt/romexis/version
-TARGETARCH=arm64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
 ```
 
-Further details are documented in [BUILD.md](BUILD.md).
+### Database Backend
 
----
+The selected backend is loaded through `COMPOSE_FILE`.
 
+For MSSQL, the override file adds the SQL Server service and configures Romexis for Microsoft SQL Server.
 
----
+For Firebird, the override file adds the Firebird service and configures Romexis for Firebird.
 
-## Current Architecture Update
+Use:
 
-The project now uses three build layers instead of only base and server images:
+```bash
+docker compose ps
+docker compose logs -f
+docker compose config
+```
 
-1. **Romexis Payload Image**
+to inspect the effective runtime stack.
-   - Built from `romexis-payload/Dockerfile`.
-   - Downloads and extracts the official Romexis installer.
-   - Contains `/opt/romexis` and `/opt/romexis-mssql-db`.
-   - Is architecture-independent and tagged as `romexis-payload:<version>`.
 
-2. **Romexis Base Image**
+### Migration Service
-   - Built from `romexis-base/Dockerfile`.
-   - Contains Java, JavaFX, SQL tools and common runtime libraries.
-   - Is architecture-specific.
 
-3. **Romexis Server Image**
+The Migration Service is used for Romexis migration and restore workflows.
-   - Built from `romexis/Dockerfile`.
-   - Consumes the payload image and the base image.
-   - Adds Chilkat, the Java Property Agent, runtime scripts and startup logic.
 
-The payload split avoids repeated installer downloads and keeps the final server image build independent from the original ZIP/CAB extraction step.
+It provides:
 
----
+- web UI and REST API for migration jobs
-
+- database backup upload
-## Migration Service
+- temporary SFTP access per migration job
-
+- server-side `manifest.json` generation
-The repository now includes a Romexis Migration Service and a Windows Migration Client.
+- database restore workflow
-
-The migration service provides:
-
-- Web UI and REST API for migration jobs
-- temporary per-job SFTP credentials
-- browser-based database backup upload
-- automatic server-side `manifest.json` creation
-- SQL Server database restore
-- upload validation
 - file restore workflow
-- migration cancellation and cleanup
+- validation and cleanup
-- migration completion with SFTP access removal
 - coordinated Romexis restart through a shared state file
 
-Supported migration paths:
+The restart coordination file is:
-
-1. **Windows Migration Client**
-   - detects Romexis installation, SQL Server configuration and data directories
-   - creates or uses a database backup
-   - uploads data using rclone/SFTP
-   - communicates with the migration service API
-
-2. **Manual browser and SFTP workflow**
-   - create a migration job in the Web UI
-   - upload the database backup through the browser
-   - let the server generate the manifest
-   - upload `romexis_images`, `romexis_ergodata` and optionally `romexis_cache` via SFTP
-   - validate, restore and complete the migration
-
-The Romexis restart after restore is coordinated through:
 
 ```text
 /data/romexis_images/.romexis_restart_state
 ```
 
-The migration service writes the restart request, the Romexis entrypoint performs the restart and writes the final status back.
+### Romexis Admin
 
+The `romexis-admin` service provides Romexis Admin / RomexisConfig through noVNC.
+
+It starts the graphical runtime components with the container:
+
+```text
+Xvfb -> Openbox -> xcompmgr -> x11vnc -> noVNC
+```
+
+RomexisConfig itself can be started only when a VNC/noVNC client connects. This keeps the Admin application from running permanently in the background.
+
+Open the Admin UI:
+
+```text
+http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true
+```
+
+Typical Admin environment values:
+
+```env
+ADMIN_NOVNC_PORT=6080
+ADMIN_VNC_PORT=5900
+ADMIN_VNC_PASSWORD=promax
+ADMIN_RESOLUTION=1280x900x24
+ADMIN_JAVA_OPTS=-Xms256m -Xmx1024m
+
+ADMIN_LANGUAGE=en
+DEBUG_XTERM=false
+ADMIN_VNC_LIFECYCLE=true
+ENABLE_PROPERTY_AGENT=false
+```
+
+`ADMIN_LANGUAGE` supports:
+
+```text
+en
+de
+```
+
+The same language value is used for the startup splash screen and the RomexisConfig `language=` parameter.
+
+`DEBUG_XTERM=true` opens an additional debug terminal in the VNC session.
+
+`ADMIN_VNC_LIFECYCLE=true` means:
+
+- first VNC/noVNC client connects -> RomexisConfig starts
+- last VNC/noVNC client disconnects -> RomexisConfig stops
+- a localized splash screen is displayed during Admin startup
+
+### mRomexis Web App
+
+The `romexis-app` service serves the mRomexis Web frontend as a standalone Tomcat application.
+
+Important:
+
+```text
+mromexis-html.war is only available in Romexis 6.5.3 and newer.
+```
+
+Older payload versions do not contain the WAR file and therefore cannot build a valid mRomexis Web App image.
+
+The web application is normally exposed through the proxy service. The proxy also handles the application `/proxy?url=...` endpoint.
+
+The proxy rewrites incoming mRomexis proxy requests to the internal Romexis backend service instead of trusting the browser-supplied host. This avoids maintaining internal IP allowlists and prevents the endpoint from becoming an open HTTP proxy.
+
+Typical environment value:
+
+```env
+MROMEXIS_WEB_PORT=8081
+```
+
+Open the mRomexis Web App through the configured proxy port:
+
+```text
+http://localhost:8081/
+```
+
+---
+
+## Container Images
+
+The project uses these image families:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-payload:<version>
+
+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:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-server:<version>
+
+gitea.buchhorster.de/planmeca/romexis-migration-service:amd64
+gitea.buchhorster.de/planmeca/romexis-migration-service:arm64
+gitea.buchhorster.de/planmeca/romexis-migration-service:latest
+
+gitea.buchhorster.de/planmeca/romexis-admin:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-admin:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-admin:<version>
+gitea.buchhorster.de/planmeca/romexis-admin:latest
+
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest
+```
+
+For feature branches, `IMAGE_SUFFIX` is appended to the tag:
+
+```env
+IMAGE_SUFFIX=-feature-romexis-admin
+```
+
+Example:
+
+```text
+gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-feature-romexis-admin
+```
+
+---
+
+## Local Image Builds
+
+Local builds are handled by scripts.
+
+Linux/macOS:
+
+```bash
+chmod +x scripts/build-local.sh
+./scripts/build-local.sh all
+```
+
+Windows PowerShell:
+
+```powershell
+.\scripts\build-local.ps1 -Targets all
+```
+
+Build only selected image families:
+
+```bash
+./scripts/build-local.sh base server
+./scripts/build-local.sh admin mromexis
+./scripts/build-local.sh migration
+```
+
+Common local `.env` values:
+
+```env
+REGISTRY=gitea.buchhorster.de/planmeca
+ROMEXIS_VERSION=6.5.3.444.203
+IMAGE_SUFFIX=
+TARGETARCH=amd64
+
+ROMEXIS_IMAGE=romexis-server
+MIGRATION_IMAGE=romexis-migration-service
+ADMINISTRATION_IMAGE=romexis-admin
+MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app
+```
+
+More build details are documented in [BUILD.md](BUILD.md).
+
+---
 
 ## Persistent Data Directories
 
@@ -351,17 +412,17 @@ Mounted to:
 /opt/romexis/sconfig
 ```
 
-Contains Romexis server configuration files that should persist across container recreations.
+Contains persistent Romexis server configuration files.
 
 ### programdata
 
 Mounted to:
 
 ```text
-/programdata/Planmeca/Romexis
+/programdata/planmeca/romexis
 ```
 
-This mirrors the Windows `%ProgramData%\Planmeca\Romexis` location and contains the KeyVault and related security files.
+Mirrors the Windows `%ProgramData%\Planmeca\Romexis` location and contains KeyVault and security related files.
 
 ### romexis_images
 
@@ -397,27 +458,27 @@ Stores ergo and additional Romexis data.
 
 ## Database Initialization
 
-On first startup:
+On first startup, the server entrypoint can initialize the configured database backend.
 
-1. SQL Server starts.
+Typical first-start tasks:
-2. Romexis waits until SQL Server is healthy.
-3. The database `Romexis_db` is created if missing.
-4. The database user `romexis` is created if missing.
-5. Romexis SQL schema and update scripts are imported.
-6. Linux data paths are written to the database.
 
-Initialization is skipped when both the database and the Romexis database user already exist.
+1. Wait for the selected database backend.
+2. Create the Romexis database if missing.
+3. Create the Romexis database user if missing.
+4. Import schema and update scripts where applicable.
+5. Write Linux data paths into the database.
+6. Start the Romexis server.
 
-The initialization can be disabled:
+Disable initialization:
 
-```yaml
+```env
-ROMEXIS_INIT_DB: "0"
+ROMEXIS_INIT_DB=0
 ```
 
-Verbose SQL output can be enabled:
+Enable verbose SQL output:
 
-```yaml
+```env
-DB_CREATE_VERBOSE: "true"
+DB_CREATE_VERBOSE=true
 ```
 
 ---
@@ -430,113 +491,94 @@ Romexis expects a Windows-like `ProgramData` location. The entrypoint sets:
 ProgramData=/programdata
 ```
 
-The KeyVault path is written to `romexis_server.properties`:
+The KeyVault path is written to `romexis_server.properties`.
 
-```properties
+The entrypoint initializes missing key files from image defaults when required.
-SERVER_KEYVAULT_PATH=/programdata/Planmeca/Romexis/sconfig
-```
-
-The entrypoint initializes missing key files from the image defaults:
-
-- `static_keys_default.p12` -> `static_keys.p12`
-- `initial_keyvault.p12` -> `keyvault.p12`
 
 ---
 
-## RomexisConfig
+## RomexisConfig and Admin Configuration
 
-`RomexisConfig` is intentionally not executed.
+The server container does not run RomexisConfig during startup.
 
-Inside a Linux container, RomexisConfig may attempt to access Windows Registry functions through Advapi32/JNA. The required configuration tasks are handled directly by the Docker entrypoint instead.
+Administrative configuration is handled by the dedicated `romexis-admin` container instead. This avoids mixing the server process with a graphical configuration tool and keeps the server container focused on the backend runtime.
-
-Replaced responsibilities:
-
-- KeyVault preparation
-- ProgramData handling
-- Database configuration
-- Linux path configuration
-- Runtime property injection
 
 ---
 
 ## Advanced Configuration
 
-### Database URL
-
-By default, the entrypoint generates:
-
-```text
-jdbc:sqlserver://<host>:<port>;databaseName=<database>;encrypt=true;trustServerCertificate=true;
-```
-
-You may provide a complete JDBC URL:
-
-```yaml
-ROMEXIS_DB_URL: "jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;"
-```
-
 ### Database backend
 
-```yaml
+Backend selection is controlled at Compose level:
-SERVER_DB: "5"
+
+```env
+DATABASE_BACKEND=mssql
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
 ```
 
-Value `5` represents Microsoft SQL Server.
+The backend-specific Compose override then sets the appropriate Romexis database environment values.
 
 ### RMI host and ports
 
-```yaml
+```env
-SERVER_RMI_HOSTNAME: "192.168.65.177"
+SERVER_RMI_HOSTNAME=192.168.65.177
-SERVER_RMI_LOW_PORT: "1100"
+SERVER_RMI_LOW_PORT=1100
-SERVER_RMI_HIGH_PORT: "1120"
+SERVER_RMI_HIGH_PORT=1120
 ```
 
 `SERVER_RMI_HOSTNAME` must be reachable by Romexis clients.
 
-### Property agent
+### PropertyAgent
 
-The Java property agent can set Romexis `RxProperties` from environment variables.
+The Java PropertyAgent can set Romexis `RxProperties` from environment variables.
 
 Syntax:
 
-```yaml
+```env
-PROPERTY_AGENT_SET_<RXPROPERTY_NAME>: "<value>"
+PROPERTY_AGENT_SET_<RXPROPERTY_NAME>=<value>
 ```
 
-Default behavior:
+Example:
 
-```yaml
+```env
-PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES: "true"
+PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true
 ```
 
-This is required for reliable KeyVault handling under Docker/Linux.
+This is primarily relevant for the Romexis server runtime. In the Admin container the PropertyAgent is disabled by default.
 
 ---
 
 ## Troubleshooting
 
-### Check SQL Server
+### Inspect effective Compose configuration
 
 ```bash
-docker compose logs mssql
+docker compose config
 ```
 
-### Check Romexis
+### Check all services
 
 ```bash
-docker compose logs romexis
+docker compose ps
+docker compose logs -f
 ```
 
-### Test SQL Server connectivity
+### Check Romexis server
 
 ```bash
-docker exec -it romexis-mssql \
+docker compose logs -f romexis
-  /opt/mssql-tools18/bin/sqlcmd \
+```
-  -C \
+
-  -S localhost \
+### Check Admin container
-  -U sa \
+
-  -P 'Pwr0mex!s!!!' \
+```bash
-  -Q "SELECT 1"
+docker compose logs -f romexis-admin
+```
+
+### Open a shell in the Admin service
+
+```bash
+docker compose run --rm --entrypoint /bin/bash romexis-admin
 ```
 
 ### Check resolved Romexis version
@@ -547,14 +589,7 @@ docker exec -it romexis-server cat /opt/romexis/version
 
 ### Keystore alias issues
 
-If Romexis reports:
+If Romexis reports a missing server certificate alias, run:
-
-```text
-Failed to get keystore entry by alias:
-server_certificate_...
-```
-
-run:
 
 ```bash
 docker exec -it romexis-server /opt/fix-keystore-alias.sh
@@ -564,11 +599,11 @@ docker exec -it romexis-server /opt/fix-keystore-alias.sh
 
 ## Known Limitations
 
-- Only server operation has been tested.
+- Romexis binaries are not included in this repository.
-- `RomexisConfig` is not supported inside the container.
+- mRomexis Web App image builds require Romexis 6.5.3 or newer.
-- Microsoft SQL Server is the primary supported database backend.
+- Romexis Admin is exposed through a browser-based VNC session, not as a native desktop application.
-- Firebird client libraries are included in the base image, but the runtime Compose setup currently focuses on SQL Server.
+- Multi-architecture images are built and published, but functional validation depends on the target platform and available Romexis components.
-- Multi-architecture images are supported by the build pipeline; functional validation depends on the target platform and available Romexis components.
+- Production use requires backups, license validation and environment-specific testing.
 
 ---
 
@@ -578,7 +613,7 @@ docker exec -it romexis-server /opt/fix-keystore-alias.sh
 
 Planmeca Romexis is proprietary software.
 
-This repository does not contain any Romexis program files. The official installer is downloaded during the build process based on `romexis-versions.env`.
+This repository contains no Romexis application binaries. The official installer is downloaded during the build process based on `romexis-payload/romexis-versions.env`.
 
 ### Chilkat
 

Romexis-Admin.md

@@ -0,0 +1,172 @@
+# Romexis Admin
+
+The `romexis-admin` service provides browser-based access to Romexis Admin / RomexisConfig.
+
+It is separated from the Romexis server container so the server process can stay focused on the backend runtime while administrative configuration is handled through a dedicated graphical container.
+
+---
+
+## Runtime Components
+
+The Admin container starts the graphical runtime environment with:
+
+```text
+Xvfb
+Openbox
+xcompmgr
+x11vnc
+noVNC / websockify
+```
+
+Openbox and xcompmgr are required because Romexis Admin uses Swing/AWT dialogs with opacity and translucency features.
+
+The Openbox root desktop context menu is disabled in the startup script, because it is not useful in the noVNC runtime.
+
+---
+
+## Access
+
+Open the Admin UI through noVNC:
+
+```text
+http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true
+```
+
+If `ADMIN_NOVNC_PORT` is changed, adjust the port accordingly.
+
+---
+
+## VNC Lifecycle Mode
+
+When enabled, RomexisConfig is started only when a VNC/noVNC client connects.
+
+```env
+ADMIN_VNC_LIFECYCLE=true
+```
+
+Behavior:
+
+```text
+first VNC client connects -> start RomexisConfig
+last VNC client disconnects -> stop RomexisConfig after a short grace period
+```
+
+If the user closes RomexisConfig manually while the VNC session is still connected, it is not restarted until the next VNC connection session.
+
+When disabled:
+
+```env
+ADMIN_VNC_LIFECYCLE=false
+```
+
+RomexisConfig starts immediately with the container.
+
+---
+
+## Localized Splash Screen
+
+In VNC lifecycle mode, a small splash screen is shown when the VNC session starts and RomexisConfig is launching.
+
+The language is controlled through:
+
+```env
+ADMIN_LANGUAGE=de
+```
+
+Supported values:
+
+```text
+de
+en
+```
+
+The same variable is passed to RomexisConfig as the `language=` startup parameter.
+
+---
+
+## Debug xterm
+
+A debug xterm can be started inside the VNC session:
+
+```env
+DEBUG_XTERM=true
+```
+
+Default:
+
+```env
+DEBUG_XTERM=false
+```
+
+This is useful for inspecting the runtime display environment without changing the container entrypoint.
+
+---
+
+## Typical Compose Settings
+
+```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 in Admin
+
+The Romexis PropertyAgent is disabled by default for the Admin container:
+
+```env
+ENABLE_PROPERTY_AGENT=false
+```
+
+Reason: `RxProperties` is not always visible during the Java agent `premain` phase when RomexisConfig is started. The server container still uses the PropertyAgent for server-side runtime property injection.
+
+---
+
+## Logs and Debugging
+
+Show logs:
+
+```bash
+docker compose logs -f romexis-admin
+```
+
+Open a shell in the Admin image:
+
+```bash
+docker compose run --rm --entrypoint /bin/bash romexis-admin
+```
+
+If a stopped container has to be inspected:
+
+```bash
+docker cp romexis-admin:/opt/romexis/admin ./admin-debug
+```
+
+---
+
+## Important Runtime Dependencies
+
+The Admin image requires packages such as:
+
+```text
+xvfb
+openbox
+xcompmgr
+x11vnc
+x11-utils
+novnc
+websockify
+openjfx
+libopenjfx-java
+libopenjfx-jni
+```
+
+`x11-utils` provides `xmessage`, which is used for the splash screen.

Runtime-Layout.md

@@ -11,21 +11,51 @@ Recommended persistent root:
 Typical directories:
 
 ```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
 ```
 
 ---
 
+## Runtime Services
+
+```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.
+```
+
+---
+
 ## Romexis Container Paths
 
 ```text
 /opt/romexis
 /opt/romexis/server
 /opt/romexis/sconfig
-/opt/romexis/programdata
+/programdata/planmeca/romexis
 
 /data/romexis_images
 /data/romexis_ergodata
@@ -34,6 +64,34 @@ Typical directories:
 
 ---
 
+## Admin Container Paths
+
+```text
+/opt/romexis/admin
+/opt/romexis/client
+/opt/romexis/sconfig
+/programdata/Planmeca/Romexis/Admin
+/tmp/romexis-admin-vnc-state
+```
+
+The Admin container provides browser access through noVNC and uses VNC state files to start or stop RomexisConfig based on active sessions.
+
+---
+
+## mRomexis Web App Paths
+
+```text
+/usr/local/tomcat/webapps/ROOT.war
+```
+
+The WAR originates from the Romexis payload:
+
+```text
+/opt/romexis/broker/mromexis-html.war
+```
+
+---
+
 ## Database Paths
 
 ### MSSQL
@@ -70,3 +128,9 @@ Used by migration restore coordination:
 /opt/init-romexis-firebird-db.sh
 /opt/fix-keystore-alias.sh
 ```
+
+Admin startup script:
+
+```text
+/usr/local/bin/start.sh
+```

Server-Image.md

@@ -6,7 +6,7 @@ Directory:
 romexis/
 ```
 
-The final Romexis Server image combines the prepared payload, runtime base image and runtime scripts.
+The final Romexis Server image combines the prepared payload, runtime base image, Firebird payload and runtime scripts.
 
 ---
 
@@ -18,6 +18,7 @@ ROMEXIS_PAYLOAD_IMAGE
 ROMEXIS_FIREBIRD_PAYLOAD_IMAGE
 ROMEXIS_VERSION
 TARGETARCH
+IMAGE_SUFFIX
 CHILKAT_VERSION
 ```
 
@@ -26,10 +27,11 @@ Example defaults:
 ```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}
+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}
+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
+ARG ROMEXIS_FIREBIRD_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest${IMAGE_SUFFIX}
 ```
 
 ---
@@ -61,7 +63,6 @@ The final image includes:
 /opt/init-romexis-db.sh
 /opt/init-romexis-mssql-db.sh
 /opt/init-romexis-firebird-db.sh
-/opt/init-romexis-db.sh
 /opt/fix-keystore-alias.sh
 ```
 

Source-README-References.md

@@ -4,9 +4,10 @@ These source documents were used as the basis for the wiki package.
 
 - [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)
-- [README.de](Reference-README.de)
-- [README](Reference-README)

Troubleshooting.md

@@ -1,29 +1,59 @@
 # Troubleshooting
 
+## Inspect effective Compose configuration
+
+Because the active backend is selected through `.env`, start with:
+
+```bash
+docker compose config
+```
+
+Check that the expected backend override was loaded.
+
+---
+
+## Wrong database backend starts
+
+Check `.env`:
+
+```env
+DATABASE_BACKEND=mssql
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+or:
+
+```env
+DATABASE_BACKEND=firebird
+COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
+```
+
+Then inspect the running container environment:
+
+```bash
+docker compose exec romexis env | grep -E 'SERVER_DB|ROMEXIS_DB|MSSQL|FIREBIRD'
+```
+
+Expected backend identifiers:
+
+```text
+SERVER_DB=5  # MSSQL
+SERVER_DB=4  # Firebird
+```
+
+---
+
 ## Firebird mode still starts MSSQL initialization
 
+If `SERVER_DB` is missing, the entrypoint may default to MSSQL.
+
 Check:
 
 ```bash
-docker exec -it romexis-server env | grep -E 'SERVER_DB|ROMEXIS_DB|FIREBIRD'
+docker compose exec romexis env | grep SERVER_DB
 ```
 
-Expected Firebird values:
+The Firebird Compose override must set:
-
-```text
-SERVER_DB=4
-ROMEXIS_DB_URL=jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb
-ROMEXIS_DB_USER=sysdba
-ROMEXIS_DB_PASSWORD=pwr0mex!
-```
-
-If `SERVER_DB` is missing, the entrypoint may default to MSSQL:
-
-```bash
-SERVER_DB="${SERVER_DB:-5}"
-```
-
-Set:
 
 ```env
 SERVER_DB=4
@@ -38,28 +68,16 @@ This means the old MSSQL init script is still being executed or old script conte
 Check inside the Romexis container:
 
 ```bash
-cat /opt/init-romexis-db.sh
+docker compose exec romexis cat /opt/init-romexis-db.sh
-ls -lah /opt/init-romexis-*
+docker compose exec romexis ls -lah /opt/init-romexis-*
 ```
 
-The wrapper must not contain:
+Rebuild and recreate:
-
-```bash
-MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:?MSSQL_SA_PASSWORD is required}"
-```
-
-That belongs only in:
-
-```text
-/opt/init-romexis-mssql-db.sh
-```
-
-Rebuild without cache:
 
 ```bash
 docker buildx prune -a -f
-docker compose build --no-cache --pull
+./scripts/build-local.sh server
-docker compose up --force-recreate
+docker compose up -d --force-recreate
 ```
 
 ---
@@ -80,69 +98,87 @@ Use:
 isql-fb
 ```
 
-Set:
+or set:
 
 ```bash
 export ISQL=isql-fb
 ```
 
-Or change the init script default:
+---
+
+## Admin container does not start RomexisConfig
+
+Check logs:
 
 ```bash
-ISQL="${ISQL:-isql-fb}"
+docker compose logs -f romexis-admin
 ```
 
----
+If `ADMIN_VNC_LIFECYCLE=true`, RomexisConfig starts only after a VNC/noVNC client connects.
 
-## Firebird database file already exists
+Open:
-
-If the Firebird container creates the database using:
-
-```yaml
-FIREBIRD_DATABASE: "romexis.fdb"
-```
-
-then the Romexis init script should not run `CREATE DATABASE` again.
-
-It should connect to the existing empty database and import the SQL scripts.
-
----
-
-## Firebird SYSDBA duplicate key error
-
-Error:
 
 ```text
-violation of PRIMARY or UNIQUE KEY constraint
+http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true
-PLG$USER_NAME = 'SYSDBA'
-```
-
-Cause:
-
-The Firebird container was instructed to create `SYSDBA` again.
-
-Remove user creation variables from the Firebird service and keep only:
-
-```yaml
-environment:
-  ISC_PASSWORD: "${FIREBIRD_PASSWORD}"
-  FIREBIRD_DATABASE: "romexis.fdb"
 ```
 
 ---
 
-## Payload latest tag not found
+## Admin JavaFX or translucency errors
 
-Error:
+Romexis Admin requires Openbox and xcompmgr.
+
+The Admin image should include:
 
 ```text
-romexis-firebird-payload:latest: not found
+openbox
+xcompmgr
+x11-utils
+openjfx
+libopenjfx-java
+libopenjfx-jni
 ```
 
-Fix the Firebird payload CI build to push:
+Errors such as `TRANSLUCENT translucency is not supported` usually mean the compositor is missing or not running.
+
+---
+
+## Admin splash screen is not shown
+
+The splash screen uses `xmessage` from `x11-utils`.
+
+Check:
 
 ```bash
--t "$FIREBIRD_PAYLOAD_IMAGE:latest"
+docker compose run --rm --entrypoint which romexis-admin xmessage
+```
+
+---
+
+## mRomexis Web App build fails because WAR is missing
+
+`mromexis-html.war` exists only in Romexis 6.5.3 and newer.
+
+Check the payload:
+
+```bash
+docker run --rm --entrypoint find   gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203   /opt/romexis -name 'mromexis-html.war'
+```
+
+---
+
+## mRomexis Web App backend calls fail
+
+Check proxy logs:
+
+```bash
+docker compose logs -f proxy
+```
+
+Check Romexis backend reachability from the proxy container:
+
+```bash
+docker compose exec proxy wget -O- http://romexis:8093/ || true
 ```
 
 ---
@@ -155,32 +191,36 @@ Clean local build cache:
 docker buildx prune -a -f
 ```
 
-Then rebuild with:
+Then rebuild with the local script:
 
 ```bash
-docker compose build --no-cache --pull
+./scripts/build-local.sh all
 ```
 
-In CI, also check whether the build is skipped because the image already exists in the registry.
+Recreate the runtime stack:
+
+```bash
+docker compose up -d --force-recreate
+```
 
 ---
 
 ## Start container with bash for debugging
 
-In Compose:
+Romexis server:
-
-```yaml
-entrypoint:
-  - /bin/bash
-  - -c
-  - sleep infinity
-
-stdin_open: true
-tty: true
-```
-
-Then:
 
 ```bash
 docker compose exec romexis bash
 ```
+
+Admin image shell:
+
+```bash
+docker compose run --rm --entrypoint /bin/bash romexis-admin
+```
+
+mRomexis Web App image shell:
+
+```bash
+docker compose run --rm --entrypoint /bin/bash romexis-app
+```

_Sidebar.md

@@ -7,11 +7,21 @@
 - [Architecture](Architecture)
 - [Quick Start](Quick-Start)
 - [Use with Docker + WSL in Windows](Docker-Desktop-WSL-Windows)
+- [Compose Runtime](Compose-Runtime)
 - [Configuration](Configuration)
 - [Container Images](Container-Images)
 
+## Runtime Services
+- [Romexis Admin](Romexis-Admin)
+- [mRomexis Web App](mRomexis-WebApp)
+- [Runtime Layout](Runtime-Layout)
+- [Backup and Restore](Backup-and-Restore)
+- [Troubleshooting](Troubleshooting)
+- [Security](Security)
+
 ## Build System
 - [Build System](Build-System)
+- [Local Build Scripts](Local-Build-Scripts)
 - [Payload Images](Payload-Images)
 - [Base Image](Base-Image)
 - [Server Image](Server-Image)
@@ -27,12 +37,6 @@
 - [Migration Workflow](Migration-Workflow)
 - [Migration Client](Migration-Client)
 
-## Operations
-- [Runtime Layout](Runtime-Layout)
-- [Backup and Restore](Backup-and-Restore)
-- [Troubleshooting](Troubleshooting)
-- [Security](Security)
-
 ## Development
 - [Developer Guide](Developer-Guide)
 - [Java Property Agent](Java-Property-Agent)

mRomexis-WebApp.md

@@ -0,0 +1,121 @@
+# mRomexis Web App
+
+The `romexis-app` service provides the Planmeca mRomexis Web frontend as a separate container.
+
+The web application is served by Tomcat and is kept separate from the Romexis server container.
+
+---
+
+## Version Requirement
+
+The mRomexis Web App WAR file is available only in Romexis 6.5.3 and newer.
+
+Expected payload path:
+
+```text
+/opt/romexis/broker/mromexis-html.war
+```
+
+During the image build, this WAR is copied into Tomcat as:
+
+```text
+/usr/local/tomcat/webapps/ROOT.war
+```
+
+Older Romexis payload versions do not contain the WAR file and therefore cannot build a valid mRomexis Web App image.
+
+---
+
+## Runtime Services
+
+```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.
+```
+
+---
+
+## Access
+
+Open the mRomexis Web App through the configured proxy port:
+
+```text
+http://localhost:8081
+```
+
+If `MROMEXIS_WEB_PORT` is changed, adjust the port accordingly.
+
+---
+
+## Proxy Behavior
+
+The proxy handles requests from the web app and rewrites mRomexis backend proxy calls to the internal Romexis service.
+
+The proxy does not trust the browser-supplied host from `/proxy?url=...`.
+
+Instead, it extracts only the path and query string and forwards the request to:
+
+```text
+http://romexis:8093
+```
+
+This avoids maintaining internal IP addresses and prevents the endpoint from becoming an open HTTP proxy.
+
+---
+
+## Image Tags
+
+```text
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-amd64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-arm64
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>
+gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest
+```
+
+---
+
+## Local Build
+
+Build through the local helper script:
+
+```bash
+./scripts/build-local.sh mromexis
+```
+
+Or manually:
+
+```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
+```
+
+---
+
+## Troubleshooting
+
+### WAR file not found
+
+If the build fails while copying `mromexis-html.war`, verify that the selected Romexis payload version is 6.5.3 or newer.
+
+```bash
+docker run --rm --entrypoint find   gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203   /opt/romexis -name 'mromexis-html.war'
+```
+
+### Web app starts but backend calls fail
+
+Check the proxy logs:
+
+```bash
+docker compose logs -f proxy
+```
+
+Check that the Romexis backend service is reachable internally:
+
+```bash
+docker compose exec proxy wget -O- http://romexis:8093/ || true
+```