Table of Contents

Developer Notes

romexis-base/Dockerfile
romexis/Dockerfile
romexis-payload/romexis-versions.env
romexis-payload/romexis-copy-map.tsv
romexis-payload/extract-and-copy-romexis-parts.sh

Current Project Structure Additions
Payload Image Contract
Migration Architecture
Restart State File
Runtime Scripts

entrypoint.sh
init-romexis-db.sh
RomexisPropertyAgent.java

Multi-Architecture Notes
Local Development Workflow
Updating Romexis Versions
Updating Installer Mapping
Registry and CI Notes
Security Notes

Deutsch | English

Developer Notes

This document describes the internal structure of the Romexis Docker project and explains how the build components fit together.

Repository Design

The project is intentionally split into the following layers:

romexis-base/
  Provides the reusable Java and system runtime.

romexis/
  Builds the actual Romexis Server image from the official installer.

docker-compose.yml
  Runs pre-built images.

docker-compose.build.yml
  Builds local base and server images for development and testing.

This separation keeps the runtime base image independent from individual Romexis versions.

Main Components

`romexis-base/Dockerfile`

Builds the reusable runtime base image.

Responsibilities:

provide Java 11 runtime with JavaFX/OpenJFX support
install SQL Server command-line tools
install Firebird client libraries
apply operating system package updates
keep common dependencies out of the final server Dockerfile

The base image is tagged per architecture:

romexis-base-jre:11-amd64
romexis-base-jre:11-arm64

`romexis/Dockerfile`

Builds the actual Romexis Server image.

It uses a three-stage build:

romexis-build
- downloads installer components
- extracts required CAB components
- assembles /opt/romexis
- downloads the native Chilkat library
agent-build
- compiles RomexisPropertyAgent.java
- packages RomexisPropertyAgent.jar
final image
- starts from the Romexis base image
- copies prepared runtime files
- adds helper scripts and policy files

`romexis-payload/romexis-versions.env`

Maps supported Romexis versions to official installer URLs.

The keys use underscores instead of dots:

6_5_3_444_203=https://...

The Dockerfile accepts a prefix such as:

6.5.3

and resolves it to the newest matching full version.

`romexis-payload/romexis-copy-map.tsv`

Defines how extracted installer components are copied to the final image.

Format:

Source<TAB>Destination

Example:

Server_jar	/opt/romexis/server
Server_Program_64bit/server/*.xml	/opt/romexis/server

This file should be updated when the internal Romexis installer layout changes.

`romexis-payload/extract-and-copy-romexis-parts.sh`

Uses the mapping file to:

derive required top-level CAB components
extract only those components with unshield
copy mapped files and directories to their final destinations

This keeps the Dockerfile small and avoids hardcoding installer layout details in shell chains.

Current Project Structure Additions

The repository now includes these additional areas:

romexis-payload/
  Builds reusable, versioned, architecture-independent payload images from the official Romexis installer.

migration-service/
  Provides Web UI, REST API, SFTP, validation and restore orchestration.

migration-client/
  Provides the Windows client for guided source-system migrations.

romexis/Dockerfile no longer owns installer download and CAB extraction. It consumes the prepared payload image and only adds runtime-specific parts such as Chilkat, the Java agent and entrypoint scripts.

Payload Image Contract

A payload image must provide:

/opt/romexis
/opt/romexis-mssql-db
/opt/romexis/version
/opt/romexis/server/RomexisServer.jar

It must not contain architecture-specific runtime libraries such as Chilkat.

Changes to romexis-payload/romexis-copy-map.tsv or extraction scripts can change the payload for every version. Therefore CI rebuilds all payload versions when this logic changes.

Migration Architecture

The migration service manages migration jobs as JSON state files and provides temporary SFTP users for active jobs.

Important behavior:

active jobs recreate SFTP users on service startup
completed, cancelled and failed jobs do not recreate SFTP users
completing or cancelling a job removes or disables the temporary SFTP user
the server owns the manifest format
clients provide parameters, not fully formatted manifests

The restore script expects this manifest contract:

{
  "backup": {
    "file": "database/Romexis_db.bak"
  }
}

Restart State File

The migration service and Romexis container coordinate restarts through:

/data/romexis_images/.romexis_restart_state

The migration service writes a pending restart request, the Romexis entrypoint restarts the Romexis process and writes success or failed back. The migration service reads the final status and removes the file.

Runtime Scripts

`entrypoint.sh`

Prepares the Romexis runtime environment.

Responsibilities:

set ProgramData=/programdata
initialize persistent sconfig
initialize ProgramData sconfig
generate database connection properties
prepare static keys and KeyVault
prepare data directories
enable the default Java property agent setting
start RomexisServer.jar

`init-romexis-db.sh`

Initializes the SQL Server database.

Responsibilities:

wait for SQL Server
create the database if missing
create the Romexis database user if missing
import Romexis SQL scripts
set Linux data paths in the database

The script is idempotent and skips initialization when database and user already exist.

`RomexisPropertyAgent.java`

Allows setting Romexis RxProperties through environment variables.

Environment variable format:

PROPERTY_AGENT_SET_<RXPROPERTY_NAME>=<value>

Example:

PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true

Multi-Architecture Notes

The build supports:

linux/amd64
linux/arm64

Architecture handling is done through Docker's TARGETARCH build argument.

Examples:

--build-arg TARGETARCH=amd64
--build-arg TARGETARCH=arm64

The Chilkat native library is selected based on TARGETARCH:

TARGETARCH	Chilkat architecture
`amd64`	`x86_64`
`arm64`	`aarch64`

The final base image is selected through:

ROMEXIS_BASE_IMAGE

Example:

--build-arg ROMEXIS_BASE_IMAGE=romexis-base-jre:11-amd64

Local Development Workflow

Recommended workflow:

TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d

Check logs:

docker compose -f docker-compose.build.yml logs -f romexis

Check installed version:

docker exec -it romexis-server cat /opt/romexis/version

Updating Romexis Versions

To add a new Romexis version:

Add the full installer URL to romexis-payload/romexis-versions.env.
Build locally using the new version prefix.
Confirm the resolved version in /opt/romexis/version.
Start the container and verify database initialization.
Confirm Romexis client connectivity.

Updating Installer Mapping

When a new Romexis installer changes the internal InstallShield component names:

Inspect the extracted CAB structure.
Update romexis-copy-map.tsv.
Rebuild the server image.
Verify that required files are present under /opt/romexis.
Keep extraction logic inside the mapping file and helper script instead of adding long copy chains to the Dockerfile.

Registry and CI Notes

The Drone pipeline publishes:

romexis-base-jre:11-amd64
romexis-base-jre:11-arm64
romexis-server:<version>-amd64
romexis-server:<version>-arm64
romexis-server:<version>

The architecture-specific server tags are used to create the final multi-architecture manifest.

OCI provenance and SBOM generation are disabled in CI for better compatibility with the configured registry:

--provenance=false
--sbom=false

Security Notes

No Romexis program files are stored in the repository.
The installer is downloaded during the build.
Runtime secrets should be provided through Compose, CI secrets or an external secret manager.
Default passwords in sample Compose files must be changed before production use.
Full backups are required before production deployment.