6

Reference README

Patrick Gniza edited this page 2026-08-22 15:46:50 +02:00

Table of Contents

• Romexis Docker
• Overview
• Main Features
• Runtime Compose Structure
• Backend Selection with .env
• MSSQL
• Firebird
• Quick Start
• Runtime Services
• Romexis Server
• Database Backend
• Migration Service
• Romexis Admin
• mRomexis Web App
• Container Images
• Local Image Builds
• Persistent Data Directories
• sconfig
• programdata
• romexis_images
• romexis_cache
• romexis_ergodata
• Database Initialization
• KeyVault and ProgramData
• RomexisConfig and Admin Configuration
• Advanced Configuration
• Database backend
• RMI host and ports
• PropertyAgent
• Troubleshooting
• Inspect effective Compose configuration
• Check all services
• Check Romexis server
• Check Admin container
• Open a shell in the Admin service
• Check resolved Romexis version
• Keystore alias issues
• Known Limitations
• License
• Romexis
• Chilkat
• Disclaimer

Deutsch | English

Romexis Docker

Deutsch | Build process | Developer notes

Containerized deployment of Planmeca Romexis Server on Linux with Docker, database backend selection through Docker Compose, optional migration tooling, browser-based Romexis Admin access and a separate mRomexis Web App container.

---

Overview

This project builds and runs Planmeca Romexis services in Docker.

Romexis application files are extracted from the official Romexis Windows installer during the build process. No Romexis binaries are stored in this repository.

The runtime stack is split into clearly separated services:

• Romexis Server
  Main Romexis backend service with RMI ports, database access, KeyVault preparation and runtime configuration.

• Database backend
  Selected through DATABASE_BACKEND and COMPOSE_FILE in .env. Supported Compose backends are currently mssql and firebird.

• Romexis Migration Service
  Optional web/API service for restoring Romexis database backups and data directories.

• Romexis Admin
  Browser-accessible Admin / RomexisConfig container using Xvfb, Openbox, xcompmgr, x11vnc and noVNC.

• mRomexis Web App
  Separate Tomcat-based container for the mRomexis Web frontend available in Romexis 6.5.3 and newer.

---

Main Features

• Romexis Server in Docker
• Microsoft SQL Server and Firebird backend Compose overlays
• Runtime backend selection using .env
• Local build scripts for repeatable developer builds
• Multi-architecture images for amd64 and arm64
• Payload image layer for installer extraction
• Reusable base runtime image
• Server image built from payload and base images
• Migration Service image
• Romexis Admin image with browser/noVNC access
• mRomexis Web App image
• Branch-specific image suffix support through IMAGE_SUFFIX
• Java PropertyAgent support for server-side runtime properties
• Drone CI/CD support with multi-architecture manifests

---

Runtime Compose Structure

The runtime is split into a base Compose file and backend-specific override files:

.env.sample
docker-compose.yml
docker-compose.mssql.yml
docker-compose.firebird.yml
scripts/build-local.sh
scripts/build-local.ps1

The base file contains database-independent services such as:

romexis
romexis-admin
romexis-app
proxy

The backend override files add or override database-specific services and environment values:

docker-compose.mssql.yml
docker-compose.firebird.yml

docker-compose.build.yml is no longer required. Local image builds are handled by scripts/build-local.*.

---

Backend Selection with .env

The stack can be started with a single command by defining the selected backend in .env.

MSSQL

DATABASE_BACKEND=mssql
COMPOSE_PATH_SEPARATOR=:
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml

Start:

docker compose up -d

Firebird

DATABASE_BACKEND=firebird
COMPOSE_PATH_SEPARATOR=:
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml

Start:

docker compose up -d

On native Windows shells the Compose file separator may need to be ; instead of ::

COMPOSE_PATH_SEPARATOR=;
COMPOSE_FILE=docker-compose.yml;docker-compose.${DATABASE_BACKEND}.yml

To verify which files and values are active:

docker compose config

---

Quick Start

Create your runtime configuration:

cp .env.sample .env

Edit at least:

DATABASE_BACKEND=mssql
COMPOSE_PATH_SEPARATOR=:
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml

ROMEXIS_VERSION=6.5.3.444.203
IMAGE_SUFFIX=

Start the stack:

docker compose up -d

View logs:

docker compose logs -f

Stop the stack:

docker compose down

---

Runtime Services

Romexis Server

The romexis service runs the main Romexis backend.

It prepares:

• Romexis server properties
• KeyVault and ProgramData paths
• database connection configuration
• Linux data paths
• RMI host and port settings
• optional database initialization

Useful logs:

docker compose logs -f romexis

Check the installed Romexis version:

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

Database Backend

The selected backend is loaded through COMPOSE_FILE.

For MSSQL, the override file adds the SQL Server service and configures Romexis for Microsoft SQL Server.

For Firebird, the override file adds the Firebird service and configures Romexis for Firebird.

Use:

docker compose ps
docker compose logs -f
docker compose config

to inspect the effective runtime stack.

