Planmeca/romexis-server-docker
Private
Public Access
5
1
Packages Wiki

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
patrick
2026-07-04 18:07:17 +00:00
parent 08cccb5dd7
commit 9d9916d934
36 changed files with 5858 additions and 4353 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Architecture.md
+123 -116
@@ -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 |
+----------+-----------+
|
| RMI / Romexis protocol ports
v
+----------------------+
| Romexis Server |
| Docker Container |
+----------+-----------+
+----------------------+ +----------------------+
| Romexis Clients | | Browser / noVNC User |
+----------+-----------+ +----------+-----------+
| |
| RMI / Romexis ports | HTTP / WebSocket
v v
+----------------------+ +----------------------+
| Romexis Server | | Romexis Admin |
| Docker Container | | noVNC Container |
+----------+-----------+ +----------------------+
|
| JDBC
v
@@ -24,19 +26,19 @@ Default Microsoft SQL Server mode:
+----------------------+
```
Firebird mode:
### Firebird mode
```text
+----------------------+
| Romexis Clients |
+----------+-----------+
|
| RMI / Romexis protocol ports
v
+----------------------+
| Romexis Server |
| Docker Container |
+----------+-----------+
+----------------------+ +----------------------+
| Romexis Clients | | Browser / noVNC User |
+----------+-----------+ +----------+-----------+
| |
| RMI / Romexis ports | HTTP / WebSocket
v v
+----------------------+ +----------------------+
| Romexis Server | | Romexis Admin |
| 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
/opt/romexis/version
romexis-firebird-payload:latest
/opt/romexis-firebird-db
Firebird SQL scripts
Firebird backup/restore helpers
romexis_new.fdb template/reference
|
+--> romexis-server:<version>
|
+--> romexis-admin:<version>
|
+--> romexis-mromexis-app:<version>
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
|-- generate database URL if needed
|-- write Romexis configuration
|-- run /opt/init-romexis-db.sh
| |
| |-- route to MSSQL init if SERVER_DB=5
| |-- route to Firebird init if SERVER_DB=4
+--> romexis-server:<version>-<arch>
romexis-firebird-payload:latest
|
|-- fix keystore alias
|-- start Romexis Server
+--> romexis-server:<version>-<arch>
```
---
## Database Initialization Router
The runtime uses a small router script:
## Compose Architecture
```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
SERVER_DB
/srv/romexis-data/
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
/opt/init-romexis-firebird-db.sh
Xvfb
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
+93 -17
@@ -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
```
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
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 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
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
Feature branches use `IMAGE_SUFFIX`:
```env
IMAGE_SUFFIX=-feature-romexis-admin
```
Runtime Compose image references then resolve to branch-specific manifests.
---
## Docker Cache Cleanup
CI-CD-Pipeline.md
+64 -9
@@ -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
migration-service
romexis-admin:<version>-amd64
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
-t "$FIREBIRD_PAYLOAD_IMAGE:latest"
```
Check the Romexis version. mRomexis Web App is built only for 6.5.3 and newer.
### Payload missing from final image
Check the final image:
```bash
docker run --rm --entrypoint find \
gitea.buchhorster.de/planmeca/romexis-server:<tag> \
/opt -maxdepth 3 -type f
docker run --rm --entrypoint find gitea.buchhorster.de/planmeca/romexis-server:<tag> /opt -maxdepth 3 -type f
```
Compose-Runtime.md
+180
@@ -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
+107 -30
@@ -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
REGISTRY=gitea.buchhorster.de/patrick
ROMEXIS_IMAGE=romexis-server
IMAGE_SUFFIX=
DATABASE_BACKEND=mssql
COMPOSE_PATH_SEPARATOR=:
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
HOST_IP=192.168.65.177
ROMEXIS_DATA_ROOT=/srv/romexis-data
```
---
## 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 |
|---|---|
| `5` | Microsoft SQL Server |
| `4` | Firebird |
### MSSQL
```env
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
SERVER_RMI_HIGH_PORT=1120
PROPERTY_AGENT_SET_<RXPROPERTY_NAME>=<value>
```
These ports must be reachable from Romexis clients.
---
## 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.
This is primarily relevant for the Romexis server runtime. In the Admin container the PropertyAgent is disabled by default.
Container-Images.md
+100 -33
@@ -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:
```text
romexis-base-jre:11-amd64
romexis-base-jre:11-arm64
```
### Windows payload image
The Windows payload image is versioned by Romexis version:
The Windows payload image is versioned by Romexis version and is architecture-independent:
```text
romexis-payload:6.5.3.444.203
```
It is architecture-independent.
### Base image
### Firebird payload image
The Firebird payload contains the currently maintained Firebird SQL payload and is consumed as a shared image:
Base images are architecture-specific and also published as a manifest:
```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
```
---
## Local Tagging
If Docker Compose expects a registry image but you built locally, tag it accordingly:
Admin image:
```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
+63 -11
@@ -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
+48 -14
@@ -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 |
| [Build System](Build-System) | Payload, base and server build workflow |
| [Database Backends](Database-Backends) | MSSQL and Firebird database architecture |
| [Container Images](Container-Images) | Registry images, tags, manifests and branch suffixes |
| [Romexis Admin](Romexis-Admin) | Browser-based RomexisConfig/Admin container via noVNC |
| [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/
Contains extended project documentation.
scripts/
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)
4. [Configuration](Configuration)
5. [Database Backends](Database-Backends)
6. [Migration Service](Migration-Service)
7. [Build System](Build-System)
8. [Developer Guide](Developer-Guide)
3. [Compose Runtime](Compose-Runtime)
4. [Quick Start](Quick-Start)
5. [Configuration](Configuration)
6. [Romexis Admin](Romexis-Admin)
7. [mRomexis Web App](mRomexis-WebApp)
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
+122
@@ -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
+69 -22
@@ -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
Combines payload + base + runtime scripts + Java agent.
Service images
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
- Firebird backend preparation
- Microsoft SQL Server 2022 backend
- 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/
Extended documentation.
scripts/
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
+53 -14
@@ -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
│ ├── DEVELOPERS.md
│ ├── MIGRATION_README.md
│ └── MIGRATION_WORKFLOW.md
├── BUILD.md
├── BUILD.de.md
├── DEVELOPERS.md
├── scripts/
│ ├── 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:
```text
docs/
```
The wiki can then provide a navigable, user-facing documentation layer.
The wiki provides a navigable user-facing documentation layer.
Quick-Start.md
+117 -79
@@ -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
docker compose -f docker-compose.firebird.yml up -d
```text
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
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:
Romexis server:
```bash
docker compose exec romexis bash
```
---
## 6. Check database initialization
Inside the Romexis container:
Admin image shell:
```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
```
For Firebird debugging:
```bash
ISQL=isql-fb DB_CREATE_VERBOSE=1 bash -x /opt/init-romexis-firebird-db.sh
docker compose run --rm --entrypoint /bin/bash romexis-app
```
---
## 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
+311 -213
@@ -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
- Microsoft SQL Server Kommandozeilenwerkzeuge
- Firebird-Clienttools und Bibliotheken
- gemeinsame Betriebssystem-Laufzeitbibliotheken
Enthält gemeinsame Server-Laufzeitabhängigkeiten wie Java, JavaFX/OpenJFX-Unterstützung, SQL-Werkzeuge, Firebird-Clientbibliotheken und gemeinsame Betriebssystembibliotheken.
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
- Romexis-Datenbank-SQL-Skripte
- native Chilkat-Laufzeitbibliothek
- Romexis Java Property Agent
- Runtime-Hilfsskripte
- Entrypoint- und Initialisierungslogik
Verwendet:
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 |
|---------|--------------|
| `TARGETARCH` | Zielarchitektur, normalerweise `amd64` oder `arm64`. |
| `ROMEXIS_VERSION` | Angeforderte Romexis-Version oder Versionspräfix. |
Tags:
### 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 |
|---------|--------------|
| `IMAGE_VERSION` | OCI-Image-Label-Version des Base Images. |
### Romexis Admin Image
### Server-Image-Argumente
Gebaut aus:
| Argument | Beschreibung |
|---------|--------------|
| `ROMEXIS_BASE_IMAGE` | Basisimage-Referenz für die finale Romexis-Server-Stage. |
| `CHILKAT_VERSION` | Version der nativen Chilkat-Bibliothek. |
```text
romexis-admin/Dockerfile
```
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
ROMEXIS_VERSION=6.5.3
```env
ROMEXIS_VERSION=6.5.3.444.203
```
Das Dockerfile löst den neuesten passenden Eintrag auf und schreibt die tatsächlich verwendete Version nach:
```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.
Die CI-Pipeline iteriert über diese Datei und baut die benötigten Image-Familien für die verfügbaren Versionen.
---
## 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:
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:
Lokale Builds werden ausgeführt über:
```text
romexis-payload/romexis-copy-map.tsv
scripts/build-local.sh
scripts/build-local.ps1
```
ist die zentrale Zuordnung zwischen Installer-Komponenten und Zielverzeichnissen.
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
### Linux/macOS
```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
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
```powershell
.\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
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build --no-cache romexis-base
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build --no-cache romexis
```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
```
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>
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
version >= 6.5.3
```
Ä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.
2. `romexis-server:<version>-amd64` bauen und veröffentlichen.
3. `romexis-base-jre:11-arm64` bauen und veröffentlichen.
4. `romexis-server:<version>-arm64` bauen und veröffentlichen.
5. Multiarch-Manifest erstellen und veröffentlichen.
```text
<image>:<version>-amd64
<image>:<version>-arm64
```
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
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d
Für `main` bleibt `IMAGE_SUFFIX` leer:
```env
IMAGE_SUFFIX=
```
Für CI:
Für Feature-Branches wird ein Branch-Suffix verwendet:
```text
base amd64 -> server amd64 -> base arm64 -> server arm64 -> manifest
```env
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:
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.
```text
/usr/local/tomcat/webapps/ROOT.war
```
Reference-BUILD.md
+313 -215
@@ -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
- Microsoft SQL Server command-line tools
- Firebird client tools and libraries
- common operating system runtime libraries
Contains shared server runtime dependencies such as Java, JavaFX/OpenJFX support, SQL tooling, Firebird client libraries and common OS 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
- Romexis database SQL scripts
- native Chilkat runtime library
- Romexis Java property agent
- runtime helper scripts
- entrypoint and initialization logic
Consumes:
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 |
|---------|-------------|
| `TARGETARCH` | Target architecture, usually `amd64` or `arm64`. |
| `ROMEXIS_VERSION` | Requested Romexis version or version prefix. |
Tags:
### 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 |
|---------|-------------|
| `IMAGE_VERSION` | OCI image label version for the base image. |
### Romexis Admin Image
### Server image arguments
Built from:
| Argument | Description |
|---------|-------------|
| `ROMEXIS_BASE_IMAGE` | Base image reference used by the final Romexis Server stage. |
| `CHILKAT_VERSION` | Native Chilkat library version. |
```text
romexis-admin/Dockerfile
```
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
ROMEXIS_VERSION=6.5.3
```env
ROMEXIS_VERSION=6.5.3.444.203
```
The Dockerfile resolves the newest matching entry and writes the resolved version to:
```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.
The CI pipeline iterates over this file and builds the required image families for the available versions.
---
## 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:
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:
Local builds are handled by:
```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.
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
### Linux/macOS
```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
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
```powershell
.\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
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build --no-cache romexis-base
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build --no-cache romexis
```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
```
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
```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:
### Server Image
```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>
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
version >= 6.5.3
```
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`.
2. Build and push `romexis-server:<version>-amd64`.
3. Build and push `romexis-base-jre:11-arm64`.
4. Build and push `romexis-server:<version>-arm64`.
5. Create and push the multi-architecture manifest.
```text
<image>:<version>-amd64
<image>:<version>-arm64
```
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
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d
For `main`, `IMAGE_SUFFIX` is empty:
```env
IMAGE_SUFFIX=
```
For CI:
For feature branches, use a branch suffix:
```text
base amd64 -> server amd64 -> base arm64 -> server arm64 -> manifest
```env
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:
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.
```text
/usr/local/tomcat/webapps/ROOT.war
```
Reference-README-compose.md
+44
@@ -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
+373 -340
@@ -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**
- Stellt Java 11 mit JavaFX-Unterstützung bereit.
- Enthält Microsoft SQL Server Kommandozeilenwerkzeuge.
- Enthält Firebird-Clientbibliotheken.
- Wird separat für `amd64` und `arm64` gebaut.
- **Romexis Server**
Hauptdienst mit RMI-Ports, Datenbankzugriff, KeyVault-Vorbereitung und Laufzeitkonfiguration.
2. **Romexis Server Image**
- Baut auf dem Romexis Base Image auf.
- Lädt und extrahiert den ausgewählten Romexis-Installer.
- Erstellt die finale `/opt/romexis`-Verzeichnisstruktur.
- Fügt Java Property Agent, Laufzeitskripte und Datenbankinitialisierung hinzu.
- **Datenbank-Backend**
Auswahl über `DATABASE_BACKEND` und `COMPOSE_FILE` in der `.env`. Unterstützte Compose-Backends sind aktuell `mssql` und `firebird`.
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
- Microsoft SQL Server 2022 Unterstützung
- Automatische Datenbankinitialisierung
- Persistente Speicherung aller Nutzdaten
- Automatische Vorbereitung von KeyVault und ProgramData
- Unterstützung vorhandener Datenbank-Volumes
- Multi-Stage Docker Build
- Multiarch-Image-Publishing für `amd64` und `arm64`
- Dediziertes wiederverwendbares Romexis Base Image
- Mapping-basierte Installer-Extraktion über `romexis-copy-map.tsv`
- Selektive InstallShield-CAB-Extraktion
- Romexis-Installerversionen werden über `romexis-versions.env` verwaltet
- Keine Windows Registry erforderlich
- Kein RomexisConfig-Aufruf erforderlich
- Linux-kompatible Laufzeitpfade
- Java-Property-Injection über `RomexisPropertyAgent`
- CI/CD Build-Unterstützung über Drone
- Romexis Server in Docker
- Microsoft SQL Server und Firebird als Compose-Backends
- Backend-Auswahl über `.env`
- Lokale Build-Skripte für reproduzierbare Entwickler-Builds
- Multiarch-Images für `amd64` und `arm64`
- Payload-Image für Installer-Extraktion
- Wiederverwendbares Base-Runtime-Image
- Server-Image aus Payload- und Base-Image
- Migration-Service-Image
- Romexis-Admin-Image mit Browser/noVNC-Zugriff
- mRomexis-WebApp-Image
- Branch-spezifische Image-Suffixe über `IMAGE_SUFFIX`
- Java PropertyAgent für serverseitige Runtime-Properties
- Drone CI/CD mit Multiarch-Manifesten
---
## Architektur
## Runtime-Compose-Struktur
Die Laufzeitumgebung ist in eine Basis-Compose-Datei und backend-spezifische Override-Dateien aufgeteilt:
```text
+----------------------+
| Romexis Clients |
+----------+-----------+
|
| RMI / Romexis-Protokollports
v
+----------------------+
| Romexis Server |
| Docker |
+----------+-----------+
|
| JDBC
v
+----------------------+
| Microsoft SQL Server |
| Docker |
+----------------------+
.env.sample
docker-compose.yml
docker-compose.mssql.yml
docker-compose.firebird.yml
scripts/build-local.sh
scripts/build-local.ps1
```
---
## 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
Die Basisdatei enthält datenbankunabhängige Dienste wie:
```text
gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64
gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64
gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-server:<version>
romexis
romexis-admin
romexis-app
proxy
```
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 \
--entrypoint cat \
gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203 \
/opt/romexis/version
docker compose up -d
```
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.
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:
Runtime-Konfiguration erstellen:
```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
6.5.3.444.203
```env
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:
```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.
Stack starten:
```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:
```bash
docker compose logs -f romexis
```
Nur SQL Server:
```bash
docker compose logs -f mssql
```
Umgebung stoppen:
Stack 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
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
docker compose logs -f romexis
```
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
TARGETARCH=arm64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
docker exec -it romexis-server cat /opt/romexis/version
```
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**
- 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
### Migration Service
2. **Romexis Base Image**
- wird aus `romexis-base/Dockerfile` gebaut
- enthält Java, JavaFX, SQL-Tools und gemeinsame Runtime-Bibliotheken
- ist architekturspezifisch
Der Migration Service unterstützt Romexis-Migrationen und Restore-Workflows.
3. **Romexis Server Image**
- wird aus `romexis/Dockerfile` gebaut
- verwendet Payload Image und Base Image
- ergänzt Chilkat, Java Property Agent, Laufzeitskripte und Startlogik
Durch das Payload Image müssen Installer-ZIP und CAB-Dateien nicht bei jedem Server-Build erneut heruntergeladen und extrahiert werden.
---
## Migration Service
Das Repository enthält jetzt einen Romexis Migration Service und einen Windows Migration Client.
Der Migration Service stellt bereit:
Er stellt bereit:
- Web UI und REST API für Migrationsjobs
- temporäre SFTP-Zugangsdaten pro Job
- Datenbankbackup-Upload über den Browser
- automatische serverseitige `manifest.json`-Erzeugung
- SQL Server Datenbank-Restore
- Upload-Validierung
- Datei-Restore-Workflow
- Abbruch und Bereinigung von Migrationen
- Abschluss einer Migration mit Entfernung des SFTP-Zugangs
- Datenbankbackup-Upload
- temporären SFTP-Zugang pro Migrationsjob
- serverseitige `manifest.json`-Erzeugung
- Datenbank-Restore
- Datei-Restore
- Validierung und Bereinigung
- koordinierten Romexis-Neustart über eine gemeinsame State-Datei
Unterstützte Migrationswege:
1. **Windows Migration Client**
- erkennt Romexis-Installation, SQL-Server-Konfiguration und Datenverzeichnisse
- erstellt oder nutzt ein Datenbankbackup
- lädt Daten per rclone/SFTP hoch
- kommuniziert mit der Migration Service API
2. **Manueller Browser- und SFTP-Workflow**
- Migrationsjob im Web UI erstellen
- Datenbankbackup über den Browser hochladen
- Manifest vom Server erzeugen lassen
- `romexis_images`, `romexis_ergodata` und optional `romexis_cache` per SFTP hochladen
- validieren, wiederherstellen und Migration abschließen
Der Romexis-Neustart nach dem Restore wird über folgende Datei koordiniert:
Die Neustartkoordination erfolgt über:
```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.
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.
Typische Aufgaben beim ersten Start:
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
ROMEXIS_INIT_DB: "0"
```env
ROMEXIS_INIT_DB=0
```
Ausführliche SQL-Ausgabe:
Ausführliche SQL-Ausgabe aktivieren:
```yaml
DB_CREATE_VERBOSE: "true"
```env
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
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`
Fehlende Schlüsseldateien werden bei Bedarf aus den im Image enthaltenen Defaults initialisiert.
---
## 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.
Ersetzte Aufgaben:
- KeyVault-Vorbereitung
- ProgramData-Handling
- Datenbankkonfiguration
- Linux-Pfadkonfiguration
- Runtime-Property-Injection
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.
---
## 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
SERVER_DB: "5"
Die Backend-Auswahl erfolgt auf Compose-Ebene:
```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
SERVER_RMI_HOSTNAME: "192.168.65.177"
SERVER_RMI_LOW_PORT: "1100"
SERVER_RMI_HIGH_PORT: "1120"
```env
SERVER_RMI_HOSTNAME=192.168.65.177
SERVER_RMI_LOW_PORT=1100
SERVER_RMI_HIGH_PORT=1120
```
`SERVER_RMI_HOSTNAME` muss für Romexis-Clients erreichbar sein.
### Property Agent
### PropertyAgent
Der Java Property Agent kann Romexis `RxProperties` über Umgebungsvariablen setzen.
Der Java PropertyAgent kann Romexis `RxProperties` über Umgebungsvariablen setzen.
Syntax:
```yaml
PROPERTY_AGENT_SET_<RXPROPERTY_NAME>: "<Wert>"
```env
PROPERTY_AGENT_SET_<RXPROPERTY_NAME>=<Wert>
```
Standardverhalten:
Beispiel:
```yaml
PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES: "true"
```env
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 \
/opt/mssql-tools18/bin/sqlcmd \
-C \
-S localhost \
-U sa \
-P 'Pwr0mex!s!!!' \
-Q "SELECT 1"
docker compose logs -f romexis
```
### Admin Container prüfen
```bash
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:
```text
Failed to get keystore entry by alias:
server_certificate_...
```
ausführen:
Falls Romexis einen fehlenden Server-Zertifikat-Alias meldet:
```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.
- `RomexisConfig` wird im Container nicht unterstützt.
- Microsoft SQL Server ist das primär unterstützte Datenbank-Backend.
- Firebird-Clientbibliotheken sind im Base Image enthalten, die aktuelle Compose-Laufzeitumgebung fokussiert SQL Server.
- Multiarch-Images werden vom Build-Prozess unterstützt; die funktionale Validierung hängt von Plattform und verfügbaren Romexis-Komponenten ab.
- Romexis-Binaries sind nicht Bestandteil dieses Repositorys.
- Das mRomexis-WebApp-Image erfordert Romexis 6.5.3 oder neuer.
- Romexis Admin wird über eine browserbasierte VNC-Sitzung bereitgestellt, nicht als native Desktop-Anwendung.
- Multiarch-Images werden gebaut und veröffentlicht; 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
+376 -341
@@ -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**
- Provides the Java 11 runtime with JavaFX support.
- Provides Microsoft SQL Server command-line tools.
- Provides Firebird client libraries.
- Is built separately for `amd64` and `arm64`.
- **Romexis Server**
Main Romexis backend service with RMI ports, database access, KeyVault preparation and runtime configuration.
2. **Romexis Server Image**
- Uses the Romexis base image.
- 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.
- **Database backend**
Selected through `DATABASE_BACKEND` and `COMPOSE_FILE` in `.env`. Supported Compose backends are currently `mssql` and `firebird`.
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
- Microsoft SQL Server 2022 support
- Automatic database initialization
- Persistent storage for all application data
- Automatic KeyVault and ProgramData preparation
- Support for existing database volumes
- Multi-stage Docker build
- Multi-architecture image publishing for `amd64` and `arm64`
- Dedicated reusable Romexis base image
- Mapping-based installer extraction using `romexis-copy-map.tsv`
- Selective InstallShield CAB extraction
- Romexis installer versions managed through `romexis-versions.env`
- No Windows Registry required
- No RomexisConfig execution required
- Linux-compatible runtime paths
- Java property injection through `RomexisPropertyAgent`
- CI/CD build support through Drone
- Romexis Server in Docker
- Microsoft SQL Server and Firebird backend Compose overlays
- Runtime backend selection using `.env`
- Local build scripts for repeatable developer builds
- Multi-architecture images for `amd64` and `arm64`
- Payload image layer for installer extraction
- Reusable base runtime image
- Server image built from payload and base images
- Migration Service image
- Romexis Admin image with browser/noVNC access
- mRomexis Web App image
- Branch-specific image suffix support through `IMAGE_SUFFIX`
- Java PropertyAgent support for server-side runtime properties
- Drone CI/CD support with multi-architecture manifests
---
## Architecture
## Runtime Compose Structure
The runtime is split into a base Compose file and backend-specific override files:
```text
+----------------------+
| Romexis Clients |
+----------+-----------+
|
| RMI / Romexis protocol ports
v
+----------------------+
| Romexis Server |
| Docker |
+----------+-----------+
|
| JDBC
v
+----------------------+
| Microsoft SQL Server |
| Docker |
+----------------------+
.env.sample
docker-compose.yml
docker-compose.mssql.yml
docker-compose.firebird.yml
scripts/build-local.sh
scripts/build-local.ps1
```
---
## 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
The base file contains database-independent services such as:
```text
gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64
gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64
gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-server:<version>
romexis
romexis-admin
romexis-app
proxy
```
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 \
--entrypoint cat \
gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203 \
/opt/romexis/version
docker compose up -d
```
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.
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:
Create your runtime configuration:
```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
6.5.3.444.203
```env
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:
```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.
Start the stack:
```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:
```bash
docker compose logs -f romexis
```
SQL Server only:
```bash
docker compose logs -f mssql
```
Stop the environment:
Stop the stack:
```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
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
docker compose logs -f romexis
```
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
TARGETARCH=arm64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
docker exec -it romexis-server cat /opt/romexis/version
```
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**
- 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>`.
to inspect the effective runtime stack.
2. **Romexis Base Image**
- Built from `romexis-base/Dockerfile`.
- Contains Java, JavaFX, SQL tools and common runtime libraries.
- Is architecture-specific.
### Migration Service
3. **Romexis Server Image**
- Built from `romexis/Dockerfile`.
- Consumes the payload image and the base image.
- Adds Chilkat, the Java Property Agent, runtime scripts and startup logic.
The Migration Service is used for Romexis migration and restore workflows.
The payload split avoids repeated installer downloads and keeps the final server image build independent from the original ZIP/CAB extraction step.
It provides:
---
## Migration Service
The repository now includes a Romexis Migration Service and a Windows Migration Client.
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
- web UI and REST API for migration jobs
- database backup upload
- temporary SFTP access per migration job
- server-side `manifest.json` generation
- database restore workflow
- file restore workflow
- migration cancellation and cleanup
- migration completion with SFTP access removal
- validation and cleanup
- coordinated Romexis restart through a shared state file
Supported migration paths:
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:
The restart coordination file is:
```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.
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.
Typical first-start tasks:
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
ROMEXIS_INIT_DB: "0"
```env
ROMEXIS_INIT_DB=0
```
Verbose SQL output can be enabled:
Enable verbose SQL output:
```yaml
DB_CREATE_VERBOSE: "true"
```env
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
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`
The entrypoint initializes missing key files from image defaults when required.
---
## 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.
Replaced responsibilities:
- KeyVault preparation
- ProgramData handling
- Database configuration
- Linux path configuration
- Runtime property injection
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.
---
## 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
SERVER_DB: "5"
Backend selection is controlled at Compose level:
```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
SERVER_RMI_HOSTNAME: "192.168.65.177"
SERVER_RMI_LOW_PORT: "1100"
SERVER_RMI_HIGH_PORT: "1120"
```env
SERVER_RMI_HOSTNAME=192.168.65.177
SERVER_RMI_LOW_PORT=1100
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
PROPERTY_AGENT_SET_<RXPROPERTY_NAME>: "<value>"
```env
PROPERTY_AGENT_SET_<RXPROPERTY_NAME>=<value>
```
Default behavior:
Example:
```yaml
PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES: "true"
```env
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 \
/opt/mssql-tools18/bin/sqlcmd \
-C \
-S localhost \
-U sa \
-P 'Pwr0mex!s!!!' \
-Q "SELECT 1"
docker compose logs -f romexis
```
### Check Admin container
```bash
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:
```text
Failed to get keystore entry by alias:
server_certificate_...
```
run:
If Romexis reports a missing server certificate alias, 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.
- `RomexisConfig` is not supported inside the container.
- Microsoft SQL Server is the primary supported database backend.
- Firebird client libraries are included in the base image, but the runtime Compose setup currently focuses on SQL Server.
- Multi-architecture images are supported by the build pipeline; functional validation depends on the target platform and available Romexis components.
- Romexis binaries are not included in this repository.
- mRomexis Web App image builds require Romexis 6.5.3 or newer.
- Romexis Admin is exposed through a browser-based VNC session, not as a native desktop application.
- Multi-architecture images are built and published, but 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
+172
@@ -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
+65 -1
@@ -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 -5
@@ -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_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-payload:${ROMEXIS_VERSION}
ARG ROMEXIS_FIREBIRD_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest
ARG ROMEXIS_BASE_IMAGE=gitea.buchhorster.de/planmeca/romexis-base-jre:11-${TARGETARCH}${IMAGE_SUFFIX}
ARG ROMEXIS_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-payload:${ROMEXIS_VERSION}${IMAGE_SUFFIX}
ARG ROMEXIS_FIREBIRD_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest${IMAGE_SUFFIX}
```
---
@@ -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
+3 -2
@@ -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
+130 -90
@@ -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:
```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:
The Firebird Compose override must 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
ls -lah /opt/init-romexis-*
docker compose exec romexis cat /opt/init-romexis-db.sh
docker compose exec romexis ls -lah /opt/init-romexis-*
```
The wrapper must not contain:
```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:
Rebuild and recreate:
```bash
docker buildx prune -a -f
docker compose build --no-cache --pull
docker compose up --force-recreate
./scripts/build-local.sh server
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
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:
Open:
```text
violation of PRIMARY or UNIQUE KEY constraint
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"
http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true
```
---
## 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:
```yaml
entrypoint:
- /bin/bash
- -c
- sleep infinity
stdin_open: true
tty: true
```
Then:
Romexis server:
```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
+10 -6
@@ -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
+121
@@ -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
```