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

Reference README hinzugefügt

patrick
2026-06-29 06:19:55 +00:00
parent ea7035ff02
commit 9df1852146
1 changed files with 595 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Reference-README.md
+595
@@ -0,0 +1,595 @@
# Romexis Docker
[English](README.md) | [Deutsch](README.de.md) | [Build process](BUILD.md) | [Developer notes](DEVELOPERS.md) | [![Build Status](https://drone.buchhorster.de/api/badges/patrick/romexis-server-docker/status.svg?ref=refs/heads/main)]
> Containerized deployment of Planmeca Romexis Server 6.5 on Linux using Docker, Microsoft SQL Server and a reusable multi-architecture Romexis base image.
---
## Overview
This project builds and runs the Planmeca Romexis Server in Docker.
The build process extracts the required Romexis server files directly from the official Romexis Windows installer package. No Romexis application binaries are stored in this repository.
The current build system is split into payload, base and server image layers:
1. **Romexis Base Image**
- Provides the Java 11 runtime with JavaFX support.
- Provides Microsoft SQL Server command-line tools.
- Provides Firebird client libraries.
- Is built separately for `amd64` and `arm64`.
2. **Romexis Server Image**
- Uses the Romexis base image.
- Downloads and extracts the selected Romexis installer.
- Builds the final `/opt/romexis` directory structure.
- Adds the Java property agent, runtime scripts and database initialization files.
This separation keeps the final image easier to maintain and allows the shared runtime base image to be reused across multiple Romexis builds.
---
## Features
- Romexis Server 6.5 in Docker
- Microsoft SQL Server 2022 support
- Automatic database initialization
- Persistent storage for all application data
- Automatic KeyVault and ProgramData preparation
- Support for existing database volumes
- Multi-stage Docker build
- Multi-architecture image publishing for `amd64` and `arm64`
- Dedicated reusable Romexis base image
- Mapping-based installer extraction using `romexis-copy-map.tsv`
- Selective InstallShield CAB extraction
- Romexis installer versions managed through `romexis-versions.env`
- No Windows Registry required
- No RomexisConfig execution required
- Linux-compatible runtime paths
- Java property injection through `RomexisPropertyAgent`
- CI/CD build support through Drone
---
## Architecture
```text
+----------------------+
| Romexis Clients |
+----------+-----------+
|
| RMI / Romexis protocol ports
v
+----------------------+
| Romexis Server |
| Docker |
+----------+-----------+
|
| JDBC
v
+----------------------+
| Microsoft SQL Server |
| Docker |
+----------------------+
```
---
## Supported Platforms
The build system supports the following target architectures:
| Architecture | Docker platform | Tag suffix |
|-------------|-----------------|------------|
| x86_64 | `linux/amd64` | `-amd64` |
| ARM64 | `linux/arm64` | `-arm64` |
The Drone pipeline builds architecture-specific images and then publishes a multi-architecture manifest without an architecture suffix.
---
## Requirements
### Runtime host
- Linux host
- Docker Engine
- Docker Compose plugin
- Network access between Romexis clients and the published RMI ports
### Build host
- Docker Engine with BuildKit support
- Docker Buildx
- Docker Compose plugin
- Access to the Romexis installer download URLs listed in `romexis-payload/romexis-versions.env`
- Access to the configured container registry
- Sufficient disk space for installer extraction and image builds
### Recommended resources
- 8 GB RAM
- 4 CPU cores
- 20 GB free disk space for runtime
- Additional free disk space on build hosts for Docker build cache and extracted installer files
---
## Container Images
Images are published to the Gitea Container Registry namespace used by the project.
### Image layout
```text
gitea.buchhorster.de/patrick/romexis-base-jre:11-amd64
gitea.buchhorster.de/patrick/romexis-base-jre:11-arm64
gitea.buchhorster.de/patrick/romexis-server:<version>-amd64
gitea.buchhorster.de/patrick/romexis-server:<version>-arm64
gitea.buchhorster.de/patrick/romexis-server:<version>
```
The architecture-specific tags are used internally by the multi-architecture manifest.
### Example pull
```bash
docker pull gitea.buchhorster.de/patrick/romexis-server:6.5.3.444.203
```
### Verify installed Romexis version
```bash
docker run --rm \
--entrypoint cat \
gitea.buchhorster.de/patrick/romexis-server:6.5.3.444.203 \
/opt/romexis/version
```
---
## Version Handling
The file `romexis-payload/romexis-versions.env` maps supported Romexis versions to official installer URLs.
Example entries:
```text
6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip
6_5_2_189_213=https://content.planmeca.com/files/Planmeca_Romexis_6.5.2.189.213_Win.zip
```
The build argument `ROMEXIS_VERSION` may contain either a full version or a prefix.
Example:
```bash
ROMEXIS_VERSION=6.5.3
```
The build resolves this to the newest matching entry, for example:
```text
6.5.3.444.203
```
The resolved version is stored inside the image:
```text
/opt/romexis/version
```
---
## Project Structure
```text
.
├── docker-compose.yml
├── docker-compose.build.yml
├── README.md
├── README.de.md
├── BUILD.md
├── BUILD.de.md
├── DEVELOPERS.md
│
├── romexis-base
│ └── Dockerfile
│
├── romexis
│ ├── Dockerfile
│ ├── entrypoint.sh
│ ├── fix-keystore-alias.sh
│ ├── init-romexis-db.sh
│ ├── RomexisPropertyAgent.java
│ ├──
│
└── data
├── programdata
├── sconfig
├── romexis_images
├── romexis_cache
└── romexis_ergodata
```
---
## Runtime with pre-built images
Use `docker-compose.yml` for normal runtime operation.
```bash
ROMEXIS_VERSION=6.5.3.444.203 docker compose up -d
```
View logs:
```bash
docker compose logs -f
```
Romexis only:
```bash
docker compose logs -f romexis
```
SQL Server only:
```bash
docker compose logs -f mssql
```
Stop the environment:
```bash
docker compose down
```
---
## Local build with Docker Compose
Use `docker-compose.build.yml` for local builds.
The base image must be built before the Romexis Server image because the server Dockerfile uses the base image via the `ROMEXIS_BASE_IMAGE` build argument.
```bash
TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d
```
For an ARM64 build host:
```bash
TARGETARCH=arm64 docker compose -f docker-compose.build.yml --profile build build romexis-base
TARGETARCH=arm64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
```
Further details are documented in [BUILD.md](BUILD.md).
---
---
## Current Architecture Update
The project now uses three build layers instead of only base and server images:
1. **Romexis Payload Image**
- Built from `romexis-payload/Dockerfile`.
- Downloads and extracts the official Romexis installer.
- Contains `/opt/romexis` and `/opt/romexis-mssql-db`.
- Is architecture-independent and tagged as `romexis-payload:<version>`.
2. **Romexis Base Image**
- Built from `romexis-base/Dockerfile`.
- Contains Java, JavaFX, SQL tools and common runtime libraries.
- Is architecture-specific.
3. **Romexis Server Image**
- Built from `romexis/Dockerfile`.
- Consumes the payload image and the base image.
- Adds Chilkat, the Java Property Agent, runtime scripts and startup logic.
The payload split avoids repeated installer downloads and keeps the final server image build independent from the original ZIP/CAB extraction step.
---
## Migration Service
The repository now includes a Romexis Migration Service and a Windows Migration Client.
The migration service provides:
- Web UI and REST API for migration jobs
- temporary per-job SFTP credentials
- browser-based database backup upload
- automatic server-side `manifest.json` creation
- SQL Server database restore
- upload validation
- file restore workflow
- migration cancellation and cleanup
- migration completion with SFTP access removal
- coordinated Romexis restart through a shared state file
Supported migration paths:
1. **Windows Migration Client**
- detects Romexis installation, SQL Server configuration and data directories
- creates or uses a database backup
- uploads data using rclone/SFTP
- communicates with the migration service API
2. **Manual browser and SFTP workflow**
- create a migration job in the Web UI
- upload the database backup through the browser
- let the server generate the manifest
- upload `romexis_images`, `romexis_ergodata` and optionally `romexis_cache` via SFTP
- validate, restore and complete the migration
The Romexis restart after restore is coordinated through:
```text
/data/romexis_images/.romexis_restart_state
```
The migration service writes the restart request, the Romexis entrypoint performs the restart and writes the final status back.
## Persistent Data Directories
### sconfig
Mounted to:
```text
/opt/romexis/sconfig
```
Contains Romexis server configuration files that should persist across container recreations.
### programdata
Mounted to:
```text
/programdata/Planmeca/Romexis
```
This mirrors the Windows `%ProgramData%\Planmeca\Romexis` location and contains the KeyVault and related security files.
### romexis_images
Mounted to:
```text
/data/romexis_images
```
Stores patient images.
### romexis_cache
Mounted to:
```text
/data/romexis_cache
```
Stores cache data.
### romexis_ergodata
Mounted to:
```text
/data/romexis_ergodata
```
Stores ergo and additional Romexis data.
---
## Database Initialization
On first startup:
1. SQL Server starts.
2. Romexis waits until SQL Server is healthy.
3. The database `Romexis_db` is created if missing.
4. The database user `romexis` is created if missing.
5. Romexis SQL schema and update scripts are imported.
6. Linux data paths are written to the database.
Initialization is skipped when both the database and the Romexis database user already exist.
The initialization can be disabled:
```yaml
ROMEXIS_INIT_DB: "0"
```
Verbose SQL output can be enabled:
```yaml
DB_CREATE_VERBOSE: "true"
```
---
## KeyVault and ProgramData
Romexis expects a Windows-like `ProgramData` location. The entrypoint sets:
```bash
ProgramData=/programdata
```
The KeyVault path is written to `romexis_server.properties`:
```properties
SERVER_KEYVAULT_PATH=/programdata/Planmeca/Romexis/sconfig
```
The entrypoint initializes missing key files from the image defaults:
- `static_keys_default.p12` -> `static_keys.p12`
- `initial_keyvault.p12` -> `keyvault.p12`
---
## RomexisConfig
`RomexisConfig` is intentionally not executed.
Inside a Linux container, RomexisConfig may attempt to access Windows Registry functions through Advapi32/JNA. The required configuration tasks are handled directly by the Docker entrypoint instead.
Replaced responsibilities:
- KeyVault preparation
- ProgramData handling
- Database configuration
- Linux path configuration
- Runtime property injection
---
## Advanced Configuration
### Database URL
By default, the entrypoint generates:
```text
jdbc:sqlserver://<host>:<port>;databaseName=<database>;encrypt=true;trustServerCertificate=true;
```
You may provide a complete JDBC URL:
```yaml
ROMEXIS_DB_URL: "jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;"
```
### Database backend
```yaml
SERVER_DB: "5"
```
Value `5` represents Microsoft SQL Server.
### RMI host and ports
```yaml
SERVER_RMI_HOSTNAME: "192.168.65.177"
SERVER_RMI_LOW_PORT: "1100"
SERVER_RMI_HIGH_PORT: "1120"
```
`SERVER_RMI_HOSTNAME` must be reachable by Romexis clients.
### Property agent
The Java property agent can set Romexis `RxProperties` from environment variables.
Syntax:
```yaml
PROPERTY_AGENT_SET_<RXPROPERTY_NAME>: "<value>"
```
Default behavior:
```yaml
PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES: "true"
```
This is required for reliable KeyVault handling under Docker/Linux.
---
## Troubleshooting
### Check SQL Server
```bash
docker compose logs mssql
```
### Check Romexis
```bash
docker compose logs romexis
```
### Test SQL Server connectivity
```bash
docker exec -it romexis-mssql \
/opt/mssql-tools18/bin/sqlcmd \
-C \
-S localhost \
-U sa \
-P 'Pwr0mex!s!!!' \
-Q "SELECT 1"
```
### Check resolved Romexis version
```bash
docker exec -it romexis-server cat /opt/romexis/version
```
### Keystore alias issues
If Romexis reports:
```text
Failed to get keystore entry by alias:
server_certificate_...
```
run:
```bash
docker exec -it romexis-server /opt/fix-keystore-alias.sh
```
---
## Known Limitations
- Only server operation has been tested.
- `RomexisConfig` is not supported inside the container.
- Microsoft SQL Server is the primary supported database backend.
- Firebird client libraries are included in the base image, but the runtime Compose setup currently focuses on SQL Server.
- Multi-architecture images are supported by the build pipeline; functional validation depends on the target platform and available Romexis components.
---
## License
### Romexis
Planmeca Romexis is proprietary software.
This repository does not contain any Romexis program files. The official installer is downloaded during the build process based on `romexis-versions.env`.
### 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.