Private
Public Access
Reference README hinzugefügt
+595
@@ -0,0 +1,595 @@
|
||||
# Romexis Docker
|
||||
|
||||
[English](README.md) | [Deutsch](README.de.md) | [Build process](BUILD.md) | [Developer notes](DEVELOPERS.md) | []
|
||||
|
||||
> 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.
|
||||
Reference in New Issue
Block a user