Migration Service

The Migration Service is used for Romexis migration and restore workflows.

It provides:

• web UI and REST API for migration jobs
• database backup upload
• temporary SFTP access per migration job
• server-side manifest.json generation
• database restore workflow
• file restore workflow
• validation and cleanup
• coordinated Romexis restart through a shared state file

The restart coordination file is:

/data/romexis_images/.romexis_restart_state

Romexis Admin

The romexis-admin service provides Romexis Admin / RomexisConfig through noVNC.

It starts the graphical runtime components with the container:

Xvfb -> Openbox -> xcompmgr -> x11vnc -> noVNC

RomexisConfig itself can be started only when a VNC/noVNC client connects. This keeps the Admin application from running permanently in the background.

Open the Admin UI:

http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true

Typical Admin environment values:

ADMIN_NOVNC_PORT=6080
ADMIN_VNC_PORT=5900
ADMIN_VNC_PASSWORD=promax
ADMIN_RESOLUTION=1280x900x24
ADMIN_JAVA_OPTS=-Xms256m -Xmx1024m

ADMIN_LANGUAGE=en
DEBUG_XTERM=false
ADMIN_VNC_LIFECYCLE=true
ENABLE_PROPERTY_AGENT=true

ADMIN_LANGUAGE supports:

en
de

The same language value is used for the startup splash screen and the RomexisConfig language= parameter.

DEBUG_XTERM=true opens an additional debug terminal in the VNC session.

ADMIN_VNC_LIFECYCLE=true means:

• first VNC/noVNC client connects -> RomexisConfig starts
• last VNC/noVNC client disconnects -> RomexisConfig stops
• a localized splash screen is displayed during Admin startup

mRomexis Web App

The romexis-app service serves the mRomexis Web frontend as a standalone Tomcat application.

Important:

mromexis-html.war is only available in Romexis 6.5.3 and newer.

Older payload versions do not contain the WAR file and therefore cannot build a valid mRomexis Web App image.

The web application is normally exposed through the proxy service. The proxy also handles the application /proxy?url=... endpoint.

The proxy rewrites incoming mRomexis proxy requests to the internal Romexis backend service instead of trusting the browser-supplied host. This avoids maintaining internal IP allowlists and prevents the endpoint from becoming an open HTTP proxy.

Typical environment value:

MROMEXIS_WEB_PORT=8081

Open the mRomexis Web App through the configured proxy port:

http://localhost:8081/

---

Container Images

The project uses these image families:

gitea.buchhorster.de/planmeca/romexis-payload:<version>

gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64
gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64
gitea.buchhorster.de/planmeca/romexis-base-jre:11

gitea.buchhorster.de/planmeca/romexis-server:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-server:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-server:<version>

gitea.buchhorster.de/planmeca/romexis-migration-service:amd64
gitea.buchhorster.de/planmeca/romexis-migration-service:arm64
gitea.buchhorster.de/planmeca/romexis-migration-service:latest

gitea.buchhorster.de/planmeca/romexis-admin:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-admin:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-admin:<version>
gitea.buchhorster.de/planmeca/romexis-admin:latest

gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-amd64
gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>-arm64
gitea.buchhorster.de/planmeca/romexis-mromexis-app:<version>
gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest

For feature branches, IMAGE_SUFFIX is appended to the tag:

IMAGE_SUFFIX=-feature-romexis-admin

Example:

gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-feature-romexis-admin

---

Local Image Builds

Local builds are handled by scripts.

Linux/macOS:

chmod +x scripts/build-local.sh
./scripts/build-local.sh all

Windows PowerShell:

.\scripts\build-local.ps1 -Targets all

Build only selected image families:

./scripts/build-local.sh base server
./scripts/build-local.sh admin mromexis
./scripts/build-local.sh migration

Common local .env values:

REGISTRY=gitea.buchhorster.de/planmeca
ROMEXIS_VERSION=6.5.3.444.203
IMAGE_SUFFIX=
TARGETARCH=amd64

ROMEXIS_IMAGE=romexis-server
MIGRATION_IMAGE=romexis-migration-service
ADMINISTRATION_IMAGE=romexis-admin
MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app

More build details are documented in BUILD.md.

---

Persistent Data Directories

sconfig

Mounted to:

/opt/romexis/sconfig

Contains persistent Romexis server configuration files.

programdata

Mounted to:

/programdata/planmeca/romexis

Mirrors the Windows %ProgramData%\Planmeca\Romexis location and contains KeyVault and security related files.

romexis_images

Mounted to:

/data/romexis_images

Stores patient images.

romexis_cache

Mounted to:

/data/romexis_cache

Stores cache data.

romexis_ergodata

Mounted to:

/data/romexis_ergodata

Stores ergo and additional Romexis data.

---

Database Initialization

On first startup, the server entrypoint can initialize the configured database backend.

Typical first-start tasks:

1. Wait for the selected database backend.
2. Create the Romexis database if missing.
3. Create the Romexis database user if missing.
4. Import schema and update scripts where applicable.
5. Write Linux data paths into the database.
6. Start the Romexis server.

