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
+175 -168
@@ -1,168 +1,175 @@
Willkommen im Wiki.# Architecture
## High-Level Runtime Architecture
Default Microsoft SQL Server mode:
```text
+----------------------+
| Romexis Clients |
+----------+-----------+
|
| RMI / Romexis protocol ports
v
+----------------------+
| Romexis Server |
| Docker Container |
+----------+-----------+
|
| JDBC
v
+----------------------+
| Microsoft SQL Server |
| Docker Container |
+----------------------+
```
Firebird mode:
```text
+----------------------+
| Romexis Clients |
+----------+-----------+
|
| RMI / Romexis protocol ports
v
+----------------------+
| Romexis Server |
| Docker Container |
+----------+-----------+
|
| JDBC / Jaybird
v
+----------------------+
| Firebird Server |
| Docker Container |
+----------------------+
```
---
## 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-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
|
|-- fix keystore alias
|-- start Romexis Server
```
---
## Database Initialization Router
The runtime uses a small router script:
```text
/opt/init-romexis-db.sh
```
It detects the backend using:
```text
ROMEXIS_DB_URL
SERVER_DB
```
Supported backend identifiers:
| Value | Backend |
|---|---|
| `SERVER_DB=5` | Microsoft SQL Server |
| `SERVER_DB=4` | Firebird |
Backend-specific logic is split into:
```text
/opt/init-romexis-mssql-db.sh
/opt/init-romexis-firebird-db.sh
```
# Architecture
## High-Level Runtime Architecture
The runtime is split into a base Compose stack and a selected database backend override.
### Microsoft SQL Server mode
```text
+----------------------+ +----------------------+
| Romexis Clients | | Browser / noVNC User |
+----------+-----------+ +----------+-----------+
| |
| RMI / Romexis ports | HTTP / WebSocket
v v
+----------------------+ +----------------------+
| Romexis Server | | Romexis Admin |
| Docker Container | | noVNC Container |
+----------+-----------+ +----------------------+
|
| JDBC
v
+----------------------+
| Microsoft SQL Server |
| Docker Container |
+----------------------+
```
### Firebird mode
```text
+----------------------+ +----------------------+
| Romexis Clients | | Browser / noVNC User |
+----------+-----------+ +----------+-----------+
| |
| RMI / Romexis ports | HTTP / WebSocket
v v
+----------------------+ +----------------------+
| Romexis Server | | Romexis Admin |
| Docker Container | | noVNC Container |
+----------+-----------+ +----------------------+
|
| JDBC / Jaybird
v
+----------------------+
| Firebird Server |
| Docker Container |
+----------------------+
```
### mRomexis Web App
```text
+----------------------+
| Browser |
+----------+-----------+
|
| HTTP
v
+----------------------+
| OpenResty / Nginx |
| proxy container |
+----------+-----------+
|
+------------------------------+
| |
v v
+----------------------+ +----------------------+
| mRomexis Web App | | Romexis Server |
| Tomcat Container | | Backend port 8093 |
+----------------------+ +----------------------+
```
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>
|
+--> romexis-server:<version>
|
+--> romexis-admin:<version>
|
+--> romexis-mromexis-app:<version>
romexis-base-jre:11-<arch>
|
+--> romexis-server:<version>-<arch>
romexis-firebird-payload:latest
|
+--> romexis-server:<version>-<arch>
```
---
## Compose Architecture
```text
docker-compose.yml
Common services:
- romexis
- romexis-admin
- romexis-app
- proxy
docker-compose.mssql.yml
MSSQL service and MSSQL-specific Romexis environment.
docker-compose.firebird.yml
Firebird service and Firebird-specific Romexis environment.
```
The selected backend is loaded through:
```env
DATABASE_BACKEND=mssql
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
```
---
## Persistent Data Flow
```text
/srv/romexis-data/
sconfig/
programdata/
romexis_images/
romexis_cache/
romexis_ergodata/
sql-backup/
firebird/
```
The same persistent data root can be used across server recreations. Backend-specific data stays in the selected database volume or host directory.
---
## Admin Runtime Architecture
`romexis-admin` provides a graphical Linux container for Romexis Admin / RomexisConfig.
It starts:
```text
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.
Backup-and-Restore.md
+77 -77
@@ -1,77 +1,77 @@
# Backup and Restore
## MSSQL Backup Restore
The migration service restores SQL Server backups through the shared backup directory.
Host:
```text
DATABASE_BACKUP_DIR=/srv/mssql-backup
```
Migration service:
```text
/upload/database
```
SQL Server:
```text
/var/opt/mssql/backup
```
Restore scripts should use the shared path so SQL Server can access the uploaded `.bak` file.
---
## Firebird Backup Restore
Firebird support includes original helper scripts from the macOS installer payload:
```text
/opt/romexis-firebird-db/tools/Romexis_Firebird_Backup.sh
/opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh
```
Long-term restore strategy should support:
```text
.fbk backup restore through gbak
.fdb file handling for compatible database files
```
For migrations, `gbak`-based restore is preferable because it can bridge Firebird ODS/version differences more safely than copying raw `.fdb` files.
---
## Restart After Restore
The migration service should not directly manipulate the Romexis process from the outside.
Instead, it uses the shared restart state file:
```text
/data/romexis_images/.romexis_restart_state
```
Expected pattern:
1. migration service writes restart request
2. Romexis container notices request
3. Romexis process is restarted
4. Romexis container writes result
5. migration service reads result
6. migration service removes state file
---
## Final Migration Completion
A completed migration should:
- preserve logs
- remove temporary SFTP user
- hide action buttons
- retain migration state for audit/debugging
# Backup and Restore
## MSSQL Backup Restore
The migration service restores SQL Server backups through the shared backup directory.
Host:
```text
DATABASE_BACKUP_DIR=/srv/mssql-backup
```
Migration service:
```text
/upload/database
```
SQL Server:
```text
/var/opt/mssql/backup
```
Restore scripts should use the shared path so SQL Server can access the uploaded `.bak` file.
---
## Firebird Backup Restore
Firebird support includes original helper scripts from the macOS installer payload:
```text
/opt/romexis-firebird-db/tools/Romexis_Firebird_Backup.sh
/opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh
```
Long-term restore strategy should support:
```text
.fbk backup restore through gbak
.fdb file handling for compatible database files
```
For migrations, `gbak`-based restore is preferable because it can bridge Firebird ODS/version differences more safely than copying raw `.fdb` files.
---
## Restart After Restore
The migration service should not directly manipulate the Romexis process from the outside.
Instead, it uses the shared restart state file:
```text
/data/romexis_images/.romexis_restart_state
```
Expected pattern:
1. migration service writes restart request
2. Romexis container notices request
3. Romexis process is restarted
4. Romexis container writes result
5. migration service reads result
6. migration service removes state file
---
## Final Migration Completion
A completed migration should:
- preserve logs
- remove temporary SFTP user
- hide action buttons
- retain migration state for audit/debugging
Base-Image.md
+84 -84
@@ -1,84 +1,84 @@
# Base Image
The base image provides reusable runtime dependencies for the Romexis Server image.
Directory:
```text
romexis-base/
```
---
## Responsibilities
The base image provides:
- Java 11 runtime
- JavaFX/OpenJFX support
- Microsoft SQL Server command-line tools
- Firebird client libraries and tools
- common OS packages
- security updates
---
## Architecture-Specific Tags
```text
romexis-base-jre:11-amd64
romexis-base-jre:11-arm64
```
The base image is architecture-specific because it contains native runtime packages.
---
## Firebird Tools
For Firebird initialization, the Romexis container needs the Firebird CLI tools.
The important tool is usually:
```text
isql-fb
```
not:
```text
isql
```
On Debian/Ubuntu, `isql` may refer to unixODBC. The Firebird initialization script should therefore default to:
```bash
ISQL="${ISQL:-isql-fb}"
```
Required packages are typically:
```text
firebird3.0-utils
libfbclient2
```
Package names can differ depending on the base distribution.
---
## SQL Server Tools
The MSSQL initialization script uses:
```text
/opt/mssql-tools18/bin/sqlcmd
```
This is required for:
- waiting for SQL Server
- creating the database
- creating the Romexis database user
- importing SQL scripts
- updating Romexis data paths
# Base Image
The base image provides reusable runtime dependencies for the Romexis Server image.
Directory:
```text
romexis-base/
```
---
## Responsibilities
The base image provides:
- Java 11 runtime
- JavaFX/OpenJFX support
- Microsoft SQL Server command-line tools
- Firebird client libraries and tools
- common OS packages
- security updates
---
## Architecture-Specific Tags
```text
romexis-base-jre:11-amd64
romexis-base-jre:11-arm64
```
The base image is architecture-specific because it contains native runtime packages.
---
## Firebird Tools
For Firebird initialization, the Romexis container needs the Firebird CLI tools.
The important tool is usually:
```text
isql-fb
```
not:
```text
isql
```
On Debian/Ubuntu, `isql` may refer to unixODBC. The Firebird initialization script should therefore default to:
```bash
ISQL="${ISQL:-isql-fb}"
```
Required packages are typically:
```text
firebird3.0-utils
libfbclient2
```
Package names can differ depending on the base distribution.
---
## SQL Server Tools
The MSSQL initialization script uses:
```text
/opt/mssql-tools18/bin/sqlcmd
```
This is required for:
- waiting for SQL Server
- creating the database
- creating the Romexis database user
- importing SQL scripts
- updating Romexis data paths
Build-System.md
+201 -125
@@ -1,125 +1,201 @@
# Build System
The build system is split into independent layers.
```text
romexis-payload
|
v
romexis-server
^
|
romexis-base-jre
romexis-firebird-payload
|
v
romexis-server
```
---
## Build Components
### Payload build
The payload build extracts the official Romexis installer.
It produces:
```text
/opt/romexis
/opt/romexis-mssql-db
/opt/romexis/version
```
### Firebird payload build
The Firebird payload build extracts the macOS installer database package.
It produces:
```text
/opt/romexis-firebird-db
/opt/romexis-firebird-db/scripts
/opt/romexis-firebird-db/tools
/opt/romexis-firebird-db/templates
```
### Base image build
The base image provides reusable runtime dependencies:
- Java 11
- JavaFX/OpenJFX
- SQL Server tools
- Firebird client libraries and tools
- OS dependencies
### Server image build
The final server image imports:
- `/opt/romexis` from `romexis-payload`
- `/opt/romexis-mssql-db` from `romexis-payload`
- `/opt/romexis-firebird-db` from `romexis-firebird-payload`
- base runtime from `romexis-base-jre`
- Chilkat native library
- Java property agent
- runtime helper scripts
---
## Local Build Commands
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
```
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
```
---
## Debug Build
Disable cache and show full logs:
```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
```
---
## Docker Cache Cleanup
Buildx cache:
```bash
docker buildx prune -a -f
```
Builder cache:
```bash
docker builder prune -a -f
```
System cleanup:
```bash
docker system prune -a -f
```
Do not use `--volumes` unless you intentionally want to remove unused database/application volumes.
# Build System
The build system is split into independent layers and service images.
```text
romexis-payload
|
+--> romexis-server
+--> romexis-admin
+--> romexis-mromexis-app
^
|
romexis-base-jre
romexis-firebird-payload
|
v
romexis-server
```
---
## Build Components
### Payload build
The payload build extracts the official Romexis Windows installer.
It produces:
```text
/opt/romexis
/opt/romexis-mssql-db
/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.
It produces:
```text
/opt/romexis-firebird-db
/opt/romexis-firebird-db/scripts
/opt/romexis-firebird-db/tools
/opt/romexis-firebird-db/templates
```
### Base image build
The base image provides reusable runtime dependencies:
- Java 11
- JavaFX/OpenJFX
- SQL Server tools
- Firebird client libraries and tools
- OS dependencies
### Server image build
The final server image imports:
- `/opt/romexis` from `romexis-payload`
- `/opt/romexis-mssql-db` from `romexis-payload`
- `/opt/romexis-firebird-db` from `romexis-firebird-payload`
- base runtime from `romexis-base-jre`
- Chilkat native library
- 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 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 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 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
```
---
## Runtime Compose Relationship
The runtime Compose files use multi-architecture manifest tags instead of architecture-specific tags.
Feature branches use `IMAGE_SUFFIX`:
```env
IMAGE_SUFFIX=-feature-romexis-admin
```
Runtime Compose image references then resolve to branch-specific manifests.
---
## Docker Cache Cleanup
Buildx cache:
```bash
docker buildx prune -a -f
```
Builder cache:
```bash
docker builder prune -a -f
```
System cleanup:
```bash
docker system prune -a -f
```
Do not use `--volumes` unless you intentionally want to remove unused database/application volumes.
CI-CD-Pipeline.md
+176 -121
@@ -1,121 +1,176 @@
# CI/CD Pipeline
The project uses Drone CI to build and publish images to the Gitea container registry.
---
## Main Pipeline Responsibilities
The pipeline builds:
```text
romexis-payload
romexis-firebird-payload
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
```
---
## Payload Build Logic
The Windows payload build checks version definitions and copy-map changes.
Desired behavior:
| Change | Behavior |
|---|---|
| New version added | build only new version |
| Existing URL changed | force rebuild affected version |
| Copy map changed | rebuild all payload versions |
| Extraction script changed | rebuild all payload versions |
---
## Firebird Payload Build
The Firebird payload is built after the Windows Romexis payload step.
It uses:
```text
romexis-firebird-payload/romexis-firebird-versions.env
```
The build pushes:
```text
romexis-firebird-payload:latest
```
The server image consumes the shared Firebird payload image.
---
## Server Build
The server build pulls:
```text
ROMEXIS_PAYLOAD_IMAGE
ROMEXIS_FIREBIRD_PAYLOAD_IMAGE
ROMEXIS_BASE_IMAGE
```
Then builds the final runtime image for each architecture.
---
## Push vs Load
In CI, use `--push` for buildx output when publishing images.
This avoids unnecessary local image loading and can reduce worker time.
---
## Common CI Troubleshooting
### Build is too fast after cache cleanup
This may mean the pipeline skipped the build because the registry image already exists.
Look for log lines like:
```text
already exists
Skipping rebuild
docker manifest inspect
```
Force rebuild by changing the pipeline condition or setting the force rebuild variable.
### latest tag not found
If the server Dockerfile references:
```text
romexis-firebird-payload:latest
```
then the Firebird payload pipeline must push `latest`.
Build command should include:
```bash
-t "$FIREBIRD_PAYLOAD_IMAGE:latest"
```
### 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
```
# CI/CD Pipeline
The project uses Drone CI to build and publish images to the Gitea container registry.
---
## Main Pipeline Responsibilities
The pipeline builds:
```text
romexis-payload
romexis-firebird-payload
romexis-base-jre:11-amd64
romexis-base-jre:11-arm64
romexis-server:<version>-amd64
romexis-server:<version>-arm64
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.
Desired behavior:
| Change | Behavior |
|---|---|
| New version added | build only new version |
| Existing URL changed | force rebuild affected version |
| Copy map changed | rebuild all payload versions |
| Extraction script changed | rebuild all payload versions |
---
## Firebird Payload Build
The Firebird payload is built after the Windows Romexis payload step.
It uses:
```text
romexis-firebird-payload/romexis-firebird-versions.env
```
The build pushes:
```text
romexis-firebird-payload:latest
```
The server image consumes the shared Firebird payload image.
---
## Server Build
The server build pulls:
```text
ROMEXIS_PAYLOAD_IMAGE
ROMEXIS_FIREBIRD_PAYLOAD_IMAGE
ROMEXIS_BASE_IMAGE
```
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.
This avoids unnecessary local image loading and can reduce worker time.
---
## Common CI Troubleshooting
### Build is too fast after cache cleanup
This may mean the pipeline skipped the build because the registry image already exists.
Look for log lines like:
```text
already exists
Skipping rebuild
docker manifest inspect
```
Force rebuild by changing the pipeline condition or setting the force rebuild variable.
### latest tag not found
If the server Dockerfile references:
```text
romexis-firebird-payload:latest
```
then the Firebird payload pipeline must push `latest`.
### mRomexis build skipped
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
```
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
+218 -141
@@ -1,141 +1,218 @@
# Configuration
Configuration is mostly handled through environment variables in `.env` and Docker Compose.
---
## Core Variables
| 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 |
| `HOST_IP` | Host IP address exposed to Romexis clients |
| `ROMEXIS_DATA_ROOT` | Root directory for persistent Romexis data |
Example:
```env
ROMEXIS_VERSION=6.5.3.444.203
TARGETARCH=amd64
REGISTRY=gitea.buchhorster.de/patrick
ROMEXIS_IMAGE=romexis-server
HOST_IP=192.168.65.177
ROMEXIS_DATA_ROOT=/srv/romexis-data
```
---
## Database Backend Selection
Romexis uses `SERVER_DB` to identify the database backend.
| Value | Backend |
|---|---|
| `5` | Microsoft SQL Server |
| `4` | Firebird |
```env
SERVER_DB=5
```
or:
```env
SERVER_DB=4
```
---
## Microsoft SQL Server Settings
```env
MSSQL_PORT=1433
MSSQL_SA_PASSWORD=Pwr0mex!s!!!
MSSQL_PID=Express
ROMEXIS_DB_NAME=Romexis_db
ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=romexis
```
Generated JDBC URL:
```text
jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;
```
---
## Firebird Settings
```env
SERVER_DB=4
FIREBIRD_PORT=3050
FIREBIRD_USER=sysdba
FIREBIRD_PASSWORD=pwr0mex!
FIREBIRD_DB_PATH=/firebird/data/romexis.fdb
```
Generated JDBC URL:
```text
jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb
```
For Romexis authentication:
```env
ROMEXIS_DB_USER=sysdba
ROMEXIS_DB_PASSWORD=pwr0mex!
```
---
## Database Initialization Version Limit
The database initializer derives the schema target from:
```text
/opt/romexis/version
```
Example:
```text
6.5.3.444.203 -> 653
```
To force initialization only up to a maximum schema marker:
```env
ROMEXIS_DB_MAX_VERSION=653
```
If the container Romexis version is newer than the configured max, the script prints a warning and initializes only up to the configured marker.
---
## RMI Ports
```env
SERVER_RMI_LOW_PORT=1100
SERVER_RMI_HIGH_PORT=1120
```
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.
# Configuration
Configuration is mostly handled through environment variables in `.env` and Docker Compose.
---
## Core Variables
| Variable | Description |
|---|---|
| `REGISTRY` | Container registry namespace |
| `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
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
Backend selection is controlled by Compose file selection, not only by `SERVER_DB`.
### 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
```
### 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
```
---
## Microsoft SQL Server Settings
```env
MSSQL_PORT=1433
MSSQL_SA_PASSWORD=Pwr0mex!s!!!
MSSQL_PID=Express
ROMEXIS_DB_NAME=Romexis_db
ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=romexis
```
Generated JDBC URL:
```text
jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;
```
---
## Firebird Settings
```env
FIREBIRD_PORT=3050
FIREBIRD_USER=sysdba
FIREBIRD_PASSWORD=pwr0mex!
FIREBIRD_DB_PATH=/firebird/data/romexis.fdb
```
Generated JDBC URL:
```text
jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb
```
For Romexis authentication:
```env
ROMEXIS_DB_USER=sysdba
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:
```text
/opt/romexis/version
```
Example:
```text
6.5.3.444.203 -> 653
```
To force initialization only up to a maximum schema marker:
```env
ROMEXIS_DB_MAX_VERSION=653
```
If the container Romexis version is newer than the configured max, the script prints a warning and initializes only up to the configured marker.
---
## Property Agent
The Java Property Agent can set Romexis `RxProperties` from environment variables.
Syntax:
```env
PROPERTY_AGENT_SET_<RXPROPERTY_NAME>=<value>
```
This is primarily relevant for the Romexis server runtime. In the Admin container the PropertyAgent is disabled by default.
Container-Images.md
+155 -88
@@ -1,88 +1,155 @@
# Container Images
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-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>
```
---
## Tagging Strategy
### Base 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:
```text
romexis-payload:6.5.3.444.203
```
It is architecture-independent.
### Firebird payload image
The Firebird payload contains the currently maintained Firebird SQL payload and is consumed as a shared image:
```text
romexis-firebird-payload:latest
```
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:
```text
romexis-server:6.5.3.444.203-amd64
romexis-server:6.5.3.444.203-arm64
romexis-server:6.5.3.444.203
```
---
## 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:
```bash
docker tag romexis-server:local gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-amd64
```
# Container Images
Images are published to the Gitea package registry namespace used by the project.
---
## Main Images
```text
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-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
### Payload image
The Windows payload image is versioned by Romexis version and is architecture-independent:
```text
romexis-payload:6.5.3.444.203
```
### Base image
Base images are architecture-specific and also published as a manifest:
```text
romexis-base-jre:11-amd64
romexis-base-jre:11-arm64
romexis-base-jre:11
```
### Server image
Server images are architecture-specific and published as a multi-architecture manifest:
```text
romexis-server:6.5.3.444.203-amd64
romexis-server:6.5.3.444.203-arm64
romexis-server:6.5.3.444.203
```
### Admin image
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
For multiarch usage:
```bash
docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203
```
Admin image:
```bash
docker pull gitea.buchhorster.de/planmeca/romexis-admin:latest
```
mRomexis Web App image:
```bash
docker pull gitea.buchhorster.de/planmeca/romexis-mromexis-app:6.5.3.444.203
```
---
## 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
+144 -92
@@ -1,92 +1,144 @@
Willkommen im Wiki.# 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.
---
## Backend Identifiers
| `SERVER_DB` | Backend |
|---|---|
| `5` | Microsoft SQL Server |
| `4` | Firebird |
---
## Initialization Scripts
The initialization entry point is:
```text
/opt/init-romexis-db.sh
```
This script routes to:
```text
/opt/init-romexis-mssql-db.sh
/opt/init-romexis-firebird-db.sh
```
---
## Version-Aware Initialization
The backend scripts read:
```text
/opt/romexis/version
```
Example:
```text
6.5.3.444.203
```
They resolve the target schema marker using the explicit Romexis update order.
Example:
```text
6.5.3 -> 653
6.5.2 -> 652
6.5.1 -> 651
6.4.x -> 64
3.8.3 -> 383
```
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
Use:
```env
ROMEXIS_DB_MAX_VERSION=653
```
If the Romexis version is newer than the configured maximum marker, initialization continues only up to the max marker and prints a warning.
---
## Existing Databases
If the database already appears initialized, initialization is skipped.
For MSSQL, this is based on database and user presence.
For Firebird, this is based on the presence of core Romexis tables.
Future upgrade logic can be added by reading the existing database schema marker.
# Database Backends
Romexis supports multiple database backends. This Docker project currently treats Microsoft SQL Server as the default backend and Firebird as a parallel backend through a dedicated Compose override.
---
## 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
The initialization entry point is:
```text
/opt/init-romexis-db.sh
```
This script routes to:
```text
/opt/init-romexis-mssql-db.sh
/opt/init-romexis-firebird-db.sh
```
---
## Version-Aware Initialization
The backend scripts read:
```text
/opt/romexis/version
```
Example:
```text
6.5.3.444.203
```
They resolve the target schema marker using the explicit Romexis update order.
Example:
```text
6.5.3 -> 653
6.5.2 -> 652
6.5.1 -> 651
6.4.x -> 64
3.8.3 -> 383
```
The scripts do not rely on plain numeric order because Romexis update markers do not sort naturally.
---
## Maximum Schema Version
Use:
```env
ROMEXIS_DB_MAX_VERSION=653
```
If the Romexis version is newer than the configured maximum marker, initialization continues only up to the max marker and prints a warning.
---
## Existing Databases
If the database already appears initialized, initialization is skipped.
For MSSQL, this is based on database and user presence.
For Firebird, this is based on the presence of core Romexis tables.
Future upgrade logic can be added by reading the existing database schema marker.
Developer-Guide.md
+111 -111
@@ -1,111 +1,111 @@
# Developer Guide
This page describes the internal project structure and development workflow.
---
## Main Project Directories
```text
romexis-base/
Runtime base image.
romexis-payload/
Windows installer payload extraction.
romexis-firebird-payload/
macOS Firebird SQL payload extraction.
romexis/
Final Romexis Server image.
migration-service/
Migration Web UI, REST API, SFTP and restore orchestration.
migration-client/
Source-side migration helper client.
docs/
Extended markdown documentation.
```
---
## Development Principles
- Keep proprietary binaries out of Git.
- Keep installer extraction in payload images.
- Keep runtime dependencies in the base image.
- Keep final server image focused on assembly and runtime logic.
- Keep MSSQL and Firebird initialization separated.
- Use the wrapper script only for backend routing.
- Prefer explicit validation over silent incomplete images.
---
## Database Init Scripts
```text
init-romexis-db.sh
Routes to backend-specific init script.
init-romexis-mssql-db.sh
Handles SQL Server initialization.
init-romexis-firebird-db.sh
Handles Firebird initialization.
```
---
## Version-Aware Database Updates
The database init scripts use an explicit Romexis update order.
This is required because markers do not sort numerically.
Example:
```text
600, 610, 63, 64, 651, 652, 653
```
The script resolves the target marker from `/opt/romexis/version` and runs updates until that marker.
---
## Testing Image Contents
```bash
docker run --rm --entrypoint find \
gitea.buchhorster.de/planmeca/romexis-server:<tag> \
/opt -maxdepth 3 -type f | sort
```
Open shell:
```bash
docker run --rm -it --entrypoint bash \
gitea.buchhorster.de/planmeca/romexis-server:<tag>
```
---
## Local Debug Compose Override
```yaml
services:
romexis:
entrypoint:
- /bin/bash
- -c
- sleep infinity
stdin_open: true
tty: true
```
Then:
```bash
docker compose exec romexis bash
```
# Developer Guide
This page describes the internal project structure and development workflow.
---
## Main Project Directories
```text
romexis-base/
Runtime base image.
romexis-payload/
Windows installer payload extraction.
romexis-firebird-payload/
macOS Firebird SQL payload extraction.
romexis/
Final Romexis Server image.
migration-service/
Migration Web UI, REST API, SFTP and restore orchestration.
migration-client/
Source-side migration helper client.
docs/
Extended markdown documentation.
```
---
## Development Principles
- Keep proprietary binaries out of Git.
- Keep installer extraction in payload images.
- Keep runtime dependencies in the base image.
- Keep final server image focused on assembly and runtime logic.
- Keep MSSQL and Firebird initialization separated.
- Use the wrapper script only for backend routing.
- Prefer explicit validation over silent incomplete images.
---
## Database Init Scripts
```text
init-romexis-db.sh
Routes to backend-specific init script.
init-romexis-mssql-db.sh
Handles SQL Server initialization.
init-romexis-firebird-db.sh
Handles Firebird initialization.
```
---
## Version-Aware Database Updates
The database init scripts use an explicit Romexis update order.
This is required because markers do not sort numerically.
Example:
```text
600, 610, 63, 64, 651, 652, 653
```
The script resolves the target marker from `/opt/romexis/version` and runs updates until that marker.
---
## Testing Image Contents
```bash
docker run --rm --entrypoint find \
gitea.buchhorster.de/planmeca/romexis-server:<tag> \
/opt -maxdepth 3 -type f | sort
```
Open shell:
```bash
docker run --rm -it --entrypoint bash \
gitea.buchhorster.de/planmeca/romexis-server:<tag>
```
---
## Local Debug Compose Override
```yaml
services:
romexis:
entrypoint:
- /bin/bash
- -c
- sleep infinity
stdin_open: true
tty: true
```
Then:
```bash
docker compose exec romexis bash
```
FAQ.md
+74 -74
@@ -1,74 +1,74 @@
# FAQ
## Are Romexis binaries stored in Git?
No. The repository does not store proprietary Romexis application binaries.
The build system downloads official installer packages and extracts required files during payload builds.
---
## Why use payload images?
Payload images avoid repeated installer downloads and decouple installer extraction from final server image assembly.
---
## Why is Firebird payload shared as latest?
The Firebird payload contains the maintained Firebird SQL payload. It is consumed by the server image independently from the server architecture.
---
## What is the default database backend?
Microsoft SQL Server.
Use:
```env
SERVER_DB=5
```
---
## How do I enable Firebird?
Use:
```env
SERVER_DB=4
FIREBIRD_PASSWORD=pwr0mex!
ROMEXIS_DB_USER=sysdba
ROMEXIS_DB_PASSWORD=pwr0mex!
```
and start the Firebird Compose variant.
---
## Why does Firebird init use isql-fb?
Because `isql` may be unixODBC's tool. Firebird's CLI is commonly named:
```text
isql-fb
```
---
## Can I run on ARM64?
The project builds ARM64 Romexis runtime images. Microsoft SQL Server does not provide an equivalent native ARM64 container path, so Firebird or an external database backend is the more realistic direction for ARM64.
---
## Can I migrate from an existing Windows Romexis server?
Yes, this is the purpose of the migration service and migration client workflow.
---
## Should completed migration jobs still have SFTP users?
No. Completed and cancelled jobs should remove or disable SFTP access and should not recreate temporary users on service restart.
# FAQ
## Are Romexis binaries stored in Git?
No. The repository does not store proprietary Romexis application binaries.
The build system downloads official installer packages and extracts required files during payload builds.
---
## Why use payload images?
Payload images avoid repeated installer downloads and decouple installer extraction from final server image assembly.
---
## Why is Firebird payload shared as latest?
The Firebird payload contains the maintained Firebird SQL payload. It is consumed by the server image independently from the server architecture.
---
## What is the default database backend?
Microsoft SQL Server.
Use:
```env
SERVER_DB=5
```
---
## How do I enable Firebird?
Use:
```env
SERVER_DB=4
FIREBIRD_PASSWORD=pwr0mex!
ROMEXIS_DB_USER=sysdba
ROMEXIS_DB_PASSWORD=pwr0mex!
```
and start the Firebird Compose variant.
---
## Why does Firebird init use isql-fb?
Because `isql` may be unixODBC's tool. Firebird's CLI is commonly named:
```text
isql-fb
```
---
## Can I run on ARM64?
The project builds ARM64 Romexis runtime images. Microsoft SQL Server does not provide an equivalent native ARM64 container path, so Firebird or an external database backend is the more realistic direction for ARM64.
---
## Can I migrate from an existing Windows Romexis server?
Yes, this is the purpose of the migration service and migration client workflow.
---
## Should completed migration jobs still have SFTP users?
No. Completed and cancelled jobs should remove or disable SFTP access and should not recreate temporary users on service restart.
Firebird.md
+150 -150
@@ -1,150 +1,150 @@
# Firebird
Firebird support is being introduced as a parallel database backend.
This is especially relevant because macOS-based Romexis installations use Firebird and because Firebird is a realistic path for ARM64 environments.
---
## Compose Service
Recommended Firebird service:
```yaml
firebird:
image: jacobalberty/firebird:3.0
container_name: romexis-firebird
environment:
ISC_PASSWORD: "${FIREBIRD_PASSWORD}"
FIREBIRD_DATABASE: "romexis.fdb"
ports:
- "${FIREBIRD_PORT:-3050}:3050"
volumes:
- ${ROMEXIS_DATA_ROOT}/firebird:/firebird/data
healthcheck:
test: ["CMD-SHELL", "nc -z localhost 3050 || exit 1"]
interval: 10s
timeout: 5s
retries: 30
start_period: 20s
restart: unless-stopped
```
Do not configure the container to create a second `SYSDBA` user. `SYSDBA` already exists.
---
## Romexis Settings
```env
SERVER_DB=4
FIREBIRD_PORT=3050
FIREBIRD_USER=sysdba
FIREBIRD_PASSWORD=pwr0mex!
FIREBIRD_DB_PATH=/firebird/data/romexis.fdb
ROMEXIS_DB_USER=sysdba
ROMEXIS_DB_PASSWORD=pwr0mex!
```
Generated JDBC URL:
```text
jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb
```
---
## Firebird SQL Payload
The Firebird SQL payload is extracted from the macOS Romexis installer and stored in:
```text
/opt/romexis-firebird-db
```
Important files:
```text
scripts/RX_Create_Database.sql
scripts/RX_Base_10fb_MAC.sql
scripts/rxdb.sh
scripts/rxupd.sh
tools/Romexis_Firebird_Backup.sh
tools/Romexis_Firebird_Restore.sh
templates/romexis_new.fdb
```
---
## Important Tooling Note
The Firebird CLI tool should be:
```text
isql-fb
```
not unixODBC `isql`.
If you see this output:
```text
unixODBC - isql and iusql
```
then the wrong tool is being used.
Set:
```bash
export ISQL=isql-fb
```
or make the init script default to:
```bash
ISQL="${ISQL:-isql-fb}"
```
---
## Database Creation Strategy
If the Firebird container creates an empty database via:
```yaml
FIREBIRD_DATABASE: "romexis.fdb"
```
then the Romexis Firebird init script should not run `CREATE DATABASE` again.
Instead, it should connect to the existing empty database and import the Romexis SQL scripts.
---
## Debugging Firebird Initialization
Open a shell in the Romexis container:
```bash
docker exec -it romexis-server bash
```
Run the initializer manually:
```bash
ISQL=isql-fb DB_CREATE_VERBOSE=1 bash -x /opt/init-romexis-firebird-db.sh
```
Check connectivity:
```bash
bash -c ':</dev/tcp/firebird/3050'
```
Connect manually:
```bash
isql-fb -user sysdba -password 'pwr0mex!' firebird/3050:/firebird/data/romexis.fdb
```
# Firebird
Firebird support is being introduced as a parallel database backend.
This is especially relevant because macOS-based Romexis installations use Firebird and because Firebird is a realistic path for ARM64 environments.
---
## Compose Service
Recommended Firebird service:
```yaml
firebird:
image: jacobalberty/firebird:3.0
container_name: romexis-firebird
environment:
ISC_PASSWORD: "${FIREBIRD_PASSWORD}"
FIREBIRD_DATABASE: "romexis.fdb"
ports:
- "${FIREBIRD_PORT:-3050}:3050"
volumes:
- ${ROMEXIS_DATA_ROOT}/firebird:/firebird/data
healthcheck:
test: ["CMD-SHELL", "nc -z localhost 3050 || exit 1"]
interval: 10s
timeout: 5s
retries: 30
start_period: 20s
restart: unless-stopped
```
Do not configure the container to create a second `SYSDBA` user. `SYSDBA` already exists.
---
## Romexis Settings
```env
SERVER_DB=4
FIREBIRD_PORT=3050
FIREBIRD_USER=sysdba
FIREBIRD_PASSWORD=pwr0mex!
FIREBIRD_DB_PATH=/firebird/data/romexis.fdb
ROMEXIS_DB_USER=sysdba
ROMEXIS_DB_PASSWORD=pwr0mex!
```
Generated JDBC URL:
```text
jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb
```
---
## Firebird SQL Payload
The Firebird SQL payload is extracted from the macOS Romexis installer and stored in:
```text
/opt/romexis-firebird-db
```
Important files:
```text
scripts/RX_Create_Database.sql
scripts/RX_Base_10fb_MAC.sql
scripts/rxdb.sh
scripts/rxupd.sh
tools/Romexis_Firebird_Backup.sh
tools/Romexis_Firebird_Restore.sh
templates/romexis_new.fdb
```
---
## Important Tooling Note
The Firebird CLI tool should be:
```text
isql-fb
```
not unixODBC `isql`.
If you see this output:
```text
unixODBC - isql and iusql
```
then the wrong tool is being used.
Set:
```bash
export ISQL=isql-fb
```
or make the init script default to:
```bash
ISQL="${ISQL:-isql-fb}"
```
---
## Database Creation Strategy
If the Firebird container creates an empty database via:
```yaml
FIREBIRD_DATABASE: "romexis.fdb"
```
then the Romexis Firebird init script should not run `CREATE DATABASE` again.
Instead, it should connect to the existing empty database and import the Romexis SQL scripts.
---
## Debugging Firebird Initialization
Open a shell in the Romexis container:
```bash
docker exec -it romexis-server bash
```
Run the initializer manually:
```bash
ISQL=isql-fb DB_CREATE_VERBOSE=1 bash -x /opt/init-romexis-firebird-db.sh
```
Check connectivity:
```bash
bash -c ':</dev/tcp/firebird/3050'
```
Connect manually:
```bash
isql-fb -user sysdba -password 'pwr0mex!' firebird/3050:/firebird/data/romexis.fdb
```
Home.md
+110 -76
@@ -1,76 +1,110 @@
# Romexis Docker Wiki
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 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.
---
## Main Areas
| Area | Description |
|---|---|
| [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 |
| [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 |
| [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 |
| [Developer Guide](Developer-Guide) | Repository structure and internal development notes |
| [Troubleshooting](Troubleshooting) | Common errors and fixes |
---
## Current Core Components
```text
romexis-payload/
Builds architecture-independent payload images from the official Windows installer.
romexis-firebird-payload/
Builds a Firebird SQL payload from the official macOS installer.
romexis-base/
Builds the reusable Java 11 runtime base image.
romexis/
Builds the final Romexis Server image.
migration-service/
Provides browser-based and API-driven migration orchestration.
migration-client/
Provides the Windows migration helper client.
docs/
Contains extended project documentation.
```
---
## 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)
---
## Important Notes
- No Romexis application binaries are committed to the repository.
- Official Planmeca installer packages are downloaded during payload builds.
- Microsoft SQL Server remains the default and most tested backend.
- Firebird support is being introduced in parallel for macOS/ARM64-oriented scenarios.
- The migration service is designed for moving existing Windows-based Romexis installations into the Docker stack.
# Romexis Docker Wiki
Welcome to the Romexis Docker project wiki.
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.
---
## Main Areas
| Area | Description |
|---|---|
| [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, 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 |
| [Developer Guide](Developer-Guide) | Repository structure and internal development notes |
| [Troubleshooting](Troubleshooting) | Common errors and fixes |
---
## Current Core Components
```text
romexis-payload/
Builds architecture-independent payload images from the official Windows installer.
romexis-firebird-payload/
Builds a Firebird SQL payload from the official macOS installer.
romexis-base/
Builds the reusable Java 11 runtime base image.
romexis/
Builds the final Romexis Server image.
romexis-admin/
Builds the browser-accessible Romexis Admin / RomexisConfig container.
romexis-mromexis-app/
Builds the standalone mRomexis Web App container from the Romexis payload WAR.
migration-service/
Provides browser-based and API-driven migration orchestration.
migration-client/
Provides the Windows migration helper client.
scripts/
Contains local build helpers such as build-local.sh and build-local.ps1.
```
---
## 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. [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)
---
## Important Notes
- 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 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
```
Microsoft-SQL-Server.md
+77 -77
@@ -1,77 +1,77 @@
# Microsoft SQL Server
Microsoft SQL Server is the default and most tested database backend.
---
## Compose Service
The MSSQL service uses the official Microsoft SQL Server image:
```yaml
mssql:
image: mcr.microsoft.com/mssql/server:2022-latest
container_name: romexis-mssql
environment:
ACCEPT_EULA: "Y"
MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}"
MSSQL_PID: "${MSSQL_PID:-Express}"
ports:
- "${MSSQL_PORT}:1433"
volumes:
- mssql_data:/var/opt/mssql
- ${DATABASE_BACKUP_DIR}:/var/opt/mssql/backup
```
---
## Romexis Settings
```env
SERVER_DB=5
MSSQL_HOST=mssql
MSSQL_PORT=1433
MSSQL_SA_PASSWORD=<strong-password>
ROMEXIS_DB_NAME=Romexis_db
ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=<strong-password>
```
Generated JDBC URL:
```text
jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;
```
---
## Initialization
The MSSQL initializer:
```text
/opt/init-romexis-mssql-db.sh
```
Responsibilities:
- wait for SQL Server
- create Romexis database if missing
- create/update Romexis database user
- import base SQL scripts
- import update scripts up to the target schema marker
- update runtime paths in `RBA_Server_Param_S`
---
## Backup Directory
`DATABASE_BACKUP_DIR` is mounted into both the migration service and SQL Server:
```text
Migration service: /upload/database
SQL Server: /var/opt/mssql/backup
```
This allows the migration service to upload a `.bak` file and trigger a database restore.
# Microsoft SQL Server
Microsoft SQL Server is the default and most tested database backend.
---
## Compose Service
The MSSQL service uses the official Microsoft SQL Server image:
```yaml
mssql:
image: mcr.microsoft.com/mssql/server:2022-latest
container_name: romexis-mssql
environment:
ACCEPT_EULA: "Y"
MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}"
MSSQL_PID: "${MSSQL_PID:-Express}"
ports:
- "${MSSQL_PORT}:1433"
volumes:
- mssql_data:/var/opt/mssql
- ${DATABASE_BACKUP_DIR}:/var/opt/mssql/backup
```
---
## Romexis Settings
```env
SERVER_DB=5
MSSQL_HOST=mssql
MSSQL_PORT=1433
MSSQL_SA_PASSWORD=<strong-password>
ROMEXIS_DB_NAME=Romexis_db
ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=<strong-password>
```
Generated JDBC URL:
```text
jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;
```
---
## Initialization
The MSSQL initializer:
```text
/opt/init-romexis-mssql-db.sh
```
Responsibilities:
- wait for SQL Server
- create Romexis database if missing
- create/update Romexis database user
- import base SQL scripts
- import update scripts up to the target schema marker
- update runtime paths in `RBA_Server_Param_S`
---
## Backup Directory
`DATABASE_BACKUP_DIR` is mounted into both the migration service and SQL Server:
```text
Migration service: /upload/database
SQL Server: /var/opt/mssql/backup
```
This allows the migration service to upload a `.bak` file and trigger a database restore.
Migration-Client.md
+54 -54
@@ -1,54 +1,54 @@
# Migration Client
The migration client is the source-side helper for guided migrations from existing Romexis installations.
Current direction:
```text
Windows client first
Future: evaluate C# for broader platform support
```
---
## Responsibilities
The client should help with:
- detecting local Romexis installation paths
- detecting SQL Server connection settings
- creating a database backup
- detecting Romexis image and ergo data directories
- creating a migration job through the migration service API
- uploading data through rclone/SFTP
- calling API endpoints to advance workflow state
- displaying progress and logs
---
## Why rclone?
rclone is suitable for large migrations because it supports:
- SFTP
- progress output
- retries
- resumable workflows
- directory synchronization
- configurable transfers/checkers
---
## Python vs C# Direction
The initial client is Python-based because it is fast to develop and easy to integrate with existing scripts.
For future macOS support, C# may become the better long-term option because it can provide:
- native Windows build
- possible macOS build
- stronger GUI options
- easier single-binary packaging
- better long-term maintainability for a desktop migration client
The README should keep this as an architectural direction, not as a completed feature.
# Migration Client
The migration client is the source-side helper for guided migrations from existing Romexis installations.
Current direction:
```text
Windows client first
Future: evaluate C# for broader platform support
```
---
## Responsibilities
The client should help with:
- detecting local Romexis installation paths
- detecting SQL Server connection settings
- creating a database backup
- detecting Romexis image and ergo data directories
- creating a migration job through the migration service API
- uploading data through rclone/SFTP
- calling API endpoints to advance workflow state
- displaying progress and logs
---
## Why rclone?
rclone is suitable for large migrations because it supports:
- SFTP
- progress output
- retries
- resumable workflows
- directory synchronization
- configurable transfers/checkers
---
## Python vs C# Direction
The initial client is Python-based because it is fast to develop and easy to integrate with existing scripts.
For future macOS support, C# may become the better long-term option because it can provide:
- native Windows build
- possible macOS build
- stronger GUI options
- easier single-binary packaging
- better long-term maintainability for a desktop migration client
The README should keep this as an architectural direction, not as a completed feature.
Migration-Service.md
+153 -153
@@ -1,153 +1,153 @@
# Migration Service
The Romexis Migration Service helps migrate an existing Romexis installation into the Docker-based Romexis Server stack.
It provides:
- Flask Web UI
- REST API
- temporary SFTP users
- migration job state tracking
- database backup upload
- manifest creation
- upload validation
- restore orchestration
- final completion/cancellation workflow
---
## Why a Migration Service?
Romexis installations can contain:
- large SQL Server backups
- large image directories
- ergo data directories
- cache directories
- many small files
Browser uploads alone are not ideal for this. Therefore the migration service combines:
```text
Web UI / API
for orchestration and state
SFTP
for large file and directory transfer
```
---
## Migration Job State
Migration jobs are stored as JSON state files.
Typical workflow:
```text
created
-> database_uploaded
-> database_restored
-> upload_complete
-> validated
-> restored
-> completed
```
Final states:
```text
completed
cancelled
failed
```
---
## SFTP User Lifecycle
The service creates one temporary SFTP user per active migration.
Important behavior:
- active jobs recreate SFTP users on service startup
- completed jobs should not recreate SFTP users
- cancelled jobs should not recreate SFTP users
- failed jobs should not recreate SFTP users unless intentionally reactivated
- completing or cancelling a job removes or disables the temporary SFTP access
---
## Manual Browser Workflow
1. Create migration job in the Web UI.
2. Upload database backup through the browser.
3. The service creates `manifest.json` automatically.
4. Trigger database restore.
5. Upload file directories through SFTP.
6. Mark upload as complete.
7. Validate upload.
8. Run restore.
9. Complete migration and remove SFTP access.
---
## SFTP Upload
The Web UI shows the SFTP credentials and example commands.
Typical rclone setup:
```bash
rclone config create romexis-migration sftp \
host <host> \
port <port> \
user <username> \
pass "$(rclone obscure '<password>')"
```
Upload images:
```bash
rclone sync "/PATH/TO/LOCAL/romexis_images" \
"romexis-migration:/romexis_images" \
--progress \
--transfers 4 \
--checkers 8
```
Upload ergo data:
```bash
rclone sync "/PATH/TO/LOCAL/romexis_ergodata" \
"romexis-migration:/romexis_ergodata" \
--progress \
--transfers 4 \
--checkers 8
```
Optional cache upload:
```bash
rclone sync "/PATH/TO/LOCAL/romexis_cache" \
"romexis-migration:/romexis_cache" \
--progress \
--transfers 4 \
--checkers 8
```
---
## Restart Coordination
The migration service and Romexis container coordinate restarts using a shared state file:
```text
/data/romexis_images/.romexis_restart_state
```
The migration service writes a pending restart request.
The Romexis entrypoint/process observes the state, restarts the Romexis service and writes the result.
The migration service reads the result and removes the state file.
# Migration Service
The Romexis Migration Service helps migrate an existing Romexis installation into the Docker-based Romexis Server stack.
It provides:
- Flask Web UI
- REST API
- temporary SFTP users
- migration job state tracking
- database backup upload
- manifest creation
- upload validation
- restore orchestration
- final completion/cancellation workflow
---
## Why a Migration Service?
Romexis installations can contain:
- large SQL Server backups
- large image directories
- ergo data directories
- cache directories
- many small files
Browser uploads alone are not ideal for this. Therefore the migration service combines:
```text
Web UI / API
for orchestration and state
SFTP
for large file and directory transfer
```
---
## Migration Job State
Migration jobs are stored as JSON state files.
Typical workflow:
```text
created
-> database_uploaded
-> database_restored
-> upload_complete
-> validated
-> restored
-> completed
```
Final states:
```text
completed
cancelled
failed
```
---
## SFTP User Lifecycle
The service creates one temporary SFTP user per active migration.
Important behavior:
- active jobs recreate SFTP users on service startup
- completed jobs should not recreate SFTP users
- cancelled jobs should not recreate SFTP users
- failed jobs should not recreate SFTP users unless intentionally reactivated
- completing or cancelling a job removes or disables the temporary SFTP access
---
## Manual Browser Workflow
1. Create migration job in the Web UI.
2. Upload database backup through the browser.
3. The service creates `manifest.json` automatically.
4. Trigger database restore.
5. Upload file directories through SFTP.
6. Mark upload as complete.
7. Validate upload.
8. Run restore.
9. Complete migration and remove SFTP access.
---
## SFTP Upload
The Web UI shows the SFTP credentials and example commands.
Typical rclone setup:
```bash
rclone config create romexis-migration sftp \
host <host> \
port <port> \
user <username> \
pass "$(rclone obscure '<password>')"
```
Upload images:
```bash
rclone sync "/PATH/TO/LOCAL/romexis_images" \
"romexis-migration:/romexis_images" \
--progress \
--transfers 4 \
--checkers 8
```
Upload ergo data:
```bash
rclone sync "/PATH/TO/LOCAL/romexis_ergodata" \
"romexis-migration:/romexis_ergodata" \
--progress \
--transfers 4 \
--checkers 8
```
Optional cache upload:
```bash
rclone sync "/PATH/TO/LOCAL/romexis_cache" \
"romexis-migration:/romexis_cache" \
--progress \
--transfers 4 \
--checkers 8
```
---
## Restart Coordination
The migration service and Romexis container coordinate restarts using a shared state file:
```text
/data/romexis_images/.romexis_restart_state
```
The migration service writes a pending restart request.
The Romexis entrypoint/process observes the state, restarts the Romexis service and writes the result.
The migration service reads the result and removes the state file.
Migration-Workflow.md
+163 -163
@@ -1,163 +1,163 @@
# Migration Workflow
This page describes the target migration workflow from an existing Romexis server into the Docker-based Romexis stack.
---
## Source System
The source system is usually a Windows-based Romexis server.
Required data:
```text
SQL Server database backup (.bak)
Romexis image directory
Romexis ergo data directory
optional Romexis cache directory
```
The cache directory is optional because it can usually be regenerated.
---
## Target System
The target system runs:
```text
Romexis Server container
Database backend container
Migration Service container
Persistent data volumes
```
---
## Workflow Overview
```text
Existing Romexis Server
|
| database backup
| image data
| ergo data
v
Romexis Migration Service
|
| validation
| database restore
| data restore
v
Docker-based Romexis Server
```
---
## Manual Workflow
1. Open the migration Web UI.
2. Create a new migration job.
3. Upload the database backup in the browser.
4. Let the service create `manifest.json`.
5. Trigger database restore.
6. Upload images and ergo data via SFTP.
7. Mark upload complete.
8. Validate uploaded data.
9. Run restore.
10. Complete migration.
11. SFTP credentials are removed or disabled.
---
## Client-Assisted Workflow
The migration client is intended to automate most source-side steps:
1. detect Romexis installation
2. detect database configuration
3. detect data directories
4. create or use a migration job
5. create database backup
6. upload data through rclone/SFTP
7. call API endpoints to advance the workflow
8. show logs and restore status
---
## Expected Upload Layout
```text
/upload/
├── meta/
│ └── manifest.json
├── database/
│ └── Romexis_db.bak
├── romexis_images/
├── romexis_ergodata/
└── romexis_cache/
```
---
## Manifest
The manifest describes the uploaded migration data.
Example:
```json
{
"migration_id": "example",
"name": "Example Migration",
"source_host": "old-romexis-server",
"database": {
"backup": "database/Romexis_db.bak"
},
"romexis_images": true,
"romexis_ergodata": true,
"romexis_cache": false
}
```
The manual browser workflow can generate this automatically after database upload.
---
## Validation
Validation should check:
- manifest exists
- database backup exists
- image directory exists
- ergo data directory exists
- optional cache directory exists if requested
- file counts
- total bytes
- future checksum data
---
## Restore
The restore step performs or coordinates:
1. database restore
2. file placement into target volumes
3. permission fixes
4. Romexis restart
5. final status reporting
---
## Completion
After successful restore, the job should be marked completed.
Completion should:
- remove or disable temporary SFTP user
- hide workflow action buttons
- keep logs available
- preserve migration state file for audit/debugging
# Migration Workflow
This page describes the target migration workflow from an existing Romexis server into the Docker-based Romexis stack.
---
## Source System
The source system is usually a Windows-based Romexis server.
Required data:
```text
SQL Server database backup (.bak)
Romexis image directory
Romexis ergo data directory
optional Romexis cache directory
```
The cache directory is optional because it can usually be regenerated.
---
## Target System
The target system runs:
```text
Romexis Server container
Database backend container
Migration Service container
Persistent data volumes
```
---
## Workflow Overview
```text
Existing Romexis Server
|
| database backup
| image data
| ergo data
v
Romexis Migration Service
|
| validation
| database restore
| data restore
v
Docker-based Romexis Server
```
---
## Manual Workflow
1. Open the migration Web UI.
2. Create a new migration job.
3. Upload the database backup in the browser.
4. Let the service create `manifest.json`.
5. Trigger database restore.
6. Upload images and ergo data via SFTP.
7. Mark upload complete.
8. Validate uploaded data.
9. Run restore.
10. Complete migration.
11. SFTP credentials are removed or disabled.
---
## Client-Assisted Workflow
The migration client is intended to automate most source-side steps:
1. detect Romexis installation
2. detect database configuration
3. detect data directories
4. create or use a migration job
5. create database backup
6. upload data through rclone/SFTP
7. call API endpoints to advance the workflow
8. show logs and restore status
---
## Expected Upload Layout
```text
/upload/
├── meta/
│ └── manifest.json
├── database/
│ └── Romexis_db.bak
├── romexis_images/
├── romexis_ergodata/
└── romexis_cache/
```
---
## Manifest
The manifest describes the uploaded migration data.
Example:
```json
{
"migration_id": "example",
"name": "Example Migration",
"source_host": "old-romexis-server",
"database": {
"backup": "database/Romexis_db.bak"
},
"romexis_images": true,
"romexis_ergodata": true,
"romexis_cache": false
}
```
The manual browser workflow can generate this automatically after database upload.
---
## Validation
Validation should check:
- manifest exists
- database backup exists
- image directory exists
- ergo data directory exists
- optional cache directory exists if requested
- file counts
- total bytes
- future checksum data
---
## Restore
The restore step performs or coordinates:
1. database restore
2. file placement into target volumes
3. permission fixes
4. Romexis restart
5. final status reporting
---
## Completion
After successful restore, the job should be marked completed.
Completion should:
- remove or disable temporary SFTP user
- hide workflow action buttons
- keep logs available
- preserve migration state file for audit/debugging
Payload-Images.md
+135 -135
@@ -1,135 +1,135 @@
# Payload Images
Payload images are reusable intermediate images containing extracted installer content.
---
## Windows Payload
Directory:
```text
romexis-payload/
```
Purpose:
- download official Windows installer
- extract required InstallShield CAB components
- build `/opt/romexis`
- extract MSSQL initialization SQL files
- write `/opt/romexis/version`
Output contract:
```text
/opt/romexis
/opt/romexis-mssql-db
/opt/romexis/version
/opt/romexis/server/RomexisServer.jar
```
The payload must not contain architecture-specific runtime libraries like Chilkat.
---
## Version File
Supported Windows installer URLs are maintained in:
```text
romexis-payload/romexis-versions.env
```
Example:
```text
6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip
```
---
## Copy Map
Installer extraction is controlled by:
```text
romexis-payload/romexis-copy-map.tsv
```
Format:
```text
Source<TAB>Destination
```
Example:
```text
Server_jar /opt/romexis/server
Server_Program_64bit/server/*.xml /opt/romexis/server
```
When this mapping changes, all payload versions should be rebuilt because the extracted runtime layout may change.
---
## Firebird Payload
Directory:
```text
romexis-firebird-payload/
```
Purpose:
- download official macOS DMG
- extract PKG payloads
- collect Firebird database SQL scripts
- collect original backup/restore helper scripts
- include `romexis_new.fdb` as reference/template
Output contract:
```text
/opt/romexis-firebird-db/version
/opt/romexis-firebird-db/scripts
/opt/romexis-firebird-db/tools
/opt/romexis-firebird-db/templates
/opt/romexis-firebird-db/layout
```
Important files:
```text
/opt/romexis-firebird-db/scripts/rxdb.sh
/opt/romexis-firebird-db/scripts/rxupd.sh
/opt/romexis-firebird-db/scripts/RX_Base_10fb_MAC.sql
/opt/romexis-firebird-db/scripts/RX_Update_653.sql
/opt/romexis-firebird-db/tools/Romexis_Firebird_Backup.sh
/opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh
/opt/romexis-firebird-db/templates/romexis_new.fdb
```
---
## Inspecting a Payload Image
If a payload image is based on `scratch`, it may not have a shell.
Use:
```bash
docker save gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest -o payload.tar
mkdir payload rootfs
tar -xf payload.tar -C payload
tar -xf payload/<layer-id>/layer.tar -C rootfs
find rootfs/opt -type f | sort
```
If the image includes a shell:
```bash
docker run --rm -it --entrypoint sh gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest
```
# Payload Images
Payload images are reusable intermediate images containing extracted installer content.
---
## Windows Payload
Directory:
```text
romexis-payload/
```
Purpose:
- download official Windows installer
- extract required InstallShield CAB components
- build `/opt/romexis`
- extract MSSQL initialization SQL files
- write `/opt/romexis/version`
Output contract:
```text
/opt/romexis
/opt/romexis-mssql-db
/opt/romexis/version
/opt/romexis/server/RomexisServer.jar
```
The payload must not contain architecture-specific runtime libraries like Chilkat.
---
## Version File
Supported Windows installer URLs are maintained in:
```text
romexis-payload/romexis-versions.env
```
Example:
```text
6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip
```
---
## Copy Map
Installer extraction is controlled by:
```text
romexis-payload/romexis-copy-map.tsv
```
Format:
```text
Source<TAB>Destination
```
Example:
```text
Server_jar /opt/romexis/server
Server_Program_64bit/server/*.xml /opt/romexis/server
```
When this mapping changes, all payload versions should be rebuilt because the extracted runtime layout may change.
---
## Firebird Payload
Directory:
```text
romexis-firebird-payload/
```
Purpose:
- download official macOS DMG
- extract PKG payloads
- collect Firebird database SQL scripts
- collect original backup/restore helper scripts
- include `romexis_new.fdb` as reference/template
Output contract:
```text
/opt/romexis-firebird-db/version
/opt/romexis-firebird-db/scripts
/opt/romexis-firebird-db/tools
/opt/romexis-firebird-db/templates
/opt/romexis-firebird-db/layout
```
Important files:
```text
/opt/romexis-firebird-db/scripts/rxdb.sh
/opt/romexis-firebird-db/scripts/rxupd.sh
/opt/romexis-firebird-db/scripts/RX_Base_10fb_MAC.sql
/opt/romexis-firebird-db/scripts/RX_Update_653.sql
/opt/romexis-firebird-db/tools/Romexis_Firebird_Backup.sh
/opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh
/opt/romexis-firebird-db/templates/romexis_new.fdb
```
---
## Inspecting a Payload Image
If a payload image is based on `scratch`, it may not have a shell.
Use:
```bash
docker save gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest -o payload.tar
mkdir payload rootfs
tar -xf payload.tar -C payload
tar -xf payload/<layer-id>/layer.tar -C rootfs
find rootfs/opt -type f | sort
```
If the image includes a shell:
```bash
docker run --rm -it --entrypoint sh gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest
```
Project-Overview.md
+171 -124
@@ -1,124 +1,171 @@
# Project Overview
## Purpose
The Romexis Docker project provides a reproducible Docker-based environment for running Planmeca Romexis Server on Linux.
The project is designed to:
- run Romexis Server in containers
- keep runtime configuration externalized
- avoid manual Windows-style setup steps
- support persistent application and database data
- support migration from existing installations
- support repeatable CI/CD builds
- prepare a path for both Microsoft SQL Server and Firebird database backends
---
## 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.
### Layered image architecture
The build system is split into reusable layers:
```text
Payload image
Contains extracted Romexis application files and SQL payload.
Base image
Contains reusable runtime dependencies such as Java, JavaFX and database tools.
Server image
Combines payload + base + runtime scripts + Java agent.
```
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.
This allows the same payload to be reused for both:
```text
linux/amd64
linux/arm64
```
### Database backend flexibility
Microsoft SQL Server remains the default backend.
Firebird support is being added in parallel because macOS-based Romexis installations use Firebird and because this path is more realistic for ARM64 environments.
---
## Main Features
- Romexis Server 6.5 Docker runtime
- Microsoft SQL Server 2022 support
- Firebird backend preparation
- automatic database initialization
- persistent runtime volumes
- Java Property Agent for runtime property injection
- versioned payload images
- multi-architecture base and server images
- Drone CI/CD pipeline
- migration service with Web UI, REST API and SFTP
- Windows migration client
- Gitea package registry publishing
---
## Supported Platforms
| Platform | Status |
|---|---|
| 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 |
| macOS source migrations | Planned through Firebird and client workflow |
---
## Repository Areas
```text
romexis-base/
Reusable runtime base image.
romexis-payload/
Windows installer payload extraction.
romexis-firebird-payload/
macOS installer Firebird SQL payload extraction.
romexis/
Final Romexis Server image.
migration-service/
Migration orchestration service.
migration-client/
Migration helper client.
docs/
Extended documentation.
docker-compose.yml
Default runtime stack.
docker-compose.firebird.yml
Firebird runtime variant.
.drone.yml
CI/CD pipeline.
```
# Project Overview
## Purpose
The Romexis Docker project provides a reproducible Docker-based environment for running Planmeca Romexis Server on Linux.
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 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, admin and web components into payload images.
### Layered image architecture
The build system is split into reusable layers:
```text
Payload image
Contains extracted Romexis application files, SQL payload and web/admin artifacts.
Base image
Contains reusable runtime dependencies such as Java, JavaFX and database tools.
Service images
Build server, admin, migration and mRomexis runtime containers from the prepared layers.
```
### Architecture-independent payloads
The Romexis payload itself is architecture independent. Architecture-specific parts such as native libraries remain in service runtime images.
The same payload can be reused for:
```text
linux/amd64
linux/arm64
```
### Compose-based backend selection
Database backends are selected through `.env`:
```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 backend
- Firebird backend through Compose override
- automatic database initialization
- persistent runtime volumes
- Java Property Agent for server-side runtime property injection
- versioned payload 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
- Gitea package registry publishing
---
## Supported Platforms
| Platform | Status |
|---|---|
| linux/amd64 | Primary supported target |
| linux/arm64 | Supported for Romexis runtime images |
| Microsoft SQL Server on amd64 | Default backend |
| 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 |
---
## Repository Areas
```text
romexis-base/
Reusable runtime base image.
romexis-payload/
Windows installer payload extraction.
romexis-firebird-payload/
macOS Firebird SQL payload extraction.
romexis/
Final Romexis Server image.
romexis-admin/
Romexis Admin / RomexisConfig noVNC image.
romexis-mromexis-app/
mRomexis Web App Tomcat image.
migration-service/
Migration orchestration service.
migration-client/
Migration helper client.
scripts/
Local build helper scripts.
docker-compose.yml
Base runtime stack.
docker-compose.mssql.yml
Microsoft SQL Server backend override.
docker-compose.firebird.yml
Firebird backend override.
.drone.yml
CI/CD pipeline.
```
Project-Structure.md
+102 -63
@@ -1,63 +1,102 @@
# Project Structure
```text
.
├── .drone.yml
├── .env.sample
├── docker-compose.yml
├── docker-compose.firebird.yml
├── README.md
├── README.de.md
├── docs/
│ ├── BUILD.md
│ ├── DEVELOPERS.md
│ ├── MIGRATION_README.md
│ └── MIGRATION_WORKFLOW.md
├── romexis-base/
│ └── Dockerfile
├── romexis-payload/
│ ├── Dockerfile
│ ├── romexis-versions.env
│ ├── romexis-copy-map.tsv
│ ├── download-romexis-installer-parts.py
│ └── extract-and-copy-romexis-parts.sh
├── romexis-firebird-payload/
│ ├── Dockerfile
│ ├── romexis-firebird-versions.env
│ └── helper scripts
├── romexis/
│ ├── Dockerfile
│ ├── entrypoint.sh
│ ├── init-romexis-db.sh
│ ├── init-romexis-mssql-db.sh
│ ├── init-romexis-firebird-db.sh
│ ├── fix-keystore-alias.sh
│ └── RomexisPropertyAgent.java
├── migration-service/
│ ├── Dockerfile
│ ├── entrypoint.sh
│ ├── app/
│ ├── scripts/
│ └── ssh/
└── migration-client/
└── client files
```
---
## Root README Files
Only the main README files should stay at repository root:
```text
README.md
README.de.md
```
Extended documentation belongs in:
```text
docs/
```
The wiki can then provide a navigable, user-facing documentation layer.
# Project Structure
```text
.
├── .drone.yml
├── .env.sample
├── docker-compose.yml
├── docker-compose.mssql.yml
├── docker-compose.firebird.yml
├── README.md
├── README.de.md
├── BUILD.md
├── BUILD.de.md
├── DEVELOPERS.md
├── scripts/
│ ├── build-local.sh
│ └── build-local.ps1
├── romexis-base/
│ └── Dockerfile
├── romexis-payload/
│ ├── Dockerfile
│ ├── romexis-versions.env
│ ├── romexis-copy-map.tsv
│ ├── download-romexis-installer-parts.py
│ └── extract-and-copy-romexis-parts.sh
├── romexis-firebird-payload/
│ ├── Dockerfile
│ ├── romexis-firebird-versions.env
│ └── helper scripts
├── romexis/
│ ├── Dockerfile
│ ├── entrypoint.sh
│ ├── init-romexis-db.sh
│ ├── init-romexis-mssql-db.sh
│ ├── init-romexis-firebird-db.sh
│ ├── fix-keystore-alias.sh
│ └── RomexisPropertyAgent.java
├── romexis-admin/
│ ├── Dockerfile
│ ├── start.sh
│ └── native helper sources
├── romexis-mromexis-app/
│ ├── Dockerfile
│ └── nginx.conf
├── migration-service/
│ ├── Dockerfile
│ ├── entrypoint.sh
│ ├── app/
│ ├── scripts/
│ └── ssh/
└── migration-client/
└── client files
```
---
## Compose Files
```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
```
The wiki provides a navigable user-facing documentation layer.
Quick-Start.md
+206 -168
@@ -1,168 +1,206 @@
# Quick Start
## 1. Prepare environment
Copy the sample environment file:
```bash
cp .env.sample .env
```
Edit `.env` and set at least:
```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_IMAGE=romexis-server
MIGRATION_IMAGE=romexis-migration-service
SERVER_DB=5
HOST_IP=192.168.65.100 # Replace IP with Host IP
MSSQL_PORT=1433
MSSQL_SA_PASSWORD=Pwr0mex!s!!!
MSSQL_PID=Express
ROMEXIS_DB_NAME=Romexis_db
ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=romexis
SERVER_RMI_LOW_PORT=1100
SERVER_RMI_HIGH_PORT=1120
ROMEXIS_DATA_ROOT=/srv/romexis-data
DATABASE_BACKUP_DIR=/srv/mssql-backup
MIGRATION_HTTP_PORT=8080
MIGRATION_SFTP_PORT=2222
MIGRATION_API_TOKEN=change-me
```
---
## 2. Start default MSSQL stack
```bash
docker compose up -d
```
Show logs:
```bash
docker compose logs -f romexis
docker compose logs -f mssql
```
---
## 3. Start Firebird stack
If using the Firebird compose variant (with firebird setiings in .env file):
```bash
docker compose -f docker-compose.firebird.yml up -d
```
Or combine the base compose file with a Firebird override:
```bash
docker compose -f docker-compose.yml -f docker-compose.firebird.yml up -d
```
---
## 4. Recreate after image changes
```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:
```bash
docker compose exec romexis bash
```
---
## 6. Check database initialization
Inside the Romexis container:
```bash
/opt/init-romexis-db.sh
```
Verbose database initialization:
```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
```
---
## 7. Stop the stack
```bash
docker compose down
```
Stop and remove volumes:
```bash
docker compose down -v
```
Use volume removal carefully because it deletes persistent database/application data.
# Quick Start
## 1. Prepare environment
Copy the sample environment file:
```bash
cp .env.sample .env
```
Edit `.env` and set at least the Romexis version, registry namespace, backend selection and passwords.
Minimal MSSQL example:
```env
REGISTRY=gitea.buchhorster.de/planmeca
ROMEXIS_VERSION=6.5.3.444.203
IMAGE_SUFFIX=
ROMEXIS_IMAGE=romexis-server
MIGRATION_IMAGE=romexis-migration-service
ADMINISTRATION_IMAGE=romexis-admin
MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app
DATABASE_BACKEND=mssql
COMPOSE_PATH_SEPARATOR=:
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
HOST_IP=192.168.65.100
MSSQL_PORT=1433
MSSQL_SA_PASSWORD=Pwr0mex!s!!!
MSSQL_PID=Express
ROMEXIS_DB_NAME=Romexis_db
ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=romexis
SERVER_RMI_LOW_PORT=1100
SERVER_RMI_HIGH_PORT=1120
ROMEXIS_DATA_ROOT=/srv/romexis-data
DATABASE_BACKUP_DIR=/srv/romexis-data/sql-backup
ADMIN_NOVNC_PORT=6080
ADMIN_VNC_PORT=5900
ADMIN_VNC_PASSWORD=promax
ADMIN_RESOLUTION=1280x900x24
ADMIN_LANGUAGE=de
DEBUG_XTERM=false
ADMIN_VNC_LIFECYCLE=true
MROMEXIS_WEB_PORT=8081
MIGRATION_HTTP_PORT=8080
MIGRATION_SFTP_PORT=2222
MIGRATION_API_TOKEN=change-me
```
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 the selected stack
After `.env` is configured, the same command is used for MSSQL and Firebird:
```bash
docker compose up -d
```
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
```
---
## 4. Open browser-based services
Romexis Admin / RomexisConfig through noVNC:
```text
http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true
```
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 up -d --force-recreate
```
Pull and recreate:
```bash
docker compose pull
docker compose up -d --force-recreate
```
---
## 6. Open shells for debugging
Romexis server:
```bash
docker compose exec romexis bash
```
Admin image shell:
```bash
docker compose run --rm --entrypoint /bin/bash romexis-admin
```
mRomexis Web App shell:
```bash
docker compose run --rm --entrypoint /bin/bash romexis-app
```
---
## 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
```
Stop and remove volumes:
```bash
docker compose down -v
```
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
+628 -595
File diff suppressed because it is too large Load Diff
Reference-README.md
+630 -595
File diff suppressed because it is too large Load Diff
Release-Process.md
+67 -67
@@ -1,67 +1,67 @@
# Release Process
## Release Inputs
A release usually includes:
- built and pushed container images
- updated documentation
- release notes
- optional migration service changes
- optional client changes
---
## Suggested Release Steps
1. Ensure the repository builds cleanly.
2. Verify payload image availability.
3. Verify base images for target architectures.
4. Verify server images for target architectures.
5. Verify multiarch manifests.
6. Test Docker Compose startup.
7. Test database initialization.
8. Test migration service startup.
9. Create release notes.
10. Publish Gitea release.
11. Verify Gitea packages.
---
## Image Verification
```bash
docker pull gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
docker pull gitea.buchhorster.de/planmeca/romexis-server:<version>
```
Inspect:
```bash
docker manifest inspect gitea.buchhorster.de/planmeca/romexis-server:<version>
```
---
## Release Notes Should Mention
- new features
- migration service changes
- database backend changes
- breaking changes
- required environment variable changes
- known limitations
---
## Gitea Areas
Use Gitea as follows:
| Area | Purpose |
|---|---|
| Code | Source code and Dockerfiles |
| Releases | Human-readable versioned release notes |
| Packages | Published container images |
| Wiki | Operational and developer documentation |
| Issues | Bugs, feature requests and planning |
# Release Process
## Release Inputs
A release usually includes:
- built and pushed container images
- updated documentation
- release notes
- optional migration service changes
- optional client changes
---
## Suggested Release Steps
1. Ensure the repository builds cleanly.
2. Verify payload image availability.
3. Verify base images for target architectures.
4. Verify server images for target architectures.
5. Verify multiarch manifests.
6. Test Docker Compose startup.
7. Test database initialization.
8. Test migration service startup.
9. Create release notes.
10. Publish Gitea release.
11. Verify Gitea packages.
---
## Image Verification
```bash
docker pull gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
docker pull gitea.buchhorster.de/planmeca/romexis-server:<version>
```
Inspect:
```bash
docker manifest inspect gitea.buchhorster.de/planmeca/romexis-server:<version>
```
---
## Release Notes Should Mention
- new features
- migration service changes
- database backend changes
- breaking changes
- required environment variable changes
- known limitations
---
## Gitea Areas
Use Gitea as follows:
| Area | Purpose |
|---|---|
| Code | Source code and Dockerfiles |
| Releases | Human-readable versioned release notes |
| Packages | Published container images |
| Wiki | Operational and developer documentation |
| Issues | Bugs, feature requests and planning |
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
+136 -72
@@ -1,72 +1,136 @@
# Runtime Layout
## Persistent Data
Recommended persistent root:
```text
/srv/romexis-data
```
Typical directories:
```text
/srv/romexis-data/romexis_images
/srv/romexis-data/romexis_ergodata
/srv/romexis-data/romexis_cache
/srv/romexis-data/firebird
```
---
## Romexis Container Paths
```text
/opt/romexis
/opt/romexis/server
/opt/romexis/sconfig
/opt/romexis/programdata
/data/romexis_images
/data/romexis_ergodata
/data/romexis_cache
```
---
## Database Paths
### MSSQL
```text
/var/opt/mssql
/var/opt/mssql/backup
```
### Firebird
```text
/firebird/data/romexis.fdb
```
---
## Restart State File
Used by migration restore coordination:
```text
/data/romexis_images/.romexis_restart_state
```
---
## Runtime Scripts
```text
/entrypoint.sh
/opt/init-romexis-db.sh
/opt/init-romexis-mssql-db.sh
/opt/init-romexis-firebird-db.sh
/opt/fix-keystore-alias.sh
```
# Runtime Layout
## Persistent Data
Recommended persistent root:
```text
/srv/romexis-data
```
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
/programdata/planmeca/romexis
/data/romexis_images
/data/romexis_ergodata
/data/romexis_cache
```
---
## 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
```text
/var/opt/mssql
/var/opt/mssql/backup
```
### Firebird
```text
/firebird/data/romexis.fdb
```
---
## Restart State File
Used by migration restore coordination:
```text
/data/romexis_images/.romexis_restart_state
```
---
## Runtime Scripts
```text
/entrypoint.sh
/opt/init-romexis-db.sh
/opt/init-romexis-mssql-db.sh
/opt/init-romexis-firebird-db.sh
/opt/fix-keystore-alias.sh
```
Admin startup script:
```text
/usr/local/bin/start.sh
```
Server-Image.md
+100 -99
@@ -1,99 +1,100 @@
# Server Image
Directory:
```text
romexis/
```
The final Romexis Server image combines the prepared payload, runtime base image and runtime scripts.
---
## Build Inputs
```text
ROMEXIS_BASE_IMAGE
ROMEXIS_PAYLOAD_IMAGE
ROMEXIS_FIREBIRD_PAYLOAD_IMAGE
ROMEXIS_VERSION
TARGETARCH
CHILKAT_VERSION
```
Example defaults:
```dockerfile
ARG TARGETARCH=amd64
ARG ROMEXIS_VERSION=6.5.3.444.203
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
```
---
## Build Stages
```text
Stage 1: romexis-payload
Imports /opt/romexis and /opt/romexis-mssql-db.
Stage 2: romexis-firebird-payload
Imports /opt/romexis-firebird-db.
Stage 3: agent-build
Compiles RomexisPropertyAgent.java.
Stage 4: final image
Assembles runtime image.
```
---
## Runtime Scripts
The final image includes:
```text
/entrypoint.sh
/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
```
---
## Java Property Agent
The image includes:
```text
/opt/romexis/server/RomexisPropertyAgent.jar
```
This allows runtime property injection before Romexis starts.
Example environment variable pattern:
```text
PROPERTY_AGENT_SET_KEY_<property-name>=<value>
```
---
## Runtime Validation
The Dockerfile should validate important payload outputs during build, especially:
```text
/opt/romexis/server/RomexisServer.jar
/opt/romexis/version
/opt/romexis-mssql-db
/opt/romexis-firebird-db
```
Failing early is preferred over producing an incomplete runtime image.
# Server Image
Directory:
```text
romexis/
```
The final Romexis Server image combines the prepared payload, runtime base image, Firebird payload and runtime scripts.
---
## Build Inputs
```text
ROMEXIS_BASE_IMAGE
ROMEXIS_PAYLOAD_IMAGE
ROMEXIS_FIREBIRD_PAYLOAD_IMAGE
ROMEXIS_VERSION
TARGETARCH
IMAGE_SUFFIX
CHILKAT_VERSION
```
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}${IMAGE_SUFFIX}
ARG ROMEXIS_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-payload:${ROMEXIS_VERSION}${IMAGE_SUFFIX}
ARG ROMEXIS_FIREBIRD_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest${IMAGE_SUFFIX}
```
---
## Build Stages
```text
Stage 1: romexis-payload
Imports /opt/romexis and /opt/romexis-mssql-db.
Stage 2: romexis-firebird-payload
Imports /opt/romexis-firebird-db.
Stage 3: agent-build
Compiles RomexisPropertyAgent.java.
Stage 4: final image
Assembles runtime image.
```
---
## Runtime Scripts
The final image includes:
```text
/entrypoint.sh
/opt/init-romexis-db.sh
/opt/init-romexis-mssql-db.sh
/opt/init-romexis-firebird-db.sh
/opt/fix-keystore-alias.sh
```
---
## Java Property Agent
The image includes:
```text
/opt/romexis/server/RomexisPropertyAgent.jar
```
This allows runtime property injection before Romexis starts.
Example environment variable pattern:
```text
PROPERTY_AGENT_SET_KEY_<property-name>=<value>
```
---
## Runtime Validation
The Dockerfile should validate important payload outputs during build, especially:
```text
/opt/romexis/server/RomexisServer.jar
/opt/romexis/version
/opt/romexis-mssql-db
/opt/romexis-firebird-db
```
Failing early is preferred over producing an incomplete runtime image.
Source-README-References.md
+13 -12
@@ -1,12 +1,13 @@
# Source README References
These source documents were used as the basis for the wiki package.
- [BUILD.de](Reference-BUILD.de)
- [BUILD](Reference-BUILD)
- [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)
# Source README References
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)
Troubleshooting.md
+226 -186
@@ -1,186 +1,226 @@
# Troubleshooting
## Firebird mode still starts MSSQL initialization
Check:
```bash
docker exec -it romexis-server env | grep -E 'SERVER_DB|ROMEXIS_DB|FIREBIRD'
```
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:
```env
SERVER_DB=4
```
---
## MSSQL_SA_PASSWORD required in Firebird mode
This means the old MSSQL init script is still being executed or old script content is present in the image.
Check inside the Romexis container:
```bash
cat /opt/init-romexis-db.sh
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:
```bash
docker buildx prune -a -f
docker compose build --no-cache --pull
docker compose up --force-recreate
```
---
## Firebird shows unixODBC isql help
If you see:
```text
unixODBC - isql and iusql
```
then the wrong `isql` tool is used.
Use:
```bash
isql-fb
```
Set:
```bash
export ISQL=isql-fb
```
Or change the init script default:
```bash
ISQL="${ISQL:-isql-fb}"
```
---
## 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:
```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"
```
---
## Payload latest tag not found
Error:
```text
romexis-firebird-payload:latest: not found
```
Fix the Firebird payload CI build to push:
```bash
-t "$FIREBIRD_PAYLOAD_IMAGE:latest"
```
---
## Build still uses old files
Clean local build cache:
```bash
docker buildx prune -a -f
```
Then rebuild with:
```bash
docker compose build --no-cache --pull
```
In CI, also check whether the build is skipped because the image already exists in the registry.
---
## Start container with bash for debugging
In Compose:
```yaml
entrypoint:
- /bin/bash
- -c
- sleep infinity
stdin_open: true
tty: true
```
Then:
```bash
docker compose exec romexis bash
```
# 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 compose exec romexis env | grep SERVER_DB
```
The Firebird Compose override must set:
```env
SERVER_DB=4
```
---
## MSSQL_SA_PASSWORD required in Firebird mode
This means the old MSSQL init script is still being executed or old script content is present in the image.
Check inside the Romexis container:
```bash
docker compose exec romexis cat /opt/init-romexis-db.sh
docker compose exec romexis ls -lah /opt/init-romexis-*
```
Rebuild and recreate:
```bash
docker buildx prune -a -f
./scripts/build-local.sh server
docker compose up -d --force-recreate
```
---
## Firebird shows unixODBC isql help
If you see:
```text
unixODBC - isql and iusql
```
then the wrong `isql` tool is used.
Use:
```bash
isql-fb
```
or set:
```bash
export ISQL=isql-fb
```
---
## Admin container does not start RomexisConfig
Check logs:
```bash
docker compose logs -f romexis-admin
```
If `ADMIN_VNC_LIFECYCLE=true`, RomexisConfig starts only after a VNC/noVNC client connects.
Open:
```text
http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true
```
---
## Admin JavaFX or translucency errors
Romexis Admin requires Openbox and xcompmgr.
The Admin image should include:
```text
openbox
xcompmgr
x11-utils
openjfx
libopenjfx-java
libopenjfx-jni
```
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
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
```
---
## Build still uses old files
Clean local build cache:
```bash
docker buildx prune -a -f
```
Then rebuild with the local script:
```bash
./scripts/build-local.sh all
```
Recreate the runtime stack:
```bash
docker compose up -d --force-recreate
```
---
## Start container with bash for debugging
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
```
_Footer.md
+11 -11
@@ -1,11 +1,11 @@
---
Romexis Docker Project Wiki
Repository areas:
- **Code**: source files, Dockerfiles and helper scripts
- **Releases**: published project releases and release notes
- **Packages**: container images in the Gitea package registry
- **Wiki**: operational and developer documentation
---
Romexis Docker Project Wiki
Repository areas:
- **Code**: source files, Dockerfiles and helper scripts
- **Releases**: published project releases and release notes
- **Packages**: container images in the Gitea package registry
- **Wiki**: operational and developer documentation
_Sidebar.md
+48 -44
@@ -1,44 +1,48 @@
# Romexis Docker Wiki
- [Home](Home)
## Getting Started
- [Project Overview](Project-Overview)
- [Architecture](Architecture)
- [Quick Start](Quick-Start)
- [Use with Docker + WSL in Windows](Docker-Desktop-WSL-Windows)
- [Configuration](Configuration)
- [Container Images](Container-Images)
## Build System
- [Build System](Build-System)
- [Payload Images](Payload-Images)
- [Base Image](Base-Image)
- [Server Image](Server-Image)
- [CI/CD Pipeline](CI-CD-Pipeline)
## Database
- [Database Backends](Database-Backends)
- [Microsoft SQL Server](Microsoft-SQL-Server)
- [Firebird](Firebird)
## Migration
- [Migration Service](Migration-Service)
- [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)
- [Project Structure](Project-Structure)
- [Release Process](Release-Process)
- [FAQ](FAQ)
## Source Documents
- [Source README References](Source-README-References)
# Romexis Docker Wiki
- [Home](Home)
## Getting Started
- [Project Overview](Project-Overview)
- [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)
- [CI/CD Pipeline](CI-CD-Pipeline)
## Database
- [Database Backends](Database-Backends)
- [Microsoft SQL Server](Microsoft-SQL-Server)
- [Firebird](Firebird)
## Migration
- [Migration Service](Migration-Service)
- [Migration Workflow](Migration-Workflow)
- [Migration Client](Migration-Client)
## Development
- [Developer Guide](Developer-Guide)
- [Java Property Agent](Java-Property-Agent)
- [Project Structure](Project-Structure)
- [Release Process](Release-Process)
- [FAQ](FAQ)
## Source Documents
- [Source README References](Source-README-References)
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
```