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 # Architecture
## High-Level Runtime Architecture ## High-Level Runtime Architecture
Default Microsoft SQL Server mode: The runtime is split into a base Compose stack and a selected database backend override.
```text ### Microsoft SQL Server mode
+----------------------+
| Romexis Clients | ```text
+----------+-----------+ +----------------------+ +----------------------+
| | Romexis Clients | | Browser / noVNC User |
| RMI / Romexis protocol ports +----------+-----------+ +----------+-----------+
v | |
+----------------------+ | RMI / Romexis ports | HTTP / WebSocket
| Romexis Server | v v
| Docker Container | +----------------------+ +----------------------+
+----------+-----------+ | Romexis Server | | Romexis Admin |
| | Docker Container | | noVNC Container |
| JDBC +----------+-----------+ +----------------------+
v |
+----------------------+ | JDBC
| Microsoft SQL Server | v
| Docker Container | +----------------------+
+----------------------+ | Microsoft SQL Server |
``` | Docker Container |
+----------------------+
Firebird mode: ```
```text ### Firebird mode
+----------------------+
| Romexis Clients | ```text
+----------+-----------+ +----------------------+ +----------------------+
| | Romexis Clients | | Browser / noVNC User |
| RMI / Romexis protocol ports +----------+-----------+ +----------+-----------+
v | |
+----------------------+ | RMI / Romexis ports | HTTP / WebSocket
| Romexis Server | v v
| Docker Container | +----------------------+ +----------------------+
+----------+-----------+ | Romexis Server | | Romexis Admin |
| | Docker Container | | noVNC Container |
| JDBC / Jaybird +----------+-----------+ +----------------------+
v |
+----------------------+ | JDBC / Jaybird
| Firebird Server | v
| Docker Container | +----------------------+
+----------------------+ | Firebird Server |
``` | Docker Container |
+----------------------+
--- ```
## Image Architecture ### mRomexis Web App
```text ```text
romexis-payload:<version> +----------------------+
/opt/romexis | Browser |
/opt/romexis-mssql-db +----------+-----------+
/opt/romexis/version |
| HTTP
romexis-firebird-payload:latest v
/opt/romexis-firebird-db +----------------------+
Firebird SQL scripts | OpenResty / Nginx |
Firebird backup/restore helpers | proxy container |
romexis_new.fdb template/reference +----------+-----------+
|
romexis-base-jre:11-<arch> +------------------------------+
Java 11 | |
JavaFX/OpenJFX v v
database client tools +----------------------+ +----------------------+
system dependencies | mRomexis Web App | | Romexis Server |
| Tomcat Container | | Backend port 8093 |
romexis-server:<version>-<arch> +----------------------+ +----------------------+
Romexis payload ```
Firebird payload
base runtime The mRomexis proxy rewrites backend proxy requests to the internal `romexis` service. It does not trust arbitrary hosts supplied by the browser.
Java property agent
initialization scripts ---
entrypoint
``` ## Image Architecture
--- ```text
romexis-payload:<version>
## Why Payload Images? |
+--> romexis-server:<version>
The original Dockerfile downloaded and extracted installer files inside the final server build. |
+--> romexis-admin:<version>
That worked, but had drawbacks: |
+--> romexis-mromexis-app:<version>
- repeated large downloads
- slow builds romexis-base-jre:11-<arch>
- harder debugging |
- installer extraction tightly coupled to server image build +--> romexis-server:<version>-<arch>
- poor reuse across architectures
romexis-firebird-payload:latest
Payload images solve this by making the extracted installer content a reusable build artifact. |
+--> romexis-server:<version>-<arch>
--- ```
## Runtime Data Layout ---
The runtime stack uses persistent volumes or host directories for: ## Compose Architecture
```text ```text
/data/romexis_images docker-compose.yml
/data/romexis_ergodata Common services:
/data/romexis_cache - romexis
/opt/romexis/sconfig - romexis-admin
/opt/romexis/programdata - romexis-app
``` - proxy
Database data is backend-specific: docker-compose.mssql.yml
MSSQL service and MSSQL-specific Romexis environment.
```text
Microsoft SQL Server: docker-compose.firebird.yml
/var/opt/mssql Firebird service and Firebird-specific Romexis environment.
```
Firebird:
/firebird/data/romexis.fdb The selected backend is loaded through:
```
```env
--- DATABASE_BACKEND=mssql
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
## Startup Flow ```
```text ---
entrypoint.sh
| ## Persistent Data Flow
|-- prepare persistent directories
|-- generate database URL if needed ```text
|-- write Romexis configuration /srv/romexis-data/
|-- run /opt/init-romexis-db.sh sconfig/
| | programdata/
| |-- route to MSSQL init if SERVER_DB=5 romexis_images/
| |-- route to Firebird init if SERVER_DB=4 romexis_cache/
| romexis_ergodata/
|-- fix keystore alias sql-backup/
|-- start Romexis Server firebird/
``` ```
--- The same persistent data root can be used across server recreations. Backend-specific data stays in the selected database volume or host directory.
## Database Initialization Router ---
The runtime uses a small router script: ## Admin Runtime Architecture
```text `romexis-admin` provides a graphical Linux container for Romexis Admin / RomexisConfig.
/opt/init-romexis-db.sh
``` It starts:
It detects the backend using: ```text
Xvfb
```text Openbox
ROMEXIS_DB_URL xcompmgr
SERVER_DB x11vnc
``` noVNC / websockify
```
Supported backend identifiers:
RomexisConfig can be started on demand when a VNC/noVNC client connects and stopped again when the last client disconnects.
| Value | Backend |
|---|---| ---
| `SERVER_DB=5` | Microsoft SQL Server |
| `SERVER_DB=4` | Firebird | ## mRomexis Web App Architecture
Backend-specific logic is split into: `romexis-app` is a Tomcat image containing:
```text ```text
/opt/init-romexis-mssql-db.sh /usr/local/tomcat/webapps/ROOT.war
/opt/init-romexis-firebird-db.sh ```
```
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 # Backup and Restore
## MSSQL Backup Restore ## MSSQL Backup Restore
The migration service restores SQL Server backups through the shared backup directory. The migration service restores SQL Server backups through the shared backup directory.
Host: Host:
```text ```text
DATABASE_BACKUP_DIR=/srv/mssql-backup DATABASE_BACKUP_DIR=/srv/mssql-backup
``` ```
Migration service: Migration service:
```text ```text
/upload/database /upload/database
``` ```
SQL Server: SQL Server:
```text ```text
/var/opt/mssql/backup /var/opt/mssql/backup
``` ```
Restore scripts should use the shared path so SQL Server can access the uploaded `.bak` file. Restore scripts should use the shared path so SQL Server can access the uploaded `.bak` file.
--- ---
## Firebird Backup Restore ## Firebird Backup Restore
Firebird support includes original helper scripts from the macOS installer payload: Firebird support includes original helper scripts from the macOS installer payload:
```text ```text
/opt/romexis-firebird-db/tools/Romexis_Firebird_Backup.sh /opt/romexis-firebird-db/tools/Romexis_Firebird_Backup.sh
/opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh /opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh
``` ```
Long-term restore strategy should support: Long-term restore strategy should support:
```text ```text
.fbk backup restore through gbak .fbk backup restore through gbak
.fdb file handling for compatible database files .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. 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 ## Restart After Restore
The migration service should not directly manipulate the Romexis process from the outside. The migration service should not directly manipulate the Romexis process from the outside.
Instead, it uses the shared restart state file: Instead, it uses the shared restart state file:
```text ```text
/data/romexis_images/.romexis_restart_state /data/romexis_images/.romexis_restart_state
``` ```
Expected pattern: Expected pattern:
1. migration service writes restart request 1. migration service writes restart request
2. Romexis container notices request 2. Romexis container notices request
3. Romexis process is restarted 3. Romexis process is restarted
4. Romexis container writes result 4. Romexis container writes result
5. migration service reads result 5. migration service reads result
6. migration service removes state file 6. migration service removes state file
--- ---
## Final Migration Completion ## Final Migration Completion
A completed migration should: A completed migration should:
- preserve logs - preserve logs
- remove temporary SFTP user - remove temporary SFTP user
- hide action buttons - hide action buttons
- retain migration state for audit/debugging - retain migration state for audit/debugging
Base-Image.md
+84 -84
@@ -1,84 +1,84 @@
# Base Image # Base Image
The base image provides reusable runtime dependencies for the Romexis Server image. The base image provides reusable runtime dependencies for the Romexis Server image.
Directory: Directory:
```text ```text
romexis-base/ romexis-base/
``` ```
--- ---
## Responsibilities ## Responsibilities
The base image provides: The base image provides:
- Java 11 runtime - Java 11 runtime
- JavaFX/OpenJFX support - JavaFX/OpenJFX support
- Microsoft SQL Server command-line tools - Microsoft SQL Server command-line tools
- Firebird client libraries and tools - Firebird client libraries and tools
- common OS packages - common OS packages
- security updates - security updates
--- ---
## Architecture-Specific Tags ## Architecture-Specific Tags
```text ```text
romexis-base-jre:11-amd64 romexis-base-jre:11-amd64
romexis-base-jre:11-arm64 romexis-base-jre:11-arm64
``` ```
The base image is architecture-specific because it contains native runtime packages. The base image is architecture-specific because it contains native runtime packages.
--- ---
## Firebird Tools ## Firebird Tools
For Firebird initialization, the Romexis container needs the Firebird CLI tools. For Firebird initialization, the Romexis container needs the Firebird CLI tools.
The important tool is usually: The important tool is usually:
```text ```text
isql-fb isql-fb
``` ```
not: not:
```text ```text
isql isql
``` ```
On Debian/Ubuntu, `isql` may refer to unixODBC. The Firebird initialization script should therefore default to: On Debian/Ubuntu, `isql` may refer to unixODBC. The Firebird initialization script should therefore default to:
```bash ```bash
ISQL="${ISQL:-isql-fb}" ISQL="${ISQL:-isql-fb}"
``` ```
Required packages are typically: Required packages are typically:
```text ```text
firebird3.0-utils firebird3.0-utils
libfbclient2 libfbclient2
``` ```
Package names can differ depending on the base distribution. Package names can differ depending on the base distribution.
--- ---
## SQL Server Tools ## SQL Server Tools
The MSSQL initialization script uses: The MSSQL initialization script uses:
```text ```text
/opt/mssql-tools18/bin/sqlcmd /opt/mssql-tools18/bin/sqlcmd
``` ```
This is required for: This is required for:
- waiting for SQL Server - waiting for SQL Server
- creating the database - creating the database
- creating the Romexis database user - creating the Romexis database user
- importing SQL scripts - importing SQL scripts
- updating Romexis data paths - updating Romexis data paths
Build-System.md
+201 -125
@@ -1,125 +1,201 @@
# Build System # Build System
The build system is split into independent layers. The build system is split into independent layers and service images.
```text ```text
romexis-payload romexis-payload
| |
v +--> romexis-server
romexis-server +--> romexis-admin
^ +--> romexis-mromexis-app
| ^
romexis-base-jre |
romexis-base-jre
romexis-firebird-payload
| romexis-firebird-payload
v |
romexis-server v
``` romexis-server
```
---
---
## Build Components
## Build Components
### Payload build
### Payload build
The payload build extracts the official Romexis installer.
The payload build extracts the official Romexis Windows installer.
It produces:
It produces:
```text
/opt/romexis ```text
/opt/romexis-mssql-db /opt/romexis
/opt/romexis/version /opt/romexis-mssql-db
``` /opt/romexis/version
```
### Firebird payload build
It also provides files consumed by other service images, including Admin files and the mRomexis Web App WAR when available.
The Firebird payload build extracts the macOS installer database package.
### Firebird payload build
It produces:
The Firebird payload build extracts the macOS installer database package.
```text
/opt/romexis-firebird-db It produces:
/opt/romexis-firebird-db/scripts
/opt/romexis-firebird-db/tools ```text
/opt/romexis-firebird-db/templates /opt/romexis-firebird-db
``` /opt/romexis-firebird-db/scripts
/opt/romexis-firebird-db/tools
### Base image build /opt/romexis-firebird-db/templates
```
The base image provides reusable runtime dependencies:
### Base image build
- Java 11
- JavaFX/OpenJFX The base image provides reusable runtime dependencies:
- SQL Server tools
- Firebird client libraries and tools - Java 11
- OS dependencies - JavaFX/OpenJFX
- SQL Server tools
### Server image build - Firebird client libraries and tools
- OS dependencies
The final server image imports:
### Server image build
- `/opt/romexis` from `romexis-payload`
- `/opt/romexis-mssql-db` from `romexis-payload` The final server image imports:
- `/opt/romexis-firebird-db` from `romexis-firebird-payload`
- base runtime from `romexis-base-jre` - `/opt/romexis` from `romexis-payload`
- Chilkat native library - `/opt/romexis-mssql-db` from `romexis-payload`
- Java property agent - `/opt/romexis-firebird-db` from `romexis-firebird-payload`
- runtime helper scripts - base runtime from `romexis-base-jre`
- Chilkat native library
--- - Java property agent
- runtime helper scripts
## Local Build Commands
### Admin image build
Build payload:
The Admin image imports Romexis Admin files from the payload and adds a browser-accessible X11/noVNC runtime.
```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 Important runtime components:
```
```text
Build Firebird payload: Xvfb
Openbox
```bash xcompmgr
docker build --build-arg ROMEXIS_VERSION=6.5.3.444.203 -t gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest ./romexis-firebird-payload x11vnc
``` noVNC/websockify
JavaFX
Build server image: ```
```bash ### mRomexis Web App build
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
``` The mRomexis Web App image copies:
--- ```text
/opt/romexis/broker/mromexis-html.war
## Debug Build ```
Disable cache and show full logs: from the Romexis payload into Tomcat as:
```bash ```text
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 /usr/local/tomcat/webapps/ROOT.war
``` ```
--- This is only possible for Romexis 6.5.3 and newer.
## Docker Cache Cleanup ---
Buildx cache: ## Local Build Scripts
```bash Local builds are handled through:
docker buildx prune -a -f
``` ```text
scripts/build-local.sh
Builder cache: scripts/build-local.ps1
```
```bash
docker builder prune -a -f Linux/macOS:
```
```bash
System cleanup: chmod +x scripts/build-local.sh
./scripts/build-local.sh all
```bash ```
docker system prune -a -f
``` Windows PowerShell:
Do not use `--volumes` unless you intentionally want to remove unused database/application volumes. ```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 # CI/CD Pipeline
The project uses Drone CI to build and publish images to the Gitea container registry. The project uses Drone CI to build and publish images to the Gitea container registry.
--- ---
## Main Pipeline Responsibilities ## Main Pipeline Responsibilities
The pipeline builds: The pipeline builds:
```text ```text
romexis-payload romexis-payload
romexis-firebird-payload romexis-firebird-payload
romexis-base-jre:11-amd64 romexis-base-jre:11-amd64
romexis-base-jre:11-arm64 romexis-base-jre:11-arm64
romexis-server:<version>-amd64 romexis-server:<version>-amd64
romexis-server:<version>-arm64 romexis-server:<version>-arm64
romexis-server:<version> multiarch manifest romexis-admin:<version>-amd64
migration-service romexis-admin:<version>-arm64
``` romexis-mromexis-app:<version>-amd64
romexis-mromexis-app:<version>-arm64
--- romexis-migration-service:amd64
romexis-migration-service:arm64
## Payload Build Logic multiarch manifests
```
The Windows payload build checks version definitions and copy-map changes.
---
Desired behavior:
## Branch Suffix Handling
| Change | Behavior |
|---|---| For `main`, image tags are published without a suffix.
| New version added | build only new version |
| Existing URL changed | force rebuild affected version | For feature branches, the branch name is normalized and appended as an image suffix:
| Copy map changed | rebuild all payload versions |
| Extraction script changed | rebuild all payload versions | ```text
-feature-romexis-admin
--- ```
## Firebird Payload Build This allows feature branch images and manifests to be tested without overwriting `main` images.
The Firebird payload is built after the Windows Romexis payload step. ---
It uses: ## Payload Build Logic
```text The Windows payload build checks version definitions and copy-map changes.
romexis-firebird-payload/romexis-firebird-versions.env
``` Desired behavior:
The build pushes: | Change | Behavior |
|---|---|
```text | New version added | build only new version |
romexis-firebird-payload:latest | Existing URL changed | force rebuild affected version |
``` | Copy map changed | rebuild all payload versions |
| Extraction script changed | rebuild all payload versions |
The server image consumes the shared Firebird payload image.
---
---
## Firebird Payload Build
## Server Build
The Firebird payload is built after the Windows Romexis payload step.
The server build pulls:
It uses:
```text
ROMEXIS_PAYLOAD_IMAGE ```text
ROMEXIS_FIREBIRD_PAYLOAD_IMAGE romexis-firebird-payload/romexis-firebird-versions.env
ROMEXIS_BASE_IMAGE ```
```
The build pushes:
Then builds the final runtime image for each architecture.
```text
--- romexis-firebird-payload:latest
```
## Push vs Load
The server image consumes the shared Firebird payload image.
In CI, use `--push` for buildx output when publishing images.
---
This avoids unnecessary local image loading and can reduce worker time.
## Server Build
---
The server build pulls:
## Common CI Troubleshooting
```text
### Build is too fast after cache cleanup ROMEXIS_PAYLOAD_IMAGE
ROMEXIS_FIREBIRD_PAYLOAD_IMAGE
This may mean the pipeline skipped the build because the registry image already exists. ROMEXIS_BASE_IMAGE
```
Look for log lines like:
Then builds the final runtime image for each architecture.
```text
already exists ---
Skipping rebuild
docker manifest inspect ## Admin Build
```
The Admin build consumes the Romexis payload and builds:
Force rebuild by changing the pipeline condition or setting the force rebuild variable.
```text
### latest tag not found romexis-admin:<version>-amd64
romexis-admin:<version>-arm64
If the server Dockerfile references: romexis-admin:<version>
romexis-admin:latest
```text ```
romexis-firebird-payload:latest
``` The final image contains the graphical noVNC runtime and Romexis Admin / RomexisConfig files.
then the Firebird payload pipeline must push `latest`. ---
Build command should include: ## mRomexis Web App Build
```bash mRomexis Web App images are built only for Romexis versions where:
-t "$FIREBIRD_PAYLOAD_IMAGE:latest"
``` ```text
version >= 6.5.3
### Payload missing from final image ```
Check the final image: Older versions are skipped because the payload does not contain:
```bash ```text
docker run --rm --entrypoint find \ /opt/romexis/broker/mromexis-html.war
gitea.buchhorster.de/planmeca/romexis-server:<tag> \ ```
/opt -maxdepth 3 -type f
``` 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
Configuration is mostly handled through environment variables in `.env` and Docker Compose. Configuration is mostly handled through environment variables in `.env` and Docker Compose.
--- ---
## Core Variables ## Core Variables
| Variable | Description | | Variable | Description |
|---|---| |---|---|
| `ROMEXIS_VERSION` | Romexis version to run | | `REGISTRY` | Container registry namespace |
| `TARGETARCH` | Target architecture suffix, e.g. `amd64` or `arm64` | | `ROMEXIS_VERSION` | Romexis version to run |
| `REGISTRY` | Container registry namespace | | `IMAGE_SUFFIX` | Optional branch-specific image suffix |
| `ROMEXIS_IMAGE` | Romexis Server image name | | `DATABASE_BACKEND` | Selected backend, usually `mssql` or `firebird` |
| `HOST_IP` | Host IP address exposed to Romexis clients | | `COMPOSE_FILE` | Compose file chain based on selected backend |
| `ROMEXIS_DATA_ROOT` | Root directory for persistent Romexis data | | `HOST_IP` | Host IP address exposed to Romexis clients |
| `ROMEXIS_DATA_ROOT` | Root directory for persistent Romexis data |
Example:
Example:
```env
ROMEXIS_VERSION=6.5.3.444.203 ```env
TARGETARCH=amd64 REGISTRY=gitea.buchhorster.de/planmeca
REGISTRY=gitea.buchhorster.de/patrick ROMEXIS_VERSION=6.5.3.444.203
ROMEXIS_IMAGE=romexis-server IMAGE_SUFFIX=
HOST_IP=192.168.65.177 DATABASE_BACKEND=mssql
ROMEXIS_DATA_ROOT=/srv/romexis-data 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
```
## Database Backend Selection
---
Romexis uses `SERVER_DB` to identify the database backend.
## Image Name Variables
| Value | Backend |
|---|---| ```env
| `5` | Microsoft SQL Server | ROMEXIS_IMAGE=romexis-server
| `4` | Firebird | MIGRATION_IMAGE=romexis-migration-service
ADMINISTRATION_IMAGE=romexis-admin
```env MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app
SERVER_DB=5 ```
```
These are combined with `REGISTRY`, `ROMEXIS_VERSION` and `IMAGE_SUFFIX` by the Compose files.
or:
---
```env
SERVER_DB=4 ## Database Backend Selection
```
Backend selection is controlled by Compose file selection, not only by `SERVER_DB`.
---
### MSSQL
## Microsoft SQL Server Settings
```env
```env DATABASE_BACKEND=mssql
MSSQL_PORT=1433 COMPOSE_PATH_SEPARATOR=:
MSSQL_SA_PASSWORD=Pwr0mex!s!!! COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
MSSQL_PID=Express ```
ROMEXIS_DB_NAME=Romexis_db The MSSQL override then sets the Romexis backend values, for example:
ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=romexis ```env
``` SERVER_DB=5
MSSQL_HOST=mssql
Generated JDBC URL: ```
```text ### Firebird
jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;
``` ```env
DATABASE_BACKEND=firebird
--- COMPOSE_PATH_SEPARATOR=:
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
## Firebird Settings ```
```env The Firebird override then sets the Romexis backend values, for example:
SERVER_DB=4
FIREBIRD_PORT=3050 ```env
FIREBIRD_USER=sysdba SERVER_DB=4
FIREBIRD_PASSWORD=pwr0mex! FIREBIRD_HOST=firebird
FIREBIRD_DB_PATH=/firebird/data/romexis.fdb ```
```
---
Generated JDBC URL:
## Microsoft SQL Server Settings
```text
jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb ```env
``` MSSQL_PORT=1433
MSSQL_SA_PASSWORD=Pwr0mex!s!!!
For Romexis authentication: MSSQL_PID=Express
```env ROMEXIS_DB_NAME=Romexis_db
ROMEXIS_DB_USER=sysdba ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=pwr0mex! ROMEXIS_DB_PASSWORD=romexis
``` ```
--- Generated JDBC URL:
## Database Initialization Version Limit ```text
jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;
The database initializer derives the schema target from: ```
```text ---
/opt/romexis/version
``` ## Firebird Settings
Example: ```env
FIREBIRD_PORT=3050
```text FIREBIRD_USER=sysdba
6.5.3.444.203 -> 653 FIREBIRD_PASSWORD=pwr0mex!
``` FIREBIRD_DB_PATH=/firebird/data/romexis.fdb
```
To force initialization only up to a maximum schema marker:
Generated JDBC URL:
```env
ROMEXIS_DB_MAX_VERSION=653 ```text
``` jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb
```
If the container Romexis version is newer than the configured max, the script prints a warning and initializes only up to the configured marker.
For Romexis authentication:
---
```env
## RMI Ports ROMEXIS_DB_USER=sysdba
ROMEXIS_DB_PASSWORD=pwr0mex!
```env ```
SERVER_RMI_LOW_PORT=1100
SERVER_RMI_HIGH_PORT=1120 ---
```
## RMI Ports
These ports must be reachable from Romexis clients.
```env
--- SERVER_RMI_LOW_PORT=1100
SERVER_RMI_HIGH_PORT=1120
## Migration Service Settings ```
```env These ports must be reachable from Romexis clients.
MIGRATION_HTTP_PORT=8080
MIGRATION_SFTP_PORT=2222 ---
MIGRATION_API_TOKEN=change-me
DATABASE_BACKUP_DIR=/srv/mssql-backup ## Romexis Admin Settings
```
```env
`DATABASE_BACKUP_DIR` is shared between the migration service and the database backend for database restore workflows. 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 # Container Images
Images are published to the Gitea package registry namespace used by the project. Images are published to the Gitea package registry namespace used by the project.
--- ---
## Main Images ## Main Images
```text ```text
gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64 gitea.buchhorster.de/planmeca/romexis-payload:<version>
gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64 gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest
gitea.buchhorster.de/planmeca/romexis-payload:<version> gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64
gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest 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>-amd64
gitea.buchhorster.de/planmeca/romexis-server:<version> gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-server:<version>
gitea.buchhorster.de/planmeca/romexis-migration-service:<tag>
``` gitea.buchhorster.de/planmeca/romexis-admin:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-admin:<version>-arm64
--- gitea.buchhorster.de/planmeca/romexis-admin:<version>
gitea.buchhorster.de/planmeca/romexis-admin:latest
## Tagging Strategy
gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-amd64
### Base image gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>
Base images are architecture-specific: gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest
```text gitea.buchhorster.de/planmeca/romexis-migration-service:amd64
romexis-base-jre:11-amd64 gitea.buchhorster.de/planmeca/romexis-migration-service:arm64
romexis-base-jre:11-arm64 gitea.buchhorster.de/planmeca/romexis-migration-service:latest
``` ```
### Windows payload image ---
The Windows payload image is versioned by Romexis version: ## Tagging Strategy
```text ### Payload image
romexis-payload:6.5.3.444.203
``` The Windows payload image is versioned by Romexis version and is architecture-independent:
It is architecture-independent. ```text
romexis-payload:6.5.3.444.203
### Firebird payload image ```
The Firebird payload contains the currently maintained Firebird SQL payload and is consumed as a shared image: ### Base image
```text Base images are architecture-specific and also published as a manifest:
romexis-firebird-payload:latest
``` ```text
romexis-base-jre:11-amd64
The Firebird SQL payload is not tied to the server image architecture. romexis-base-jre:11-arm64
romexis-base-jre:11
### Server image ```
Server images are architecture-specific and also published as a multi-architecture manifest: ### Server image
```text Server images are architecture-specific and published as a multi-architecture manifest:
romexis-server:6.5.3.444.203-amd64
romexis-server:6.5.3.444.203-arm64 ```text
romexis-server:6.5.3.444.203 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 ### Admin image
```bash The Admin image uses the Romexis payload and provides the browser/noVNC Admin runtime:
docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-amd64
``` ```text
romexis-admin:<version>-amd64
For multiarch usage: romexis-admin:<version>-arm64
romexis-admin:<version>
```bash romexis-admin:latest
docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203 ```
```
### mRomexis Web App image
---
The mRomexis Web App image is versioned by Romexis version:
## Local Tagging
```text
If Docker Compose expects a registry image but you built locally, tag it accordingly: romexis-mromexis-app:<version>-amd64
romexis-mromexis-app:<version>-arm64
```bash romexis-mromexis-app:<version>
docker tag romexis-server:local gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-amd64 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 # Database Backends
Romexis supports multiple database backends. This Docker project currently treats Microsoft SQL Server as the default backend and Firebird as the parallel backend under development. Romexis supports multiple database backends. This Docker project currently treats Microsoft SQL Server as the default backend and Firebird as a parallel backend through a dedicated Compose override.
--- ---
## Backend Identifiers ## Compose Backend Selection
| `SERVER_DB` | Backend | The database backend is selected in `.env` with `DATABASE_BACKEND` and `COMPOSE_FILE`.
|---|---|
| `5` | Microsoft SQL Server | ### Microsoft SQL Server
| `4` | Firebird |
```env
--- DATABASE_BACKEND=mssql
COMPOSE_PATH_SEPARATOR=:
## Initialization Scripts COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
```
The initialization entry point is:
### Firebird
```text
/opt/init-romexis-db.sh ```env
``` DATABASE_BACKEND=firebird
COMPOSE_PATH_SEPARATOR=:
This script routes to: COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
```
```text
/opt/init-romexis-mssql-db.sh The backend-specific Compose override sets the actual Romexis backend variables.
/opt/init-romexis-firebird-db.sh
``` ---
--- ## Backend Identifiers
## Version-Aware Initialization Romexis itself still uses `SERVER_DB` internally.
The backend scripts read: | `SERVER_DB` | Backend |
|---|---|
```text | `5` | Microsoft SQL Server |
/opt/romexis/version | `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.
Example:
---
```text
6.5.3.444.203 ## Backend Services
```
### MSSQL
They resolve the target schema marker using the explicit Romexis update order.
The MSSQL override starts the `mssql` service and configures Romexis to connect to:
Example:
```text
```text mssql:1433
6.5.3 -> 653 ```
6.5.2 -> 652
6.5.1 -> 651 Typical values:
6.4.x -> 64
3.8.3 -> 383 ```env
``` MSSQL_SA_PASSWORD=Pwr0mex!s!!!
ROMEXIS_DB_NAME=Romexis_db
The scripts do not rely on plain numeric order because Romexis update markers do not sort naturally. ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=romexis
Example: ```
```text ### Firebird
6.0 -> 600
6.1 -> 610 The Firebird override starts the `firebird` service and configures Romexis to connect through Jaybird.
6.3 -> 63
6.4 -> 64 Typical values:
```
```env
--- FIREBIRD_USER=sysdba
FIREBIRD_PASSWORD=pwr0mex!
## Maximum Schema Version FIREBIRD_DB_PATH=/firebird/data/romexis.fdb
```
Use:
---
```env
ROMEXIS_DB_MAX_VERSION=653 ## Initialization Scripts
```
The initialization entry point is:
If the Romexis version is newer than the configured maximum marker, initialization continues only up to the max marker and prints a warning.
```text
--- /opt/init-romexis-db.sh
```
## Existing Databases
This script routes to:
If the database already appears initialized, initialization is skipped.
```text
For MSSQL, this is based on database and user presence. /opt/init-romexis-mssql-db.sh
/opt/init-romexis-firebird-db.sh
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. ---
## 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 # Developer Guide
This page describes the internal project structure and development workflow. This page describes the internal project structure and development workflow.
--- ---
## Main Project Directories ## Main Project Directories
```text ```text
romexis-base/ romexis-base/
Runtime base image. Runtime base image.
romexis-payload/ romexis-payload/
Windows installer payload extraction. Windows installer payload extraction.
romexis-firebird-payload/ romexis-firebird-payload/
macOS Firebird SQL payload extraction. macOS Firebird SQL payload extraction.
romexis/ romexis/
Final Romexis Server image. Final Romexis Server image.
migration-service/ migration-service/
Migration Web UI, REST API, SFTP and restore orchestration. Migration Web UI, REST API, SFTP and restore orchestration.
migration-client/ migration-client/
Source-side migration helper client. Source-side migration helper client.
docs/ docs/
Extended markdown documentation. Extended markdown documentation.
``` ```
--- ---
## Development Principles ## Development Principles
- Keep proprietary binaries out of Git. - Keep proprietary binaries out of Git.
- Keep installer extraction in payload images. - Keep installer extraction in payload images.
- Keep runtime dependencies in the base image. - Keep runtime dependencies in the base image.
- Keep final server image focused on assembly and runtime logic. - Keep final server image focused on assembly and runtime logic.
- Keep MSSQL and Firebird initialization separated. - Keep MSSQL and Firebird initialization separated.
- Use the wrapper script only for backend routing. - Use the wrapper script only for backend routing.
- Prefer explicit validation over silent incomplete images. - Prefer explicit validation over silent incomplete images.
--- ---
## Database Init Scripts ## Database Init Scripts
```text ```text
init-romexis-db.sh init-romexis-db.sh
Routes to backend-specific init script. Routes to backend-specific init script.
init-romexis-mssql-db.sh init-romexis-mssql-db.sh
Handles SQL Server initialization. Handles SQL Server initialization.
init-romexis-firebird-db.sh init-romexis-firebird-db.sh
Handles Firebird initialization. Handles Firebird initialization.
``` ```
--- ---
## Version-Aware Database Updates ## Version-Aware Database Updates
The database init scripts use an explicit Romexis update order. The database init scripts use an explicit Romexis update order.
This is required because markers do not sort numerically. This is required because markers do not sort numerically.
Example: Example:
```text ```text
600, 610, 63, 64, 651, 652, 653 600, 610, 63, 64, 651, 652, 653
``` ```
The script resolves the target marker from `/opt/romexis/version` and runs updates until that marker. The script resolves the target marker from `/opt/romexis/version` and runs updates until that marker.
--- ---
## Testing Image Contents ## Testing Image Contents
```bash ```bash
docker run --rm --entrypoint find \ docker run --rm --entrypoint find \
gitea.buchhorster.de/planmeca/romexis-server:<tag> \ gitea.buchhorster.de/planmeca/romexis-server:<tag> \
/opt -maxdepth 3 -type f | sort /opt -maxdepth 3 -type f | sort
``` ```
Open shell: Open shell:
```bash ```bash
docker run --rm -it --entrypoint bash \ docker run --rm -it --entrypoint bash \
gitea.buchhorster.de/planmeca/romexis-server:<tag> gitea.buchhorster.de/planmeca/romexis-server:<tag>
``` ```
--- ---
## Local Debug Compose Override ## Local Debug Compose Override
```yaml ```yaml
services: services:
romexis: romexis:
entrypoint: entrypoint:
- /bin/bash - /bin/bash
- -c - -c
- sleep infinity - sleep infinity
stdin_open: true stdin_open: true
tty: true tty: true
``` ```
Then: Then:
```bash ```bash
docker compose exec romexis bash docker compose exec romexis bash
``` ```
FAQ.md
+74 -74
@@ -1,74 +1,74 @@
# FAQ # FAQ
## Are Romexis binaries stored in Git? ## Are Romexis binaries stored in Git?
No. The repository does not store proprietary Romexis application binaries. No. The repository does not store proprietary Romexis application binaries.
The build system downloads official installer packages and extracts required files during payload builds. The build system downloads official installer packages and extracts required files during payload builds.
--- ---
## Why use payload images? ## Why use payload images?
Payload images avoid repeated installer downloads and decouple installer extraction from final server image assembly. Payload images avoid repeated installer downloads and decouple installer extraction from final server image assembly.
--- ---
## Why is Firebird payload shared as latest? ## 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. 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? ## What is the default database backend?
Microsoft SQL Server. Microsoft SQL Server.
Use: Use:
```env ```env
SERVER_DB=5 SERVER_DB=5
``` ```
--- ---
## How do I enable Firebird? ## How do I enable Firebird?
Use: Use:
```env ```env
SERVER_DB=4 SERVER_DB=4
FIREBIRD_PASSWORD=pwr0mex! FIREBIRD_PASSWORD=pwr0mex!
ROMEXIS_DB_USER=sysdba ROMEXIS_DB_USER=sysdba
ROMEXIS_DB_PASSWORD=pwr0mex! ROMEXIS_DB_PASSWORD=pwr0mex!
``` ```
and start the Firebird Compose variant. and start the Firebird Compose variant.
--- ---
## Why does Firebird init use isql-fb? ## Why does Firebird init use isql-fb?
Because `isql` may be unixODBC's tool. Firebird's CLI is commonly named: Because `isql` may be unixODBC's tool. Firebird's CLI is commonly named:
```text ```text
isql-fb isql-fb
``` ```
--- ---
## Can I run on ARM64? ## 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. 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? ## Can I migrate from an existing Windows Romexis server?
Yes, this is the purpose of the migration service and migration client workflow. Yes, this is the purpose of the migration service and migration client workflow.
--- ---
## Should completed migration jobs still have SFTP users? ## 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. 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
Firebird support is being introduced as a parallel database backend. 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. This is especially relevant because macOS-based Romexis installations use Firebird and because Firebird is a realistic path for ARM64 environments.
--- ---
## Compose Service ## Compose Service
Recommended Firebird service: Recommended Firebird service:
```yaml ```yaml
firebird: firebird:
image: jacobalberty/firebird:3.0 image: jacobalberty/firebird:3.0
container_name: romexis-firebird container_name: romexis-firebird
environment: environment:
ISC_PASSWORD: "${FIREBIRD_PASSWORD}" ISC_PASSWORD: "${FIREBIRD_PASSWORD}"
FIREBIRD_DATABASE: "romexis.fdb" FIREBIRD_DATABASE: "romexis.fdb"
ports: ports:
- "${FIREBIRD_PORT:-3050}:3050" - "${FIREBIRD_PORT:-3050}:3050"
volumes: volumes:
- ${ROMEXIS_DATA_ROOT}/firebird:/firebird/data - ${ROMEXIS_DATA_ROOT}/firebird:/firebird/data
healthcheck: healthcheck:
test: ["CMD-SHELL", "nc -z localhost 3050 || exit 1"] test: ["CMD-SHELL", "nc -z localhost 3050 || exit 1"]
interval: 10s interval: 10s
timeout: 5s timeout: 5s
retries: 30 retries: 30
start_period: 20s start_period: 20s
restart: unless-stopped restart: unless-stopped
``` ```
Do not configure the container to create a second `SYSDBA` user. `SYSDBA` already exists. Do not configure the container to create a second `SYSDBA` user. `SYSDBA` already exists.
--- ---
## Romexis Settings ## Romexis Settings
```env ```env
SERVER_DB=4 SERVER_DB=4
FIREBIRD_PORT=3050 FIREBIRD_PORT=3050
FIREBIRD_USER=sysdba FIREBIRD_USER=sysdba
FIREBIRD_PASSWORD=pwr0mex! FIREBIRD_PASSWORD=pwr0mex!
FIREBIRD_DB_PATH=/firebird/data/romexis.fdb FIREBIRD_DB_PATH=/firebird/data/romexis.fdb
ROMEXIS_DB_USER=sysdba ROMEXIS_DB_USER=sysdba
ROMEXIS_DB_PASSWORD=pwr0mex! ROMEXIS_DB_PASSWORD=pwr0mex!
``` ```
Generated JDBC URL: Generated JDBC URL:
```text ```text
jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb
``` ```
--- ---
## Firebird SQL Payload ## Firebird SQL Payload
The Firebird SQL payload is extracted from the macOS Romexis installer and stored in: The Firebird SQL payload is extracted from the macOS Romexis installer and stored in:
```text ```text
/opt/romexis-firebird-db /opt/romexis-firebird-db
``` ```
Important files: Important files:
```text ```text
scripts/RX_Create_Database.sql scripts/RX_Create_Database.sql
scripts/RX_Base_10fb_MAC.sql scripts/RX_Base_10fb_MAC.sql
scripts/rxdb.sh scripts/rxdb.sh
scripts/rxupd.sh scripts/rxupd.sh
tools/Romexis_Firebird_Backup.sh tools/Romexis_Firebird_Backup.sh
tools/Romexis_Firebird_Restore.sh tools/Romexis_Firebird_Restore.sh
templates/romexis_new.fdb templates/romexis_new.fdb
``` ```
--- ---
## Important Tooling Note ## Important Tooling Note
The Firebird CLI tool should be: The Firebird CLI tool should be:
```text ```text
isql-fb isql-fb
``` ```
not unixODBC `isql`. not unixODBC `isql`.
If you see this output: If you see this output:
```text ```text
unixODBC - isql and iusql unixODBC - isql and iusql
``` ```
then the wrong tool is being used. then the wrong tool is being used.
Set: Set:
```bash ```bash
export ISQL=isql-fb export ISQL=isql-fb
``` ```
or make the init script default to: or make the init script default to:
```bash ```bash
ISQL="${ISQL:-isql-fb}" ISQL="${ISQL:-isql-fb}"
``` ```
--- ---
## Database Creation Strategy ## Database Creation Strategy
If the Firebird container creates an empty database via: If the Firebird container creates an empty database via:
```yaml ```yaml
FIREBIRD_DATABASE: "romexis.fdb" FIREBIRD_DATABASE: "romexis.fdb"
``` ```
then the Romexis Firebird init script should not run `CREATE DATABASE` again. 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. Instead, it should connect to the existing empty database and import the Romexis SQL scripts.
--- ---
## Debugging Firebird Initialization ## Debugging Firebird Initialization
Open a shell in the Romexis container: Open a shell in the Romexis container:
```bash ```bash
docker exec -it romexis-server bash docker exec -it romexis-server bash
``` ```
Run the initializer manually: Run the initializer manually:
```bash ```bash
ISQL=isql-fb DB_CREATE_VERBOSE=1 bash -x /opt/init-romexis-firebird-db.sh ISQL=isql-fb DB_CREATE_VERBOSE=1 bash -x /opt/init-romexis-firebird-db.sh
``` ```
Check connectivity: Check connectivity:
```bash ```bash
bash -c ':</dev/tcp/firebird/3050' bash -c ':</dev/tcp/firebird/3050'
``` ```
Connect manually: Connect manually:
```bash ```bash
isql-fb -user sysdba -password 'pwr0mex!' firebird/3050:/firebird/data/romexis.fdb isql-fb -user sysdba -password 'pwr0mex!' firebird/3050:/firebird/data/romexis.fdb
``` ```
Home.md
+110 -76
@@ -1,76 +1,110 @@
# Romexis Docker Wiki # Romexis Docker Wiki
Welcome to the Romexis Docker project 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 wiki documents the Docker-based Romexis runtime stack, the backend-specific Compose layout, the local build scripts, the payload image architecture, the Romexis Admin container, the mRomexis Web App container, database backends, migration tooling and CI/CD workflow.
> This project provides a reproducible Docker environment for running Planmeca Romexis Server on Linux, MacOS or WSL with Windows while keeping the build process close to the original installer layout. Romexis application binaries are not stored in the repository. They are extracted from official installer packages during the build process. > This project provides a reproducible Docker environment for running Planmeca Romexis Server on Linux, macOS or WSL with Windows while keeping the build process close to the original installer layout. Romexis application binaries are not stored in the repository. They are extracted from official installer packages during the build process.
--- ---
## Main Areas ## Main Areas
| Area | Description | | Area | Description |
|---|---| |---|---|
| [Project Overview](Project-Overview) | High-level goals, features and supported platforms | | [Project Overview](Project-Overview) | High-level goals, features and supported platforms |
| [Architecture](Architecture) | Image layers, runtime containers and data flow | | [Architecture](Architecture) | Image layers, runtime containers and data flow |
| [Quick Start](Quick-Start) | Minimal steps to run the stack | | [Quick Start](Quick-Start) | Minimal steps to run the stack |
| [Configuration](Configuration) | Environment variables and runtime configuration | | [Compose Runtime](Compose-Runtime) | Base Compose file, backend overrides and `.env` selection |
| [Container Images](Container-Images) | Registry images, tags and manifests | | [Configuration](Configuration) | Environment variables and runtime configuration |
| [Build System](Build-System) | Payload, base and server build workflow | | [Container Images](Container-Images) | Registry images, tags, manifests and branch suffixes |
| [Database Backends](Database-Backends) | MSSQL and Firebird database architecture | | [Romexis Admin](Romexis-Admin) | Browser-based RomexisConfig/Admin container via noVNC |
| [Migration Service](Migration-Service) | Web UI, REST API, SFTP and restore workflow | | [mRomexis Web App](mRomexis-WebApp) | Separate Tomcat-based mRomexis Web frontend container |
| [Migration Workflow](Migration-Workflow) | Manual and client-assisted migration process | | [Build System](Build-System) | Payload, base, server, admin and web app build workflow |
| [CI/CD Pipeline](CI-CD-Pipeline) | Drone pipeline and publishing process | | [Local Build Scripts](Local-Build-Scripts) | Local build helper scripts for Linux/macOS and Windows |
| [Developer Guide](Developer-Guide) | Repository structure and internal development notes | | [Database Backends](Database-Backends) | MSSQL and Firebird backend architecture |
| [Troubleshooting](Troubleshooting) | Common errors and fixes | | [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 |
## Current Core Components | [Troubleshooting](Troubleshooting) | Common errors and fixes |
```text ---
romexis-payload/
Builds architecture-independent payload images from the official Windows installer. ## Current Core Components
romexis-firebird-payload/ ```text
Builds a Firebird SQL payload from the official macOS installer. romexis-payload/
Builds architecture-independent payload images from the official Windows installer.
romexis-base/
Builds the reusable Java 11 runtime base image. romexis-firebird-payload/
Builds a Firebird SQL payload from the official macOS installer.
romexis/
Builds the final Romexis Server image. romexis-base/
Builds the reusable Java 11 runtime base image.
migration-service/
Provides browser-based and API-driven migration orchestration. romexis/
Builds the final Romexis Server image.
migration-client/
Provides the Windows migration helper client. romexis-admin/
Builds the browser-accessible Romexis Admin / RomexisConfig container.
docs/
Contains extended project documentation. 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.
## Recommended Reading Order
migration-client/
1. [Project Overview](Project-Overview) Provides the Windows migration helper client.
2. [Architecture](Architecture)
3. [Quick Start](Quick-Start) scripts/
4. [Configuration](Configuration) Contains local build helpers such as build-local.sh and build-local.ps1.
5. [Database Backends](Database-Backends) ```
6. [Migration Service](Migration-Service)
7. [Build System](Build-System) ---
8. [Developer Guide](Developer-Guide)
## Current Runtime Layout
---
The runtime is split into a base Compose file and backend-specific override files:
## Important Notes
```text
- No Romexis application binaries are committed to the repository. docker-compose.yml
- Official Planmeca installer packages are downloaded during payload builds. Base runtime services and shared configuration.
- Microsoft SQL Server remains the default and most tested backend.
- Firebird support is being introduced in parallel for macOS/ARM64-oriented scenarios. docker-compose.mssql.yml
- The migration service is designed for moving existing Windows-based Romexis installations into the Docker stack. 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
Microsoft SQL Server is the default and most tested database backend. Microsoft SQL Server is the default and most tested database backend.
--- ---
## Compose Service ## Compose Service
The MSSQL service uses the official Microsoft SQL Server image: The MSSQL service uses the official Microsoft SQL Server image:
```yaml ```yaml
mssql: mssql:
image: mcr.microsoft.com/mssql/server:2022-latest image: mcr.microsoft.com/mssql/server:2022-latest
container_name: romexis-mssql container_name: romexis-mssql
environment: environment:
ACCEPT_EULA: "Y" ACCEPT_EULA: "Y"
MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}" MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}"
MSSQL_PID: "${MSSQL_PID:-Express}" MSSQL_PID: "${MSSQL_PID:-Express}"
ports: ports:
- "${MSSQL_PORT}:1433" - "${MSSQL_PORT}:1433"
volumes: volumes:
- mssql_data:/var/opt/mssql - mssql_data:/var/opt/mssql
- ${DATABASE_BACKUP_DIR}:/var/opt/mssql/backup - ${DATABASE_BACKUP_DIR}:/var/opt/mssql/backup
``` ```
--- ---
## Romexis Settings ## Romexis Settings
```env ```env
SERVER_DB=5 SERVER_DB=5
MSSQL_HOST=mssql MSSQL_HOST=mssql
MSSQL_PORT=1433 MSSQL_PORT=1433
MSSQL_SA_PASSWORD=<strong-password> MSSQL_SA_PASSWORD=<strong-password>
ROMEXIS_DB_NAME=Romexis_db ROMEXIS_DB_NAME=Romexis_db
ROMEXIS_DB_USER=romexis ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=<strong-password> ROMEXIS_DB_PASSWORD=<strong-password>
``` ```
Generated JDBC URL: Generated JDBC URL:
```text ```text
jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true; jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;
``` ```
--- ---
## Initialization ## Initialization
The MSSQL initializer: The MSSQL initializer:
```text ```text
/opt/init-romexis-mssql-db.sh /opt/init-romexis-mssql-db.sh
``` ```
Responsibilities: Responsibilities:
- wait for SQL Server - wait for SQL Server
- create Romexis database if missing - create Romexis database if missing
- create/update Romexis database user - create/update Romexis database user
- import base SQL scripts - import base SQL scripts
- import update scripts up to the target schema marker - import update scripts up to the target schema marker
- update runtime paths in `RBA_Server_Param_S` - update runtime paths in `RBA_Server_Param_S`
--- ---
## Backup Directory ## Backup Directory
`DATABASE_BACKUP_DIR` is mounted into both the migration service and SQL Server: `DATABASE_BACKUP_DIR` is mounted into both the migration service and SQL Server:
```text ```text
Migration service: /upload/database Migration service: /upload/database
SQL Server: /var/opt/mssql/backup SQL Server: /var/opt/mssql/backup
``` ```
This allows the migration service to upload a `.bak` file and trigger a database restore. 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 # Migration Client
The migration client is the source-side helper for guided migrations from existing Romexis installations. The migration client is the source-side helper for guided migrations from existing Romexis installations.
Current direction: Current direction:
```text ```text
Windows client first Windows client first
Future: evaluate C# for broader platform support Future: evaluate C# for broader platform support
``` ```
--- ---
## Responsibilities ## Responsibilities
The client should help with: The client should help with:
- detecting local Romexis installation paths - detecting local Romexis installation paths
- detecting SQL Server connection settings - detecting SQL Server connection settings
- creating a database backup - creating a database backup
- detecting Romexis image and ergo data directories - detecting Romexis image and ergo data directories
- creating a migration job through the migration service API - creating a migration job through the migration service API
- uploading data through rclone/SFTP - uploading data through rclone/SFTP
- calling API endpoints to advance workflow state - calling API endpoints to advance workflow state
- displaying progress and logs - displaying progress and logs
--- ---
## Why rclone? ## Why rclone?
rclone is suitable for large migrations because it supports: rclone is suitable for large migrations because it supports:
- SFTP - SFTP
- progress output - progress output
- retries - retries
- resumable workflows - resumable workflows
- directory synchronization - directory synchronization
- configurable transfers/checkers - configurable transfers/checkers
--- ---
## Python vs C# Direction ## Python vs C# Direction
The initial client is Python-based because it is fast to develop and easy to integrate with existing scripts. 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: For future macOS support, C# may become the better long-term option because it can provide:
- native Windows build - native Windows build
- possible macOS build - possible macOS build
- stronger GUI options - stronger GUI options
- easier single-binary packaging - easier single-binary packaging
- better long-term maintainability for a desktop migration client - better long-term maintainability for a desktop migration client
The README should keep this as an architectural direction, not as a completed feature. 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 # Migration Service
The Romexis Migration Service helps migrate an existing Romexis installation into the Docker-based Romexis Server stack. The Romexis Migration Service helps migrate an existing Romexis installation into the Docker-based Romexis Server stack.
It provides: It provides:
- Flask Web UI - Flask Web UI
- REST API - REST API
- temporary SFTP users - temporary SFTP users
- migration job state tracking - migration job state tracking
- database backup upload - database backup upload
- manifest creation - manifest creation
- upload validation - upload validation
- restore orchestration - restore orchestration
- final completion/cancellation workflow - final completion/cancellation workflow
--- ---
## Why a Migration Service? ## Why a Migration Service?
Romexis installations can contain: Romexis installations can contain:
- large SQL Server backups - large SQL Server backups
- large image directories - large image directories
- ergo data directories - ergo data directories
- cache directories - cache directories
- many small files - many small files
Browser uploads alone are not ideal for this. Therefore the migration service combines: Browser uploads alone are not ideal for this. Therefore the migration service combines:
```text ```text
Web UI / API Web UI / API
for orchestration and state for orchestration and state
SFTP SFTP
for large file and directory transfer for large file and directory transfer
``` ```
--- ---
## Migration Job State ## Migration Job State
Migration jobs are stored as JSON state files. Migration jobs are stored as JSON state files.
Typical workflow: Typical workflow:
```text ```text
created created
-> database_uploaded -> database_uploaded
-> database_restored -> database_restored
-> upload_complete -> upload_complete
-> validated -> validated
-> restored -> restored
-> completed -> completed
``` ```
Final states: Final states:
```text ```text
completed completed
cancelled cancelled
failed failed
``` ```
--- ---
## SFTP User Lifecycle ## SFTP User Lifecycle
The service creates one temporary SFTP user per active migration. The service creates one temporary SFTP user per active migration.
Important behavior: Important behavior:
- active jobs recreate SFTP users on service startup - active jobs recreate SFTP users on service startup
- completed jobs should not recreate SFTP users - completed jobs should not recreate SFTP users
- cancelled jobs should not recreate SFTP users - cancelled jobs should not recreate SFTP users
- failed jobs should not recreate SFTP users unless intentionally reactivated - failed jobs should not recreate SFTP users unless intentionally reactivated
- completing or cancelling a job removes or disables the temporary SFTP access - completing or cancelling a job removes or disables the temporary SFTP access
--- ---
## Manual Browser Workflow ## Manual Browser Workflow
1. Create migration job in the Web UI. 1. Create migration job in the Web UI.
2. Upload database backup through the browser. 2. Upload database backup through the browser.
3. The service creates `manifest.json` automatically. 3. The service creates `manifest.json` automatically.
4. Trigger database restore. 4. Trigger database restore.
5. Upload file directories through SFTP. 5. Upload file directories through SFTP.
6. Mark upload as complete. 6. Mark upload as complete.
7. Validate upload. 7. Validate upload.
8. Run restore. 8. Run restore.
9. Complete migration and remove SFTP access. 9. Complete migration and remove SFTP access.
--- ---
## SFTP Upload ## SFTP Upload
The Web UI shows the SFTP credentials and example commands. The Web UI shows the SFTP credentials and example commands.
Typical rclone setup: Typical rclone setup:
```bash ```bash
rclone config create romexis-migration sftp \ rclone config create romexis-migration sftp \
host <host> \ host <host> \
port <port> \ port <port> \
user <username> \ user <username> \
pass "$(rclone obscure '<password>')" pass "$(rclone obscure '<password>')"
``` ```
Upload images: Upload images:
```bash ```bash
rclone sync "/PATH/TO/LOCAL/romexis_images" \ rclone sync "/PATH/TO/LOCAL/romexis_images" \
"romexis-migration:/romexis_images" \ "romexis-migration:/romexis_images" \
--progress \ --progress \
--transfers 4 \ --transfers 4 \
--checkers 8 --checkers 8
``` ```
Upload ergo data: Upload ergo data:
```bash ```bash
rclone sync "/PATH/TO/LOCAL/romexis_ergodata" \ rclone sync "/PATH/TO/LOCAL/romexis_ergodata" \
"romexis-migration:/romexis_ergodata" \ "romexis-migration:/romexis_ergodata" \
--progress \ --progress \
--transfers 4 \ --transfers 4 \
--checkers 8 --checkers 8
``` ```
Optional cache upload: Optional cache upload:
```bash ```bash
rclone sync "/PATH/TO/LOCAL/romexis_cache" \ rclone sync "/PATH/TO/LOCAL/romexis_cache" \
"romexis-migration:/romexis_cache" \ "romexis-migration:/romexis_cache" \
--progress \ --progress \
--transfers 4 \ --transfers 4 \
--checkers 8 --checkers 8
``` ```
--- ---
## Restart Coordination ## Restart Coordination
The migration service and Romexis container coordinate restarts using a shared state file: The migration service and Romexis container coordinate restarts using a shared state file:
```text ```text
/data/romexis_images/.romexis_restart_state /data/romexis_images/.romexis_restart_state
``` ```
The migration service writes a pending restart request. The migration service writes a pending restart request.
The Romexis entrypoint/process observes the state, restarts the Romexis service and writes the result. 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. The migration service reads the result and removes the state file.
Migration-Workflow.md
+163 -163
@@ -1,163 +1,163 @@
# Migration Workflow # Migration Workflow
This page describes the target migration workflow from an existing Romexis server into the Docker-based Romexis stack. This page describes the target migration workflow from an existing Romexis server into the Docker-based Romexis stack.
--- ---
## Source System ## Source System
The source system is usually a Windows-based Romexis server. The source system is usually a Windows-based Romexis server.
Required data: Required data:
```text ```text
SQL Server database backup (.bak) SQL Server database backup (.bak)
Romexis image directory Romexis image directory
Romexis ergo data directory Romexis ergo data directory
optional Romexis cache directory optional Romexis cache directory
``` ```
The cache directory is optional because it can usually be regenerated. The cache directory is optional because it can usually be regenerated.
--- ---
## Target System ## Target System
The target system runs: The target system runs:
```text ```text
Romexis Server container Romexis Server container
Database backend container Database backend container
Migration Service container Migration Service container
Persistent data volumes Persistent data volumes
``` ```
--- ---
## Workflow Overview ## Workflow Overview
```text ```text
Existing Romexis Server Existing Romexis Server
| |
| database backup | database backup
| image data | image data
| ergo data | ergo data
v v
Romexis Migration Service Romexis Migration Service
| |
| validation | validation
| database restore | database restore
| data restore | data restore
v v
Docker-based Romexis Server Docker-based Romexis Server
``` ```
--- ---
## Manual Workflow ## Manual Workflow
1. Open the migration Web UI. 1. Open the migration Web UI.
2. Create a new migration job. 2. Create a new migration job.
3. Upload the database backup in the browser. 3. Upload the database backup in the browser.
4. Let the service create `manifest.json`. 4. Let the service create `manifest.json`.
5. Trigger database restore. 5. Trigger database restore.
6. Upload images and ergo data via SFTP. 6. Upload images and ergo data via SFTP.
7. Mark upload complete. 7. Mark upload complete.
8. Validate uploaded data. 8. Validate uploaded data.
9. Run restore. 9. Run restore.
10. Complete migration. 10. Complete migration.
11. SFTP credentials are removed or disabled. 11. SFTP credentials are removed or disabled.
--- ---
## Client-Assisted Workflow ## Client-Assisted Workflow
The migration client is intended to automate most source-side steps: The migration client is intended to automate most source-side steps:
1. detect Romexis installation 1. detect Romexis installation
2. detect database configuration 2. detect database configuration
3. detect data directories 3. detect data directories
4. create or use a migration job 4. create or use a migration job
5. create database backup 5. create database backup
6. upload data through rclone/SFTP 6. upload data through rclone/SFTP
7. call API endpoints to advance the workflow 7. call API endpoints to advance the workflow
8. show logs and restore status 8. show logs and restore status
--- ---
## Expected Upload Layout ## Expected Upload Layout
```text ```text
/upload/ /upload/
├── meta/ ├── meta/
│ └── manifest.json │ └── manifest.json
├── database/ ├── database/
│ └── Romexis_db.bak │ └── Romexis_db.bak
├── romexis_images/ ├── romexis_images/
├── romexis_ergodata/ ├── romexis_ergodata/
└── romexis_cache/ └── romexis_cache/
``` ```
--- ---
## Manifest ## Manifest
The manifest describes the uploaded migration data. The manifest describes the uploaded migration data.
Example: Example:
```json ```json
{ {
"migration_id": "example", "migration_id": "example",
"name": "Example Migration", "name": "Example Migration",
"source_host": "old-romexis-server", "source_host": "old-romexis-server",
"database": { "database": {
"backup": "database/Romexis_db.bak" "backup": "database/Romexis_db.bak"
}, },
"romexis_images": true, "romexis_images": true,
"romexis_ergodata": true, "romexis_ergodata": true,
"romexis_cache": false "romexis_cache": false
} }
``` ```
The manual browser workflow can generate this automatically after database upload. The manual browser workflow can generate this automatically after database upload.
--- ---
## Validation ## Validation
Validation should check: Validation should check:
- manifest exists - manifest exists
- database backup exists - database backup exists
- image directory exists - image directory exists
- ergo data directory exists - ergo data directory exists
- optional cache directory exists if requested - optional cache directory exists if requested
- file counts - file counts
- total bytes - total bytes
- future checksum data - future checksum data
--- ---
## Restore ## Restore
The restore step performs or coordinates: The restore step performs or coordinates:
1. database restore 1. database restore
2. file placement into target volumes 2. file placement into target volumes
3. permission fixes 3. permission fixes
4. Romexis restart 4. Romexis restart
5. final status reporting 5. final status reporting
--- ---
## Completion ## Completion
After successful restore, the job should be marked completed. After successful restore, the job should be marked completed.
Completion should: Completion should:
- remove or disable temporary SFTP user - remove or disable temporary SFTP user
- hide workflow action buttons - hide workflow action buttons
- keep logs available - keep logs available
- preserve migration state file for audit/debugging - preserve migration state file for audit/debugging
Payload-Images.md
+135 -135
@@ -1,135 +1,135 @@
# Payload Images # Payload Images
Payload images are reusable intermediate images containing extracted installer content. Payload images are reusable intermediate images containing extracted installer content.
--- ---
## Windows Payload ## Windows Payload
Directory: Directory:
```text ```text
romexis-payload/ romexis-payload/
``` ```
Purpose: Purpose:
- download official Windows installer - download official Windows installer
- extract required InstallShield CAB components - extract required InstallShield CAB components
- build `/opt/romexis` - build `/opt/romexis`
- extract MSSQL initialization SQL files - extract MSSQL initialization SQL files
- write `/opt/romexis/version` - write `/opt/romexis/version`
Output contract: Output contract:
```text ```text
/opt/romexis /opt/romexis
/opt/romexis-mssql-db /opt/romexis-mssql-db
/opt/romexis/version /opt/romexis/version
/opt/romexis/server/RomexisServer.jar /opt/romexis/server/RomexisServer.jar
``` ```
The payload must not contain architecture-specific runtime libraries like Chilkat. The payload must not contain architecture-specific runtime libraries like Chilkat.
--- ---
## Version File ## Version File
Supported Windows installer URLs are maintained in: Supported Windows installer URLs are maintained in:
```text ```text
romexis-payload/romexis-versions.env romexis-payload/romexis-versions.env
``` ```
Example: Example:
```text ```text
6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip 6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip
``` ```
--- ---
## Copy Map ## Copy Map
Installer extraction is controlled by: Installer extraction is controlled by:
```text ```text
romexis-payload/romexis-copy-map.tsv romexis-payload/romexis-copy-map.tsv
``` ```
Format: Format:
```text ```text
Source<TAB>Destination Source<TAB>Destination
``` ```
Example: Example:
```text ```text
Server_jar /opt/romexis/server Server_jar /opt/romexis/server
Server_Program_64bit/server/*.xml /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. When this mapping changes, all payload versions should be rebuilt because the extracted runtime layout may change.
--- ---
## Firebird Payload ## Firebird Payload
Directory: Directory:
```text ```text
romexis-firebird-payload/ romexis-firebird-payload/
``` ```
Purpose: Purpose:
- download official macOS DMG - download official macOS DMG
- extract PKG payloads - extract PKG payloads
- collect Firebird database SQL scripts - collect Firebird database SQL scripts
- collect original backup/restore helper scripts - collect original backup/restore helper scripts
- include `romexis_new.fdb` as reference/template - include `romexis_new.fdb` as reference/template
Output contract: Output contract:
```text ```text
/opt/romexis-firebird-db/version /opt/romexis-firebird-db/version
/opt/romexis-firebird-db/scripts /opt/romexis-firebird-db/scripts
/opt/romexis-firebird-db/tools /opt/romexis-firebird-db/tools
/opt/romexis-firebird-db/templates /opt/romexis-firebird-db/templates
/opt/romexis-firebird-db/layout /opt/romexis-firebird-db/layout
``` ```
Important files: Important files:
```text ```text
/opt/romexis-firebird-db/scripts/rxdb.sh /opt/romexis-firebird-db/scripts/rxdb.sh
/opt/romexis-firebird-db/scripts/rxupd.sh /opt/romexis-firebird-db/scripts/rxupd.sh
/opt/romexis-firebird-db/scripts/RX_Base_10fb_MAC.sql /opt/romexis-firebird-db/scripts/RX_Base_10fb_MAC.sql
/opt/romexis-firebird-db/scripts/RX_Update_653.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_Backup.sh
/opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh /opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh
/opt/romexis-firebird-db/templates/romexis_new.fdb /opt/romexis-firebird-db/templates/romexis_new.fdb
``` ```
--- ---
## Inspecting a Payload Image ## Inspecting a Payload Image
If a payload image is based on `scratch`, it may not have a shell. If a payload image is based on `scratch`, it may not have a shell.
Use: Use:
```bash ```bash
docker save gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest -o payload.tar docker save gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest -o payload.tar
mkdir payload rootfs mkdir payload rootfs
tar -xf payload.tar -C payload tar -xf payload.tar -C payload
tar -xf payload/<layer-id>/layer.tar -C rootfs tar -xf payload/<layer-id>/layer.tar -C rootfs
find rootfs/opt -type f | sort find rootfs/opt -type f | sort
``` ```
If the image includes a shell: If the image includes a shell:
```bash ```bash
docker run --rm -it --entrypoint sh gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest 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 # Project Overview
## Purpose ## Purpose
The Romexis Docker project provides a reproducible Docker-based environment for running Planmeca Romexis Server on Linux. The Romexis Docker project provides a reproducible Docker-based environment for running Planmeca Romexis Server on Linux.
The project is designed to: The project is designed to:
- run Romexis Server in containers - run Romexis Server in containers
- keep runtime configuration externalized - keep runtime configuration externalized
- avoid manual Windows-style setup steps - select the database backend through Docker Compose configuration
- support persistent application and database data - avoid manual Windows-style setup steps
- support migration from existing installations - support persistent application and database data
- support repeatable CI/CD builds - provide browser-based access to Romexis Admin / RomexisConfig
- prepare a path for both Microsoft SQL Server and Firebird database backends - 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
## Design Principles
---
### No Romexis binaries in Git
## Main Runtime Services
The repository does not contain Romexis application binaries.
```text
Instead, the build process downloads official installer packages and extracts only the required server components into payload images. romexis
Romexis Server backend runtime.
### Layered image architecture
mssql / firebird
The build system is split into reusable layers: Selected database backend loaded through Compose override files.
```text romexis-admin
Payload image Browser-accessible Romexis Admin / RomexisConfig runtime using noVNC.
Contains extracted Romexis application files and SQL payload.
romexis-app
Base image Tomcat-based mRomexis Web App container.
Contains reusable runtime dependencies such as Java, JavaFX and database tools.
proxy
Server image OpenResty/Nginx proxy for mRomexis Web App backend access.
Combines payload + base + runtime scripts + Java agent.
``` romexis-migration
Optional migration service for MSSQL-based migration workflows.
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. ## Design Principles
This allows the same payload to be reused for both: ### No Romexis binaries in Git
```text The repository does not contain Romexis application binaries.
linux/amd64
linux/arm64 Instead, the build process downloads official installer packages and extracts only the required server, admin and web components into payload images.
```
### Layered image architecture
### Database backend flexibility
The build system is split into reusable layers:
Microsoft SQL Server remains the default backend.
```text
Firebird support is being added in parallel because macOS-based Romexis installations use Firebird and because this path is more realistic for ARM64 environments. Payload image
Contains extracted Romexis application files, SQL payload and web/admin artifacts.
---
Base image
## Main Features Contains reusable runtime dependencies such as Java, JavaFX and database tools.
- Romexis Server 6.5 Docker runtime Service images
- Microsoft SQL Server 2022 support Build server, admin, migration and mRomexis runtime containers from the prepared layers.
- Firebird backend preparation ```
- automatic database initialization
- persistent runtime volumes ### Architecture-independent payloads
- Java Property Agent for runtime property injection
- versioned payload images The Romexis payload itself is architecture independent. Architecture-specific parts such as native libraries remain in service runtime images.
- multi-architecture base and server images
- Drone CI/CD pipeline The same payload can be reused for:
- migration service with Web UI, REST API and SFTP
- Windows migration client ```text
- Gitea package registry publishing linux/amd64
linux/arm64
--- ```
## Supported Platforms ### Compose-based backend selection
| Platform | Status | Database backends are selected through `.env`:
|---|---|
| linux/amd64 | Primary supported target | ```env
| linux/arm64 | Supported for Romexis runtime images | DATABASE_BACKEND=mssql
| Microsoft SQL Server on amd64 | Default backend | COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
| Firebird on amd64/arm64 | In progress / experimental | ```
| macOS source migrations | Planned through Firebird and client workflow |
The backend-specific Compose override sets the correct database service and Romexis database environment values.
---
---
## Repository Areas
## Main Features
```text
romexis-base/ - Romexis Server 6.5 Docker runtime
Reusable runtime base image. - Microsoft SQL Server 2022 backend
- Firebird backend through Compose override
romexis-payload/ - automatic database initialization
Windows installer payload extraction. - persistent runtime volumes
- Java Property Agent for server-side runtime property injection
romexis-firebird-payload/ - versioned payload images
macOS installer Firebird SQL payload extraction. - multi-architecture service images
- Romexis Admin container with browser/noVNC access
romexis/ - VNC-session-controlled Admin lifecycle
Final Romexis Server image. - localized Admin splash screen
- mRomexis Web App container for Romexis 6.5.3 and newer
migration-service/ - OpenResty/Nginx proxy for mRomexis backend requests
Migration orchestration service. - local build scripts for Linux/macOS and Windows
- Drone CI/CD pipeline
migration-client/ - migration service with Web UI, REST API and SFTP
Migration helper client. - Windows migration client
- Gitea package registry publishing
docs/
Extended documentation. ---
docker-compose.yml ## Supported Platforms
Default runtime stack.
| Platform | Status |
docker-compose.firebird.yml |---|---|
Firebird runtime variant. | linux/amd64 | Primary supported target |
| linux/arm64 | Supported for Romexis runtime images |
.drone.yml | Microsoft SQL Server on amd64 | Default backend |
CI/CD pipeline. | 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 # Project Structure
```text ```text
. .
├── .drone.yml ├── .drone.yml
├── .env.sample ├── .env.sample
├── docker-compose.yml ├── docker-compose.yml
├── docker-compose.firebird.yml ├── docker-compose.mssql.yml
├── README.md ├── docker-compose.firebird.yml
├── README.de.md ├── README.md
├── docs/ ├── README.de.md
│ ├── BUILD.md ├── BUILD.md
│ ├── DEVELOPERS.md ├── BUILD.de.md
│ ├── MIGRATION_README.md ├── DEVELOPERS.md
│ └── MIGRATION_WORKFLOW.md ├── scripts/
├── romexis-base/ │ ├── build-local.sh
│ └── Dockerfile │ └── build-local.ps1
├── romexis-payload/ ├── romexis-base/
│ ├── Dockerfile │ └── Dockerfile
│ ├── romexis-versions.env ├── romexis-payload/
│ ├── romexis-copy-map.tsv │ ├── Dockerfile
│ ├── download-romexis-installer-parts.py │ ├── romexis-versions.env
│ └── extract-and-copy-romexis-parts.sh │ ├── romexis-copy-map.tsv
├── romexis-firebird-payload/ │ ├── download-romexis-installer-parts.py
│ ├── Dockerfile │ └── extract-and-copy-romexis-parts.sh
│ ├── romexis-firebird-versions.env ├── romexis-firebird-payload/
│ └── helper scripts │ ├── Dockerfile
├── romexis/ │ ├── romexis-firebird-versions.env
│ ├── Dockerfile │ └── helper scripts
│ ├── entrypoint.sh ├── romexis/
│ ├── init-romexis-db.sh │ ├── Dockerfile
│ ├── init-romexis-mssql-db.sh │ ├── entrypoint.sh
│ ├── init-romexis-firebird-db.sh │ ├── init-romexis-db.sh
│ ├── fix-keystore-alias.sh │ ├── init-romexis-mssql-db.sh
│ └── RomexisPropertyAgent.java │ ├── init-romexis-firebird-db.sh
├── migration-service/ │ ├── fix-keystore-alias.sh
│ ├── Dockerfile │ └── RomexisPropertyAgent.java
│ ├── entrypoint.sh ├── romexis-admin/
│ ├── app/ │ ├── Dockerfile
│ ├── scripts/ │ ├── start.sh
│ └── ssh/ │ └── native helper sources
└── migration-client/ ├── romexis-mromexis-app/
└── client files │ ├── Dockerfile
``` │ └── nginx.conf
├── migration-service/
--- │ ├── Dockerfile
│ ├── entrypoint.sh
## Root README Files │ ├── app/
│ ├── scripts/
Only the main README files should stay at repository root: │ └── ssh/
└── migration-client/
```text └── client files
README.md ```
README.de.md
``` ---
Extended documentation belongs in: ## Compose Files
```text ```text
docs/ docker-compose.yml
``` Base runtime stack.
The wiki can then provide a navigable, user-facing documentation layer. 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 # Quick Start
## 1. Prepare environment ## 1. Prepare environment
Copy the sample environment file: Copy the sample environment file:
```bash ```bash
cp .env.sample .env cp .env.sample .env
``` ```
Edit `.env` and set at least: Edit `.env` and set at least the Romexis version, registry namespace, backend selection and passwords.
```env Minimal MSSQL example:
ROMEXIS_VERSION=6.5.3.444.203
TARGETARCH=amd64 ```env
REGISTRY=gitea.buchhorster.de/planmeca
REGISTRY=gitea.buchhorster.de/patrick ROMEXIS_VERSION=6.5.3.444.203
ROMEXIS_IMAGE=romexis-server IMAGE_SUFFIX=
HOST_IP=<your-server-ip> ROMEXIS_IMAGE=romexis-server
MIGRATION_IMAGE=romexis-migration-service
MSSQL_SA_PASSWORD=<strong-password> ADMINISTRATION_IMAGE=romexis-admin
ROMEXIS_DB_PASSWORD=<strong-password> MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app
```
DATABASE_BACKEND=mssql
or create minimal one COMPOSE_PATH_SEPARATOR=:
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
```env
ROMEXIS_VERSION=6.5.3.444.203 HOST_IP=192.168.65.100
TARGETARCH=amd64
MSSQL_PORT=1433
REGISTRY=gitea.buchhorster.de/planmeca MSSQL_SA_PASSWORD=Pwr0mex!s!!!
ROMEXIS_IMAGE=romexis-server MSSQL_PID=Express
MIGRATION_IMAGE=romexis-migration-service
ROMEXIS_DB_NAME=Romexis_db
SERVER_DB=5 ROMEXIS_DB_USER=romexis
ROMEXIS_DB_PASSWORD=romexis
HOST_IP=192.168.65.100 # Replace IP with Host IP
SERVER_RMI_LOW_PORT=1100
MSSQL_PORT=1433 SERVER_RMI_HIGH_PORT=1120
MSSQL_SA_PASSWORD=Pwr0mex!s!!!
MSSQL_PID=Express ROMEXIS_DATA_ROOT=/srv/romexis-data
DATABASE_BACKUP_DIR=/srv/romexis-data/sql-backup
ROMEXIS_DB_NAME=Romexis_db
ROMEXIS_DB_USER=romexis ADMIN_NOVNC_PORT=6080
ROMEXIS_DB_PASSWORD=romexis ADMIN_VNC_PORT=5900
ADMIN_VNC_PASSWORD=promax
SERVER_RMI_LOW_PORT=1100 ADMIN_RESOLUTION=1280x900x24
SERVER_RMI_HIGH_PORT=1120 ADMIN_LANGUAGE=de
DEBUG_XTERM=false
ROMEXIS_DATA_ROOT=/srv/romexis-data ADMIN_VNC_LIFECYCLE=true
DATABASE_BACKUP_DIR=/srv/mssql-backup
MROMEXIS_WEB_PORT=8081
MIGRATION_HTTP_PORT=8080
MIGRATION_SFTP_PORT=2222 MIGRATION_HTTP_PORT=8080
MIGRATION_API_TOKEN=change-me MIGRATION_SFTP_PORT=2222
``` MIGRATION_API_TOKEN=change-me
```
--- For Firebird, change the backend selection:
## 2. Start default MSSQL stack ```env
DATABASE_BACKEND=firebird
```bash COMPOSE_PATH_SEPARATOR=:
docker compose up -d COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
``` ```
Show logs: ---
```bash ## 2. Start the selected stack
docker compose logs -f romexis
docker compose logs -f mssql After `.env` is configured, the same command is used for MSSQL and Firebird:
```
```bash
--- docker compose up -d
```
## 3. Start Firebird stack
Show the effective Compose configuration:
If using the Firebird compose variant (with firebird setiings in .env file):
```bash
```bash docker compose config
docker compose -f docker-compose.firebird.yml up -d ```
```
---
Or combine the base compose file with a Firebird override:
## 3. Show logs
```bash
docker compose -f docker-compose.yml -f docker-compose.firebird.yml up -d ```bash
``` docker compose logs -f romexis
```
---
Database backend logs:
## 4. Recreate after image changes
```bash
```bash docker compose logs -f mssql
docker compose up --force-recreate -d # or
``` docker compose logs -f firebird
```
With rebuild:
Admin container logs:
```bash
docker compose up --build --force-recreate -d ```bash
``` docker compose logs -f romexis-admin
```
No cache rebuild:
mRomexis Web App logs:
```bash
docker compose build --no-cache --pull ```bash
docker compose up --force-recreate -d docker compose logs -f romexis-app
``` ```
--- ---
## 5. Open a shell in the Romexis container ## 4. Open browser-based services
```bash Romexis Admin / RomexisConfig through noVNC:
docker exec -it romexis-server bash
``` ```text
http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true
If bash is unavailable: ```
```bash mRomexis Web App through the proxy:
docker exec -it romexis-server sh
``` ```text
http://localhost:8081
With Compose: ```
```bash Adjust the ports if `ADMIN_NOVNC_PORT` or `MROMEXIS_WEB_PORT` were changed in `.env`.
docker compose exec romexis bash
``` ---
--- ## 5. Recreate after image changes
## 6. Check database initialization ```bash
docker compose up -d --force-recreate
Inside the Romexis container: ```
```bash Pull and recreate:
/opt/init-romexis-db.sh
``` ```bash
docker compose pull
Verbose database initialization: docker compose up -d --force-recreate
```
```bash
DB_CREATE_VERBOSE=1 /opt/init-romexis-db.sh ---
```
## 6. Open shells for debugging
For Firebird debugging:
Romexis server:
```bash
ISQL=isql-fb DB_CREATE_VERBOSE=1 bash -x /opt/init-romexis-firebird-db.sh ```bash
``` docker compose exec romexis bash
```
---
Admin image shell:
## 7. Stop the stack
```bash
```bash docker compose run --rm --entrypoint /bin/bash romexis-admin
docker compose down ```
```
mRomexis Web App shell:
Stop and remove volumes:
```bash
```bash docker compose run --rm --entrypoint /bin/bash romexis-app
docker compose down -v ```
```
---
Use volume removal carefully because it deletes persistent database/application data.
## 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) [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: Das Build-System ist darauf ausgelegt, folgende Ziele zu erfüllen:
- reproduzierbare Docker-Builds - reproduzierbare Docker-Builds
- wiederverwendbares Runtime-Basisimage - wiederverwendbare Image-Schichten
- lokale Entwickler-Builds über Skripte
- native `amd64`- und `arm64`-Images - native `amd64`- und `arm64`-Images
- Multiarch-Manifeste - Multiarch-Manifeste
- minimale finale Runtime-Images - minimale finale Runtime-Images
- wartbare Installer-Extraktionslogik - 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 ### Romexis Base Image
Das Base Image wird aus `romexis-base/Dockerfile` gebaut. Gebaut aus:
Es enthält gemeinsame Laufzeitabhängigkeiten: ```text
romexis-base/Dockerfile
```
- Azul Zulu Java 11 Runtime mit JavaFX/OpenJFX-Unterstützung Enthält gemeinsame Server-Laufzeitabhängigkeiten wie Java, JavaFX/OpenJFX-Unterstützung, SQL-Werkzeuge, Firebird-Clientbibliotheken und gemeinsame Betriebssystembibliotheken.
- Microsoft SQL Server Kommandozeilenwerkzeuge
- Firebird-Clienttools und Bibliotheken
- gemeinsame Betriebssystem-Laufzeitbibliotheken
Tags: Tags:
```text ```text
gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64 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-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 ### Romexis Server Image
Das Server Image wird aus `romexis/Dockerfile` gebaut. Gebaut aus:
Es enthält: ```text
romexis/Dockerfile
```
- extrahierte Romexis-Serverdateien Verwendet:
- Romexis-Datenbank-SQL-Skripte
- native Chilkat-Laufzeitbibliothek
- Romexis Java Property Agent
- Runtime-Hilfsskripte
- Entrypoint- und Initialisierungslogik
Architekturspezifische Tags: ```text
romexis-payload:<version>
romexis-base-jre:11-<arch>
```
Ergänzt:
- native Chilkat-Laufzeit
- Romexis Java PropertyAgent
- Server-Entrypoint
- Datenbankinitialisierung
- KeyVault- und Pfadvorbereitung
Tags:
```text ```text
gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64 gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64 gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
```
Multiarch-Manifest-Tag:
```text
gitea.buchhorster.de/planmeca/romexis-server:<version> gitea.buchhorster.de/planmeca/romexis-server:<version>
``` ```
--- ### Romexis Migration Service Image
## Build-Argumente Gebaut aus dem Migration-Service-Verzeichnis.
### Gemeinsame Argumente Stellt Web/API-Dienst für Migrations- und Restore-Workflows bereit.
| Argument | Beschreibung | Tags:
|---------|--------------|
| `TARGETARCH` | Zielarchitektur, normalerweise `amd64` oder `arm64`. |
| `ROMEXIS_VERSION` | Angeforderte Romexis-Version oder Versionspräfix. |
### Base-Image-Argumente ```text
gitea.buchhorster.de/planmeca/romexis-migration-service:amd64
gitea.buchhorster.de/planmeca/romexis-migration-service:arm64
gitea.buchhorster.de/planmeca/romexis-migration-service:latest
```
| Argument | Beschreibung | ### Romexis Admin Image
|---------|--------------|
| `IMAGE_VERSION` | OCI-Image-Label-Version des Base Images. |
### Server-Image-Argumente Gebaut aus:
| Argument | Beschreibung | ```text
|---------|--------------| romexis-admin/Dockerfile
| `ROMEXIS_BASE_IMAGE` | Basisimage-Referenz für die finale Romexis-Server-Stage. | ```
| `CHILKAT_VERSION` | Version der nativen Chilkat-Bibliothek. |
Verwendet das Romexis Payload Image und stellt eine browserbasierte Romexis Admin / RomexisConfig Umgebung bereit.
Das Image enthält:
- Romexis Admin Dateien aus dem Payload Image
- Xvfb
- Openbox
- xcompmgr
- x11vnc
- noVNC/websockify
- JavaFX Runtime-Unterstützung
- DxService Linux-Kompatibilitäts-Shim
- optionales Debug-xterm
- lokalisierten VNC-Start-Splashscreen
Tags:
```text
gitea.buchhorster.de/planmeca/romexis-admin:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-admin:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-admin:<version>
gitea.buchhorster.de/planmeca/romexis-admin:latest
```
### mRomexis WebApp Image
Gebaut aus:
```text
romexis-mromexis-app/Dockerfile
```
Verwendet das Romexis Payload Image und kopiert:
```text
/opt/romexis/broker/mromexis-html.war
```
in eine Tomcat-Runtime als:
```text
/usr/local/tomcat/webapps/ROOT.war
```
Wichtig:
```text
mromexis-html.war existiert erst ab Romexis 6.5.3.
```
Builds für ältere Romexis-Versionen werden bewusst übersprungen.
Tags:
```text
gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>
gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest
```
--- ---
## Versionsauflösung ## Versionsauflösung
Romexis-Versionen werden in folgender Datei definiert: Unterstützte Romexis-Versionen werden in folgender Datei definiert:
```text ```text
romexis-payload/romexis-versions.env romexis-payload/romexis-versions.env
@@ -110,106 +196,84 @@ Format:
Build-Eingabe: Build-Eingabe:
```bash ```env
ROMEXIS_VERSION=6.5.3 ROMEXIS_VERSION=6.5.3.444.203
``` ```
Das Dockerfile löst den neuesten passenden Eintrag auf und schreibt die tatsächlich verwendete Version nach: Die CI-Pipeline iteriert über diese Datei und baut die benötigten Image-Familien für die verfügbaren Versionen.
```text
/opt/romexis/version
```
Dadurch kann lokal oder in CI mit stabilen Versionspräfixen gebaut werden, während das Image intern die exakte Romexis-Version enthält.
--- ---
## Installer-Download und Extraktion ## Lokale Builds
Das Repository enthält keine Romexis-Binaries. `docker-compose.build.yml` wird nicht mehr verwendet.
Während der `romexis-build`-Stage: Lokale Builds werden ausgeführt über:
1. Die passende Installer-URL wird aus `romexis-versions.env` gelesen.
2. `download-romexis-installer-parts.py` lädt nur die benötigten Installerbestandteile herunter.
3. Die InstallShield-CAB-Datei wird durch `extract-and-copy-romexis-parts.sh` verarbeitet.
4. Die finale Romexis-Verzeichnisstruktur wird unter `/opt/romexis` aufgebaut.
5. SQL-Server-Initialisierungsskripte werden nach `/opt/romexis-mssql-db` kopiert.
---
## Mapping-basierte Extraktion
Die Datei:
```text ```text
romexis-payload/romexis-copy-map.tsv scripts/build-local.sh
scripts/build-local.ps1
``` ```
ist die zentrale Zuordnung zwischen Installer-Komponenten und Zielverzeichnissen. ### Linux/macOS
Format:
```text
Source<TAB>Destination
Broker_jar /opt/romexis/broker
Server_jar /opt/romexis/server
Server_Program_64bit/server/*.xml /opt/romexis/server
```
Das Extraktionsskript nutzt diese Datei für zwei Schritte:
1. Ermitteln, welche Top-Level-CAB-Komponenten extrahiert werden müssen.
2. Kopieren der gemappten Dateien und Verzeichnisse an ihre Zielorte.
Bei Glob-Mappings wie:
```text
Server_Program_64bit/server/*.xml
```
wird die komplette Top-Level-Komponente `Server_Program_64bit` extrahiert, aber nur passende XML-Dateien werden in das Zielverzeichnis kopiert.
Dadurch bleibt das Dockerfile unabhängig vom internen Romexis-Installerlayout.
---
## Lokaler Build mit Docker Compose
Verwendet wird:
```text
docker-compose.build.yml
```
### Base Image bauen
```bash ```bash
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base chmod +x scripts/build-local.sh
./scripts/build-local.sh all
``` ```
### Romexis Server Image bauen ### Windows PowerShell
```bash ```powershell
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis .\scripts\build-local.ps1 -Targets all
``` ```
### Lokal gebauten Stack starten ### Ausgewählte Image-Familien bauen
```bash ```bash
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d ./scripts/build-local.sh base server
./scripts/build-local.sh admin mromexis
./scripts/build-local.sh migration
``` ```
### Build ohne Cache Typische `.env` Werte für lokale Builds:
```bash ```env
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build --no-cache romexis-base REGISTRY=gitea.buchhorster.de/planmeca
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build --no-cache romexis ROMEXIS_VERSION=6.5.3.444.203
IMAGE_SUFFIX=
TARGETARCH=amd64
ROMEXIS_IMAGE=romexis-server
MIGRATION_IMAGE=romexis-migration-service
ADMINISTRATION_IMAGE=romexis-admin
MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app
```
Für Feature-Branches:
```env
IMAGE_SUFFIX=-feature-romexis-admin
``` ```
--- ---
## Manueller Docker Build ## Manuelle Docker-Build-Beispiele
Manuelle Builds sind hilfreich, um einzelne Image-Familien zu debuggen.
### Payload
```bash
docker buildx build \
--platform linux/amd64 \
--provenance=false \
--sbom=false \
--build-arg ROMEXIS_VERSION=6.5.3.444.203 \
-t gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203 \
--load \
./romexis-payload
```
### Base Image ### Base Image
@@ -227,52 +291,6 @@ docker buildx build \
### Server Image ### Server Image
```bash
docker buildx build \
--platform linux/amd64 \
--provenance=false \
--sbom=false \
--build-arg TARGETARCH=amd64 \
--build-arg ROMEXIS_VERSION=6.5.3 \
--build-arg ROMEXIS_BASE_IMAGE=gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64 \
-t gitea.buchhorster.de/planmeca/romexis-server:6.5.3-amd64 \
--load \
./romexis
```
---
---
## Payload-Build-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 ```bash
docker buildx build \ docker buildx build \
--platform linux/amd64 \ --platform linux/amd64 \
@@ -287,54 +305,96 @@ docker buildx build \
./romexis ./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 ```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 - neue Version in `romexis-versions.env`: nur neues Payload Image bauen
- geänderte URL einer bestehenden Version: diese Version neu 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 - geänderte `romexis-copy-map.tsv`, Payload-Dockerfile oder Hilfsskripte: alle Payload-Versionen neu bauen
- vorhandenes Payload ohne relevante Änderung: überspringen - vorhandenes Payload ohne relevante Änderung: überspringen
Veröffentlichte Image-Familien: ### mRomexis-Versionsregel
mRomexis-WebApp-Images werden nur gebaut, wenn gilt:
```text ```text
romexis-payload:<version> version >= 6.5.3
romexis-base-jre:11-amd64
romexis-base-jre:11-arm64
romexis-base-jre:11
romexis-server:<version>-amd64
romexis-server:<version>-arm64
romexis-server:<version>
romexis-migration-service:amd64
romexis-migration-service:arm64
romexis-migration-service:latest
``` ```
Ältere Versionen werden übersprungen, weil das Payload kein `mromexis-html.war` enthält.
## CI/CD Build-Ablauf ### Manifest-Veröffentlichung
Die Drone-Pipeline folgt dieser Reihenfolge: Zuerst werden architekturspezifische Tags erstellt:
1. `romexis-base-jre:11-amd64` bauen und veröffentlichen. ```text
2. `romexis-server:<version>-amd64` bauen und veröffentlichen. <image>:<version>-amd64
3. `romexis-base-jre:11-arm64` bauen und veröffentlichen. <image>:<version>-arm64
4. `romexis-server:<version>-arm64` bauen und veröffentlichen. ```
5. Multiarch-Manifest erstellen und veröffentlichen.
Das Publishing erfolgt bewusst seriell, um Registry-Last und parallele Upload-Probleme zu vermeiden. Danach erstellt Drone das Multiarch-Manifest:
Buildx wird mit folgenden Optionen verwendet: ```text
<image>:<version>
```
Für ausgewählte Dienste wird zusätzlich ein `latest` Alias aus der Default-Romexis-Version in `.env.sample` erzeugt.
Buildx verwendet:
```bash ```bash
--provenance=false --provenance=false
@@ -345,22 +405,64 @@ Dies verbessert die Kompatibilität mit Registries, die OCI-Attestations nicht z
--- ---
## Empfohlene Build-Reihenfolge ## Zusammenhang zwischen Runtime Compose und Build
Für lokale Entwicklung: Die Runtime-Compose-Dateien verwenden Manifest-Tags statt architekturspezifischer Tags.
```bash Für `main` bleibt `IMAGE_SUFFIX` leer:
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis ```env
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d IMAGE_SUFFIX=
``` ```
Für CI: Für Feature-Branches wird ein Branch-Suffix verwendet:
```text ```env
base amd64 -> server amd64 -> base arm64 -> server arm64 -> manifest IMAGE_SUFFIX=-feature-romexis-admin
``` ```
Die Runtime-Compose-Image-Referenzen lösen dadurch auf die passenden branch-spezifischen Manifeste auf.
---
## Wartungshinweise
### Neue Romexis-Version hinzufügen
1. Installer-URL in `romexis-payload/romexis-versions.env` ergänzen.
2. Prüfen, ob die Copy-Map weiterhin zum Installerlayout passt.
3. Payload Image bauen oder durch CI bauen lassen.
4. Server/Admin/mRomexis-Images bauen, sofern zutreffend.
5. Stack starten und Server, Admin und WebApp testen.
### Änderungen am Installerlayout
1. `romexis-payload/romexis-copy-map.tsv` aktualisieren.
2. Payload Image neu bauen.
3. Benötigte Dateien unter `/opt/romexis` prüfen.
4. Abhängige Runtime-Images neu bauen.
### Änderungen am Admin Image
Prüfen:
- JavaFX-Native-Libraries
- `/usr/lib/jni` Symlinks
- Openbox-Start
- xcompmgr-Start
- noVNC-Zugriff
- VNC-Lifecycle-Verhalten
- Admin-Sprache als Startparameter
### Änderungen an der mRomexis WebApp
Prüfen:
- `mromexis-html.war` existiert im Payload
- Tomcat deployed `ROOT.war`
- Proxy-Endpunkt ist kein offener Proxy
- Versionsfilter überspringt weiterhin nicht unterstützte Romexis-Versionen
--- ---
## Build-Artefakte ## Build-Artefakte
@@ -377,23 +479,19 @@ Das finale Server Image enthält:
/entrypoint.sh /entrypoint.sh
``` ```
Temporäre Installerdateien werden während des Builds entfernt. Das finale Admin Image enthält:
--- ```text
/opt/romexis/admin
/opt/romexis/admin/RomexisPropertyAgent.jar
/opt/romexis/admin/libDxService.so
/opt/romexis/admin/libDxService_64.so
/opt/romexis/admin/RxClientClinic.jar
/usr/local/bin/start.sh
```
## Wartungshinweise Das finale mRomexis-WebApp-Image enthält:
Neue Romexis-Version hinzufügen: ```text
/usr/local/tomcat/webapps/ROOT.war
1. Installer-URL in `romexis-payload/romexis-versions.env` ergänzen. ```
2. Image mit neuer Version oder neuem Versionspräfix bauen.
3. `/opt/romexis/version` prüfen.
4. Container starten und Datenbankinitialisierung prüfen.
5. Client-Verbindung über konfigurierte RMI-Adresse und Ports testen.
Wenn sich das Installerlayout ändert:
1. `romexis-payload/romexis-copy-map.tsv` aktualisieren.
2. Server Image neu bauen.
3. Prüfen, ob alle benötigten Dateien in `/opt/romexis` vorhanden sind.
4. Dockerfile nur ändern, wenn neue Build-Werkzeuge erforderlich sind.
Reference-BUILD.md
+313 -215
@@ -2,7 +2,7 @@
[Back to README](README.md) | [Deutsch](BUILD.de.md) [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: The build system is designed to provide:
- reproducible Docker builds - reproducible Docker builds
- a reusable runtime base image - reusable image layers
- local developer builds through scripts
- native `amd64` and `arm64` images - native `amd64` and `arm64` images
- multi-architecture manifests - multi-architecture manifests
- minimal final runtime images - minimal final runtime images
- maintainable installer extraction logic - 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 ### Romexis Base Image
The base image is built from `romexis-base/Dockerfile`. Built from:
It contains shared runtime dependencies: ```text
romexis-base/Dockerfile
```
- Azul Zulu Java 11 runtime with JavaFX/OpenJFX support Contains shared server runtime dependencies such as Java, JavaFX/OpenJFX support, SQL tooling, Firebird client libraries and common OS libraries.
- Microsoft SQL Server command-line tools
- Firebird client tools and libraries
- common operating system runtime libraries
Tags: Tags:
```text ```text
gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64 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-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 ### Romexis Server Image
The server image is built from `romexis/Dockerfile`. Built from:
It contains: ```text
romexis/Dockerfile
```
- extracted Romexis server files Consumes:
- Romexis database SQL scripts
- native Chilkat runtime library
- Romexis Java property agent
- runtime helper scripts
- entrypoint and initialization logic
Architecture-specific tags: ```text
romexis-payload:<version>
romexis-base-jre:11-<arch>
```
Adds:
- native Chilkat runtime
- Romexis Java PropertyAgent
- server entrypoint
- database initialization scripts
- KeyVault and path preparation logic
Tags:
```text ```text
gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64 gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64 gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
```
Multi-architecture manifest tag:
```text
gitea.buchhorster.de/planmeca/romexis-server:<version> gitea.buchhorster.de/planmeca/romexis-server:<version>
``` ```
--- ### Romexis Migration Service Image
## Build Arguments Built from the migration service directory.
### Common arguments Provides the web/API service for migration and restore workflows.
| Argument | Description | Tags:
|---------|-------------|
| `TARGETARCH` | Target architecture, usually `amd64` or `arm64`. |
| `ROMEXIS_VERSION` | Requested Romexis version or version prefix. |
### Base image arguments ```text
gitea.buchhorster.de/planmeca/romexis-migration-service:amd64
gitea.buchhorster.de/planmeca/romexis-migration-service:arm64
gitea.buchhorster.de/planmeca/romexis-migration-service:latest
```
| Argument | Description | ### Romexis Admin Image
|---------|-------------|
| `IMAGE_VERSION` | OCI image label version for the base image. |
### Server image arguments Built from:
| Argument | Description | ```text
|---------|-------------| romexis-admin/Dockerfile
| `ROMEXIS_BASE_IMAGE` | Base image reference used by the final Romexis Server stage. | ```
| `CHILKAT_VERSION` | Native Chilkat library version. |
Consumes the Romexis payload and provides a browser-accessible Romexis Admin / RomexisConfig environment.
The image includes:
- Romexis Admin files from the payload image
- Xvfb
- Openbox
- xcompmgr
- x11vnc
- noVNC/websockify
- JavaFX runtime support
- DxService Linux compatibility shim
- optional debug xterm
- localized VNC startup splash screen
Tags:
```text
gitea.buchhorster.de/planmeca/romexis-admin:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-admin:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-admin:<version>
gitea.buchhorster.de/planmeca/romexis-admin:latest
```
### mRomexis Web App Image
Built from:
```text
romexis-mromexis-app/Dockerfile
```
Consumes the Romexis payload and copies:
```text
/opt/romexis/broker/mromexis-html.war
```
into a Tomcat runtime as:
```text
/usr/local/tomcat/webapps/ROOT.war
```
Important:
```text
mromexis-html.war exists only in Romexis 6.5.3 and newer.
```
Builds for older Romexis versions are intentionally skipped.
Tags:
```text
gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>
gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest
```
--- ---
## Version Resolution ## Version Resolution
Romexis versions are defined in: Supported Romexis versions are defined in:
```text ```text
romexis-payload/romexis-versions.env romexis-payload/romexis-versions.env
@@ -110,108 +196,86 @@ Format:
Build input: Build input:
```bash ```env
ROMEXIS_VERSION=6.5.3 ROMEXIS_VERSION=6.5.3.444.203
``` ```
The Dockerfile resolves the newest matching entry and writes the resolved version to: The CI pipeline iterates over this file and builds the required image families for the available versions.
```text
/opt/romexis/version
```
This makes it possible to build using a stable prefix while still tagging the final image with the exact resolved Romexis version in CI.
--- ---
## Installer Download and Extraction ## Local Builds
The build does not store Romexis binaries in the repository. `docker-compose.build.yml` is no longer used.
During the `romexis-build` stage: Local builds are handled by:
1. The selected installer URL is read from `romexis-versions.env`.
2. `download-romexis-installer-parts.py` downloads only the required installer parts.
3. The InstallShield CAB file is processed by `extract-and-copy-romexis-parts.sh`.
4. The final Romexis directory layout is assembled under `/opt/romexis`.
5. SQL Server initialization scripts are copied to `/opt/romexis-mssql-db`.
---
## Mapping-Based Extraction
The file:
```text ```text
romexis-payload/romexis-copy-map.tsv scripts/build-local.sh
scripts/build-local.ps1
``` ```
is the central mapping between installer components and final target directories. ### Linux/macOS
Format:
```text
Source<TAB>Destination
Broker_jar /opt/romexis/broker
Server_jar /opt/romexis/server
Server_Program_64bit/server/*.xml /opt/romexis/server
```
The extraction script uses this file for two steps:
1. Determine which top-level CAB components must be extracted.
2. Copy the mapped files and directories to their final destinations.
For glob mappings such as:
```text
Server_Program_64bit/server/*.xml
```
the complete top-level component `Server_Program_64bit` is extracted, but only matching XML files are copied to the final destination.
This keeps the Dockerfile independent from the Romexis installer layout and makes future installer changes easier to maintain.
---
## Local Build with Docker Compose
Use:
```text
docker-compose.build.yml
```
### Build the base image
```bash ```bash
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base chmod +x scripts/build-local.sh
./scripts/build-local.sh all
``` ```
### Build the Romexis Server image ### Windows PowerShell
```bash ```powershell
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis .\scripts\build-local.ps1 -Targets all
``` ```
### Start the locally built stack ### Build selected image families
```bash ```bash
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d ./scripts/build-local.sh base server
./scripts/build-local.sh admin mromexis
./scripts/build-local.sh migration
``` ```
### Build without cache Typical `.env` values for local builds:
```bash ```env
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build --no-cache romexis-base REGISTRY=gitea.buchhorster.de/planmeca
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build --no-cache romexis ROMEXIS_VERSION=6.5.3.444.203
IMAGE_SUFFIX=
TARGETARCH=amd64
ROMEXIS_IMAGE=romexis-server
MIGRATION_IMAGE=romexis-migration-service
ADMINISTRATION_IMAGE=romexis-admin
MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app
```
For a feature branch:
```env
IMAGE_SUFFIX=-feature-romexis-admin
``` ```
--- ---
## Manual Docker Build ## Manual Docker Build Examples
### Base image Manual builds are useful for debugging a single image family.
### Payload
```bash
docker buildx build \
--platform linux/amd64 \
--provenance=false \
--sbom=false \
--build-arg ROMEXIS_VERSION=6.5.3.444.203 \
-t gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203 \
--load \
./romexis-payload
```
### Base Image
```bash ```bash
docker buildx build \ docker buildx build \
@@ -225,53 +289,7 @@ docker buildx build \
./romexis-base ./romexis-base
``` ```
### Server image ### Server Image
```bash
docker buildx build \
--platform linux/amd64 \
--provenance=false \
--sbom=false \
--build-arg TARGETARCH=amd64 \
--build-arg ROMEXIS_VERSION=6.5.3 \
--build-arg ROMEXIS_BASE_IMAGE=gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64 \
-t gitea.buchhorster.de/planmeca/romexis-server:6.5.3-amd64 \
--load \
./romexis
```
---
---
## Payload Build Layer
Installer download and extraction now happen in `romexis-payload/`.
The payload image contains only:
```text
/opt/romexis
/opt/romexis-mssql-db
```
It does not contain Java or Chilkat. This keeps the payload architecture-independent.
Manual payload build:
```bash
docker buildx build \
--platform linux/amd64 \
--provenance=false \
--sbom=false \
--build-arg ROMEXIS_VERSION=6.5.3.444.203 \
-t gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203 \
--load \
./romexis-payload
```
The server image then consumes this payload:
```bash ```bash
docker buildx build \ docker buildx build \
@@ -287,54 +305,96 @@ docker buildx build \
./romexis ./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 ```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 - new version in `romexis-versions.env`: build only the new payload image
- changed URL for an existing version: rebuild that version - changed URL for an existing version: rebuild that version
- changed `romexis-copy-map.tsv`, payload Dockerfile or helper scripts: rebuild all payload versions - changed `romexis-copy-map.tsv`, payload Dockerfile or helper scripts: rebuild all payload versions
- existing payload with no relevant change: skip - 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 ```text
romexis-payload:<version> version >= 6.5.3
romexis-base-jre:11-amd64
romexis-base-jre:11-arm64
romexis-base-jre:11
romexis-server:<version>-amd64
romexis-server:<version>-arm64
romexis-server:<version>
romexis-migration-service:amd64
romexis-migration-service:arm64
romexis-migration-service:latest
``` ```
Older versions are skipped because the payload does not contain `mromexis-html.war`.
## CI/CD Build Flow ### Manifest publishing
The Drone pipeline follows this order: Architecture-specific tags are created first:
1. Build and push `romexis-base-jre:11-amd64`. ```text
2. Build and push `romexis-server:<version>-amd64`. <image>:<version>-amd64
3. Build and push `romexis-base-jre:11-arm64`. <image>:<version>-arm64
4. Build and push `romexis-server:<version>-arm64`. ```
5. Create and push the multi-architecture manifest.
Publishing is intentionally serialized to reduce registry contention and avoid concurrent upload issues. Then Drone creates the multi-architecture manifest:
Buildx is used with: ```text
<image>:<version>
```
For selected services, a `latest` alias is also created from the default Romexis version configured in `.env.sample`.
Buildx uses:
```bash ```bash
--provenance=false --provenance=false
@@ -345,22 +405,64 @@ This improves compatibility with registries that do not handle OCI attestations
--- ---
## Recommended Build Order ## Runtime Compose and Build Relationship
For local development: The runtime Compose files use manifest tags instead of architecture-specific tags.
```bash For `main`, `IMAGE_SUFFIX` is empty:
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis ```env
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d IMAGE_SUFFIX=
``` ```
For CI: For feature branches, use a branch suffix:
```text ```env
base amd64 -> server amd64 -> base arm64 -> server arm64 -> manifest IMAGE_SUFFIX=-feature-romexis-admin
``` ```
Runtime Compose image references then resolve to the corresponding branch-specific manifests.
---
## Maintenance Notes
### Add a new Romexis version
1. Add the installer URL to `romexis-payload/romexis-versions.env`.
2. Ensure the copy map still matches the installer layout.
3. Build or let CI build the payload image.
4. Build server/admin/mRomexis images as applicable.
5. Start the stack and verify server, Admin and Web App behavior.
### Installer layout changes
1. Update `romexis-payload/romexis-copy-map.tsv`.
2. Rebuild the payload image.
3. Verify required files under `/opt/romexis`.
4. Rebuild dependent runtime images.
### Admin image changes
Check:
- JavaFX native libraries
- `/usr/lib/jni` symlinks
- Openbox startup
- xcompmgr startup
- noVNC access
- VNC lifecycle behavior
- Admin language startup parameter
### mRomexis Web App changes
Check:
- `mromexis-html.war` exists in the payload
- Tomcat deploys `ROOT.war`
- proxy endpoint is not open to arbitrary hosts
- version filtering still skips unsupported Romexis versions
--- ---
## Build Artifacts ## Build Artifacts
@@ -377,23 +479,19 @@ The final server image contains:
/entrypoint.sh /entrypoint.sh
``` ```
Temporary installer files are removed during the build. The final Admin image contains:
--- ```text
/opt/romexis/admin
/opt/romexis/admin/RomexisPropertyAgent.jar
/opt/romexis/admin/libDxService.so
/opt/romexis/admin/libDxService_64.so
/opt/romexis/admin/RxClientClinic.jar
/usr/local/bin/start.sh
```
## Maintenance Notes The final mRomexis Web App image contains:
When adding support for a new Romexis version: ```text
/usr/local/tomcat/webapps/ROOT.war
1. Add the installer URL to `romexis-payload/romexis-versions.env`. ```
2. Build the image using the new version or version prefix.
3. Verify `/opt/romexis/version`.
4. Start the container and check database initialization logs.
5. Confirm client connectivity through the configured RMI host and ports.
When the installer layout changes:
1. Update `romexis-payload/romexis-copy-map.tsv`.
2. Rebuild the server image.
3. Confirm that all required files exist in `/opt/romexis`.
4. Keep the Dockerfile unchanged unless new build tools are required.
Reference-README-compose.md
+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 Process
## Release Inputs ## Release Inputs
A release usually includes: A release usually includes:
- built and pushed container images - built and pushed container images
- updated documentation - updated documentation
- release notes - release notes
- optional migration service changes - optional migration service changes
- optional client changes - optional client changes
--- ---
## Suggested Release Steps ## Suggested Release Steps
1. Ensure the repository builds cleanly. 1. Ensure the repository builds cleanly.
2. Verify payload image availability. 2. Verify payload image availability.
3. Verify base images for target architectures. 3. Verify base images for target architectures.
4. Verify server images for target architectures. 4. Verify server images for target architectures.
5. Verify multiarch manifests. 5. Verify multiarch manifests.
6. Test Docker Compose startup. 6. Test Docker Compose startup.
7. Test database initialization. 7. Test database initialization.
8. Test migration service startup. 8. Test migration service startup.
9. Create release notes. 9. Create release notes.
10. Publish Gitea release. 10. Publish Gitea release.
11. Verify Gitea packages. 11. Verify Gitea packages.
--- ---
## Image Verification ## Image Verification
```bash ```bash
docker pull gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64 docker pull gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
docker pull gitea.buchhorster.de/planmeca/romexis-server:<version> docker pull gitea.buchhorster.de/planmeca/romexis-server:<version>
``` ```
Inspect: Inspect:
```bash ```bash
docker manifest inspect gitea.buchhorster.de/planmeca/romexis-server:<version> docker manifest inspect gitea.buchhorster.de/planmeca/romexis-server:<version>
``` ```
--- ---
## Release Notes Should Mention ## Release Notes Should Mention
- new features - new features
- migration service changes - migration service changes
- database backend changes - database backend changes
- breaking changes - breaking changes
- required environment variable changes - required environment variable changes
- known limitations - known limitations
--- ---
## Gitea Areas ## Gitea Areas
Use Gitea as follows: Use Gitea as follows:
| Area | Purpose | | Area | Purpose |
|---|---| |---|---|
| Code | Source code and Dockerfiles | | Code | Source code and Dockerfiles |
| Releases | Human-readable versioned release notes | | Releases | Human-readable versioned release notes |
| Packages | Published container images | | Packages | Published container images |
| Wiki | Operational and developer documentation | | Wiki | Operational and developer documentation |
| Issues | Bugs, feature requests and planning | | 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 # Runtime Layout
## Persistent Data ## Persistent Data
Recommended persistent root: Recommended persistent root:
```text ```text
/srv/romexis-data /srv/romexis-data
``` ```
Typical directories: Typical directories:
```text ```text
/srv/romexis-data/romexis_images /srv/romexis-data/sconfig
/srv/romexis-data/romexis_ergodata /srv/romexis-data/programdata
/srv/romexis-data/romexis_cache /srv/romexis-data/romexis_images
/srv/romexis-data/firebird /srv/romexis-data/romexis_ergodata
``` /srv/romexis-data/romexis_cache
/srv/romexis-data/sql-backup
--- /srv/romexis-data/firebird
```
## Romexis Container Paths
---
```text
/opt/romexis ## Runtime Services
/opt/romexis/server
/opt/romexis/sconfig ```text
/opt/romexis/programdata romexis
Main Romexis Server process.
/data/romexis_images
/data/romexis_ergodata mssql
/data/romexis_cache Microsoft SQL Server backend when DATABASE_BACKEND=mssql.
```
firebird
--- Firebird backend when DATABASE_BACKEND=firebird.
## Database Paths romexis-admin
Browser-accessible Romexis Admin / RomexisConfig runtime.
### MSSQL
romexis-app
```text Tomcat-based mRomexis Web App.
/var/opt/mssql
/var/opt/mssql/backup proxy
``` OpenResty/Nginx proxy for mRomexis Web App.
### Firebird romexis-migration
Optional migration service for MSSQL workflows.
```text ```
/firebird/data/romexis.fdb
``` ---
--- ## Romexis Container Paths
## Restart State File ```text
/opt/romexis
Used by migration restore coordination: /opt/romexis/server
/opt/romexis/sconfig
```text /programdata/planmeca/romexis
/data/romexis_images/.romexis_restart_state
``` /data/romexis_images
/data/romexis_ergodata
--- /data/romexis_cache
```
## Runtime Scripts
---
```text
/entrypoint.sh ## Admin Container Paths
/opt/init-romexis-db.sh
/opt/init-romexis-mssql-db.sh ```text
/opt/init-romexis-firebird-db.sh /opt/romexis/admin
/opt/fix-keystore-alias.sh /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 # Server Image
Directory: Directory:
```text ```text
romexis/ romexis/
``` ```
The final Romexis Server image combines the prepared payload, runtime base image and runtime scripts. The final Romexis Server image combines the prepared payload, runtime base image, Firebird payload and runtime scripts.
--- ---
## Build Inputs ## Build Inputs
```text ```text
ROMEXIS_BASE_IMAGE ROMEXIS_BASE_IMAGE
ROMEXIS_PAYLOAD_IMAGE ROMEXIS_PAYLOAD_IMAGE
ROMEXIS_FIREBIRD_PAYLOAD_IMAGE ROMEXIS_FIREBIRD_PAYLOAD_IMAGE
ROMEXIS_VERSION ROMEXIS_VERSION
TARGETARCH TARGETARCH
CHILKAT_VERSION IMAGE_SUFFIX
``` CHILKAT_VERSION
```
Example defaults:
Example defaults:
```dockerfile
ARG TARGETARCH=amd64 ```dockerfile
ARG ROMEXIS_VERSION=6.5.3.444.203 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 IMAGE_SUFFIX=
ARG ROMEXIS_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-payload:${ROMEXIS_VERSION}
ARG ROMEXIS_FIREBIRD_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest ARG ROMEXIS_BASE_IMAGE=gitea.buchhorster.de/planmeca/romexis-base-jre:11-${TARGETARCH}${IMAGE_SUFFIX}
``` ARG ROMEXIS_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-payload:${ROMEXIS_VERSION}${IMAGE_SUFFIX}
ARG ROMEXIS_FIREBIRD_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest${IMAGE_SUFFIX}
--- ```
## Build Stages ---
```text ## Build Stages
Stage 1: romexis-payload
Imports /opt/romexis and /opt/romexis-mssql-db. ```text
Stage 1: romexis-payload
Stage 2: romexis-firebird-payload Imports /opt/romexis and /opt/romexis-mssql-db.
Imports /opt/romexis-firebird-db.
Stage 2: romexis-firebird-payload
Stage 3: agent-build Imports /opt/romexis-firebird-db.
Compiles RomexisPropertyAgent.java.
Stage 3: agent-build
Stage 4: final image Compiles RomexisPropertyAgent.java.
Assembles runtime image.
``` Stage 4: final image
Assembles runtime image.
--- ```
## Runtime Scripts ---
The final image includes: ## Runtime Scripts
```text The final image includes:
/entrypoint.sh
/opt/init-romexis-db.sh ```text
/opt/init-romexis-mssql-db.sh /entrypoint.sh
/opt/init-romexis-firebird-db.sh /opt/init-romexis-db.sh
/opt/init-romexis-db.sh /opt/init-romexis-mssql-db.sh
/opt/fix-keystore-alias.sh /opt/init-romexis-firebird-db.sh
``` /opt/fix-keystore-alias.sh
```
---
---
## Java Property Agent
## Java Property Agent
The image includes:
The image includes:
```text
/opt/romexis/server/RomexisPropertyAgent.jar ```text
``` /opt/romexis/server/RomexisPropertyAgent.jar
```
This allows runtime property injection before Romexis starts.
This allows runtime property injection before Romexis starts.
Example environment variable pattern:
Example environment variable pattern:
```text
PROPERTY_AGENT_SET_KEY_<property-name>=<value> ```text
``` PROPERTY_AGENT_SET_KEY_<property-name>=<value>
```
---
---
## Runtime Validation
## Runtime Validation
The Dockerfile should validate important payload outputs during build, especially:
The Dockerfile should validate important payload outputs during build, especially:
```text
/opt/romexis/server/RomexisServer.jar ```text
/opt/romexis/version /opt/romexis/server/RomexisServer.jar
/opt/romexis-mssql-db /opt/romexis/version
/opt/romexis-firebird-db /opt/romexis-mssql-db
``` /opt/romexis-firebird-db
```
Failing early is preferred over producing an incomplete runtime image.
Failing early is preferred over producing an incomplete runtime image.
Source-README-References.md
+13 -12
@@ -1,12 +1,13 @@
# Source README References # Source README References
These source documents were used as the basis for the wiki package. These source documents were used as the basis for the wiki package.
- [BUILD.de](Reference-BUILD.de) - [BUILD.de](Reference-BUILD.de)
- [BUILD](Reference-BUILD) - [BUILD](Reference-BUILD)
- [DEVELOPERS.de](Reference-DEVELOPERS.de) - [README.de](Reference-README.de)
- [DEVELOPERS](Reference-DEVELOPERS) - [README](Reference-README)
- [MIGRATION_README](Reference-MIGRATION_README) - [README Compose Refactor](Reference-README-compose)
- [MIGRATION_WORKFLOW](Reference-MIGRATION_WORKFLOW) - [DEVELOPERS.de](Reference-DEVELOPERS.de)
- [README.de](Reference-README.de) - [DEVELOPERS](Reference-DEVELOPERS)
- [README](Reference-README) - [MIGRATION_README](Reference-MIGRATION_README)
- [MIGRATION_WORKFLOW](Reference-MIGRATION_WORKFLOW)
Troubleshooting.md
+226 -186
@@ -1,186 +1,226 @@
# Troubleshooting # Troubleshooting
## Firebird mode still starts MSSQL initialization ## Inspect effective Compose configuration
Check: Because the active backend is selected through `.env`, start with:
```bash ```bash
docker exec -it romexis-server env | grep -E 'SERVER_DB|ROMEXIS_DB|FIREBIRD' docker compose config
``` ```
Expected Firebird values: Check that the expected backend override was loaded.
```text ---
SERVER_DB=4
ROMEXIS_DB_URL=jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb ## Wrong database backend starts
ROMEXIS_DB_USER=sysdba
ROMEXIS_DB_PASSWORD=pwr0mex! Check `.env`:
```
```env
If `SERVER_DB` is missing, the entrypoint may default to MSSQL: DATABASE_BACKEND=mssql
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
```bash ```
SERVER_DB="${SERVER_DB:-5}"
``` or:
Set: ```env
DATABASE_BACKEND=firebird
```env COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml
SERVER_DB=4 ```
```
Then inspect the running container environment:
---
```bash
## MSSQL_SA_PASSWORD required in Firebird mode docker compose exec romexis env | grep -E 'SERVER_DB|ROMEXIS_DB|MSSQL|FIREBIRD'
```
This means the old MSSQL init script is still being executed or old script content is present in the image.
Expected backend identifiers:
Check inside the Romexis container:
```text
```bash SERVER_DB=5 # MSSQL
cat /opt/init-romexis-db.sh SERVER_DB=4 # Firebird
ls -lah /opt/init-romexis-* ```
```
---
The wrapper must not contain:
## Firebird mode still starts MSSQL initialization
```bash
MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:?MSSQL_SA_PASSWORD is required}" If `SERVER_DB` is missing, the entrypoint may default to MSSQL.
```
Check:
That belongs only in:
```bash
```text docker compose exec romexis env | grep SERVER_DB
/opt/init-romexis-mssql-db.sh ```
```
The Firebird Compose override must set:
Rebuild without cache:
```env
```bash SERVER_DB=4
docker buildx prune -a -f ```
docker compose build --no-cache --pull
docker compose up --force-recreate ---
```
## 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.
## Firebird shows unixODBC isql help
Check inside the Romexis container:
If you see:
```bash
```text docker compose exec romexis cat /opt/init-romexis-db.sh
unixODBC - isql and iusql docker compose exec romexis ls -lah /opt/init-romexis-*
``` ```
then the wrong `isql` tool is used. Rebuild and recreate:
Use: ```bash
docker buildx prune -a -f
```bash ./scripts/build-local.sh server
isql-fb docker compose up -d --force-recreate
``` ```
Set: ---
```bash ## Firebird shows unixODBC isql help
export ISQL=isql-fb
``` If you see:
Or change the init script default: ```text
unixODBC - isql and iusql
```bash ```
ISQL="${ISQL:-isql-fb}"
``` then the wrong `isql` tool is used.
--- Use:
## Firebird database file already exists ```bash
isql-fb
If the Firebird container creates the database using: ```
```yaml or set:
FIREBIRD_DATABASE: "romexis.fdb"
``` ```bash
export ISQL=isql-fb
then the Romexis init script should not run `CREATE DATABASE` again. ```
It should connect to the existing empty database and import the SQL scripts. ---
--- ## Admin container does not start RomexisConfig
## Firebird SYSDBA duplicate key error Check logs:
Error: ```bash
docker compose logs -f romexis-admin
```text ```
violation of PRIMARY or UNIQUE KEY constraint
PLG$USER_NAME = 'SYSDBA' If `ADMIN_VNC_LIFECYCLE=true`, RomexisConfig starts only after a VNC/noVNC client connects.
```
Open:
Cause:
```text
The Firebird container was instructed to create `SYSDBA` again. http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true
```
Remove user creation variables from the Firebird service and keep only:
---
```yaml
environment: ## Admin JavaFX or translucency errors
ISC_PASSWORD: "${FIREBIRD_PASSWORD}"
FIREBIRD_DATABASE: "romexis.fdb" Romexis Admin requires Openbox and xcompmgr.
```
The Admin image should include:
---
```text
## Payload latest tag not found openbox
xcompmgr
Error: x11-utils
openjfx
```text libopenjfx-java
romexis-firebird-payload:latest: not found libopenjfx-jni
``` ```
Fix the Firebird payload CI build to push: Errors such as `TRANSLUCENT translucency is not supported` usually mean the compositor is missing or not running.
```bash ---
-t "$FIREBIRD_PAYLOAD_IMAGE:latest"
``` ## Admin splash screen is not shown
--- The splash screen uses `xmessage` from `x11-utils`.
## Build still uses old files Check:
Clean local build cache: ```bash
docker compose run --rm --entrypoint which romexis-admin xmessage
```bash ```
docker buildx prune -a -f
``` ---
Then rebuild with: ## mRomexis Web App build fails because WAR is missing
```bash `mromexis-html.war` exists only in Romexis 6.5.3 and newer.
docker compose build --no-cache --pull
``` Check the payload:
In CI, also check whether the build is skipped because the image already exists in the registry. ```bash
docker run --rm --entrypoint find gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203 /opt/romexis -name 'mromexis-html.war'
--- ```
## Start container with bash for debugging ---
In Compose: ## mRomexis Web App backend calls fail
```yaml Check proxy logs:
entrypoint:
- /bin/bash ```bash
- -c docker compose logs -f proxy
- sleep infinity ```
stdin_open: true Check Romexis backend reachability from the proxy container:
tty: true
``` ```bash
docker compose exec proxy wget -O- http://romexis:8093/ || true
Then: ```
```bash ---
docker compose exec romexis bash
``` ## 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 Romexis Docker Project Wiki
Repository areas: Repository areas:
- **Code**: source files, Dockerfiles and helper scripts - **Code**: source files, Dockerfiles and helper scripts
- **Releases**: published project releases and release notes - **Releases**: published project releases and release notes
- **Packages**: container images in the Gitea package registry - **Packages**: container images in the Gitea package registry
- **Wiki**: operational and developer documentation - **Wiki**: operational and developer documentation
_Sidebar.md
+48 -44
@@ -1,44 +1,48 @@
# Romexis Docker Wiki # Romexis Docker Wiki
- [Home](Home) - [Home](Home)
## Getting Started ## Getting Started
- [Project Overview](Project-Overview) - [Project Overview](Project-Overview)
- [Architecture](Architecture) - [Architecture](Architecture)
- [Quick Start](Quick-Start) - [Quick Start](Quick-Start)
- [Use with Docker + WSL in Windows](Docker-Desktop-WSL-Windows) - [Use with Docker + WSL in Windows](Docker-Desktop-WSL-Windows)
- [Configuration](Configuration) - [Compose Runtime](Compose-Runtime)
- [Container Images](Container-Images) - [Configuration](Configuration)
- [Container Images](Container-Images)
## Build System
- [Build System](Build-System) ## Runtime Services
- [Payload Images](Payload-Images) - [Romexis Admin](Romexis-Admin)
- [Base Image](Base-Image) - [mRomexis Web App](mRomexis-WebApp)
- [Server Image](Server-Image) - [Runtime Layout](Runtime-Layout)
- [CI/CD Pipeline](CI-CD-Pipeline) - [Backup and Restore](Backup-and-Restore)
- [Troubleshooting](Troubleshooting)
## Database - [Security](Security)
- [Database Backends](Database-Backends)
- [Microsoft SQL Server](Microsoft-SQL-Server) ## Build System
- [Firebird](Firebird) - [Build System](Build-System)
- [Local Build Scripts](Local-Build-Scripts)
## Migration - [Payload Images](Payload-Images)
- [Migration Service](Migration-Service) - [Base Image](Base-Image)
- [Migration Workflow](Migration-Workflow) - [Server Image](Server-Image)
- [Migration Client](Migration-Client) - [CI/CD Pipeline](CI-CD-Pipeline)
## Operations ## Database
- [Runtime Layout](Runtime-Layout) - [Database Backends](Database-Backends)
- [Backup and Restore](Backup-and-Restore) - [Microsoft SQL Server](Microsoft-SQL-Server)
- [Troubleshooting](Troubleshooting) - [Firebird](Firebird)
- [Security](Security)
## Migration
## Development - [Migration Service](Migration-Service)
- [Developer Guide](Developer-Guide) - [Migration Workflow](Migration-Workflow)
- [Java Property Agent](Java-Property-Agent) - [Migration Client](Migration-Client)
- [Project Structure](Project-Structure)
- [Release Process](Release-Process) ## Development
- [FAQ](FAQ) - [Developer Guide](Developer-Guide)
- [Java Property Agent](Java-Property-Agent)
## Source Documents - [Project Structure](Project-Structure)
- [Source README References](Source-README-References) - [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
```