Disable initialization:

ROMEXIS_INIT_DB=0

Enable verbose SQL output:

DB_CREATE_VERBOSE=true

---

KeyVault and ProgramData

Romexis expects a Windows-like ProgramData location. The entrypoint sets:

ProgramData=/programdata

The KeyVault path is written to romexis_server.properties.

The entrypoint initializes missing key files from image defaults when required.

---

RomexisConfig and Admin Configuration

The server container does not run RomexisConfig during startup.

Administrative configuration is handled by the dedicated romexis-admin container instead. This avoids mixing the server process with a graphical configuration tool and keeps the server container focused on the backend runtime.

---

Advanced Configuration

Database backend

Backend selection is controlled at Compose level:

DATABASE_BACKEND=mssql
COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml

The backend-specific Compose override then sets the appropriate Romexis database environment values.

RMI host and ports

SERVER_RMI_HOSTNAME=192.168.65.177
SERVER_RMI_LOW_PORT=1100
SERVER_RMI_HIGH_PORT=1120

SERVER_RMI_HOSTNAME must be reachable by Romexis clients.

PropertyAgent

The Java PropertyAgent can set Romexis RxProperties from environment variables.

Syntax:

PROPERTY_AGENT_SET_<RXPROPERTY_NAME>=<value>

Example:

PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true

The server uses the agent primarily for runtime properties. Admin enables the agent by default, and Admin and Client use its Java 17 RomexisOptionPaneUI null guard to prevent the Swing lifecycle NullPointerException caused by an early PropertyChange event before m_MessageArea is initialized.

---

Troubleshooting

Inspect effective Compose configuration

docker compose config

Check all services

docker compose ps
docker compose logs -f

Check Romexis server

docker compose logs -f romexis

Check Admin container

docker compose logs -f romexis-admin

Open a shell in the Admin service

docker compose run --rm --entrypoint /bin/bash romexis-admin

Check resolved Romexis version

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

Keystore alias issues

If Romexis reports a missing server certificate alias, run:

docker exec -it romexis-server /opt/fix-keystore-alias.sh

---

Known Limitations

• Romexis binaries are not included in this repository.
• mRomexis Web App image builds require Romexis 6.5.3 or newer.
• Romexis Admin is exposed through a browser-based VNC session, not as a native desktop application.
• Multi-architecture images are built and published, but functional validation depends on the target platform and available Romexis components.
• Production use requires backups, license validation and environment-specific testing.

---

License

Romexis

Planmeca Romexis is proprietary software.

This repository contains no Romexis application binaries. The official installer is downloaded during the build process based on romexis-payload/romexis-versions.env.

Chilkat

This project uses the Chilkat library required by Romexis. It is downloaded during the build process for the target architecture.

---

Disclaimer

This project is not affiliated with Planmeca Oy.

Use at your own risk.

Full backups and testing are strongly recommended before production use.

Romexis Docker Wiki

English · Deutsch

English

• Home

Getting Started

• Project Overview
• Architecture
• Quick Start
• Synology Quick Start
• Use with Docker + WSL in Windows
• Compose Runtime
• Configuration
• Container Images

Runtime Services

• Romexis Admin
• Romexis Client
• mRomexis Web App
• Runtime Layout
• Backup and Restore
• Troubleshooting
• Security

Build System

• Build System
• Local Build Scripts
• Payload Images
• Base Image
• Server Image
• CI/CD Pipeline

Database

• Database Backends
• Microsoft SQL Server
• Firebird

Migration

• Migration Service
• Migration Workflow
• Migration Client

Development

• Developer Guide
• Java Property Agent
• Project Structure
• Release Process
• FAQ

Source Documents

• Source README References

Deutsch

• Startseite

Erste Schritte

• Projektübersicht
• Architektur
• Schnellstart
• Synology Quick Start
• Nutzung mit Docker + WSL unter Windows
• Compose-Runtime
• Konfiguration
• Container-Images

Runtime-Dienste

• Romexis Admin
• Romexis Client
• mRomexis Web App
• Runtime-Layout
• Sicherung und Wiederherstellung
• Fehlerbehebung
• Sicherheit

Build-System

• Build-System
• Lokale Build-Skripte
• Payload-Images
• Base-Image
• Server-Image
• CI/CD-Pipeline

Datenbank

• Datenbank-Backends
• Microsoft SQL Server
• Firebird

Migration

• Migrationsdienst
• Migrationsworkflow
• Migrationsclient

Entwicklung

• Entwicklerhandbuch
• Java Property Agent
• Projektstruktur
• Release-Prozess
• FAQ

Quelldokumente

• README-Quellreferenzen

---

Romexis Docker Project Wiki / Romexis-Docker-Projekt-Wiki

English Home · Deutsche Startseite · English source documents · Deutsche Quelldokumente · Security · Sicherheit

Internal operations and development wiki / Internes Betriebs- und Entwicklungswiki