diff --git a/Architecture.md b/Architecture.md index bf5ea85..345a38e 100644 --- a/Architecture.md +++ b/Architecture.md @@ -1,168 +1,175 @@ -Willkommen im Wiki.# Architecture - -## High-Level Runtime Architecture - -Default Microsoft SQL Server mode: - -```text -+----------------------+ -| Romexis Clients | -+----------+-----------+ - | - | RMI / Romexis protocol ports - v -+----------------------+ -| Romexis Server | -| Docker Container | -+----------+-----------+ - | - | JDBC - v -+----------------------+ -| Microsoft SQL Server | -| Docker Container | -+----------------------+ -``` - -Firebird mode: - -```text -+----------------------+ -| Romexis Clients | -+----------+-----------+ - | - | RMI / Romexis protocol ports - v -+----------------------+ -| Romexis Server | -| Docker Container | -+----------+-----------+ - | - | JDBC / Jaybird - v -+----------------------+ -| Firebird Server | -| Docker Container | -+----------------------+ -``` - ---- - -## Image Architecture - -```text -romexis-payload: - /opt/romexis - /opt/romexis-mssql-db - /opt/romexis/version - -romexis-firebird-payload:latest - /opt/romexis-firebird-db - Firebird SQL scripts - Firebird backup/restore helpers - romexis_new.fdb template/reference - -romexis-base-jre:11- - Java 11 - JavaFX/OpenJFX - database client tools - system dependencies - -romexis-server:- - Romexis payload - Firebird payload - base runtime - Java property agent - initialization scripts - entrypoint -``` - ---- - -## Why Payload Images? - -The original Dockerfile downloaded and extracted installer files inside the final server build. - -That worked, but had drawbacks: - -- repeated large downloads -- slow builds -- harder debugging -- installer extraction tightly coupled to server image build -- poor reuse across architectures - -Payload images solve this by making the extracted installer content a reusable build artifact. - ---- - -## Runtime Data Layout - -The runtime stack uses persistent volumes or host directories for: - -```text -/data/romexis_images -/data/romexis_ergodata -/data/romexis_cache -/opt/romexis/sconfig -/opt/romexis/programdata -``` - -Database data is backend-specific: - -```text -Microsoft SQL Server: - /var/opt/mssql - -Firebird: - /firebird/data/romexis.fdb -``` - ---- - -## Startup Flow - -```text -entrypoint.sh - | - |-- prepare persistent directories - |-- generate database URL if needed - |-- write Romexis configuration - |-- run /opt/init-romexis-db.sh - | | - | |-- route to MSSQL init if SERVER_DB=5 - | |-- route to Firebird init if SERVER_DB=4 - | - |-- fix keystore alias - |-- start Romexis Server -``` - ---- - -## Database Initialization Router - -The runtime uses a small router script: - -```text -/opt/init-romexis-db.sh -``` - -It detects the backend using: - -```text -ROMEXIS_DB_URL -SERVER_DB -``` - -Supported backend identifiers: - -| Value | Backend | -|---|---| -| `SERVER_DB=5` | Microsoft SQL Server | -| `SERVER_DB=4` | Firebird | - -Backend-specific logic is split into: - -```text -/opt/init-romexis-mssql-db.sh -/opt/init-romexis-firebird-db.sh -``` +# Architecture + +## High-Level Runtime Architecture + +The runtime is split into a base Compose stack and a selected database backend override. + +### Microsoft SQL Server mode + +```text ++----------------------+ +----------------------+ +| Romexis Clients | | Browser / noVNC User | ++----------+-----------+ +----------+-----------+ + | | + | RMI / Romexis ports | HTTP / WebSocket + v v ++----------------------+ +----------------------+ +| Romexis Server | | Romexis Admin | +| Docker Container | | noVNC Container | ++----------+-----------+ +----------------------+ + | + | JDBC + v ++----------------------+ +| Microsoft SQL Server | +| Docker Container | ++----------------------+ +``` + +### Firebird mode + +```text ++----------------------+ +----------------------+ +| Romexis Clients | | Browser / noVNC User | ++----------+-----------+ +----------+-----------+ + | | + | RMI / Romexis ports | HTTP / WebSocket + v v ++----------------------+ +----------------------+ +| Romexis Server | | Romexis Admin | +| Docker Container | | noVNC Container | ++----------+-----------+ +----------------------+ + | + | JDBC / Jaybird + v ++----------------------+ +| Firebird Server | +| Docker Container | ++----------------------+ +``` + +### mRomexis Web App + +```text ++----------------------+ +| Browser | ++----------+-----------+ + | + | HTTP + v ++----------------------+ +| OpenResty / Nginx | +| proxy container | ++----------+-----------+ + | + +------------------------------+ + | | + v v ++----------------------+ +----------------------+ +| mRomexis Web App | | Romexis Server | +| Tomcat Container | | Backend port 8093 | ++----------------------+ +----------------------+ +``` + +The mRomexis proxy rewrites backend proxy requests to the internal `romexis` service. It does not trust arbitrary hosts supplied by the browser. + +--- + +## Image Architecture + +```text +romexis-payload: + | + +--> romexis-server: + | + +--> romexis-admin: + | + +--> romexis-mromexis-app: + +romexis-base-jre:11- + | + +--> romexis-server:- + +romexis-firebird-payload:latest + | + +--> romexis-server:- +``` + +--- + +## Compose Architecture + +```text +docker-compose.yml + Common services: + - romexis + - romexis-admin + - romexis-app + - proxy + +docker-compose.mssql.yml + MSSQL service and MSSQL-specific Romexis environment. + +docker-compose.firebird.yml + Firebird service and Firebird-specific Romexis environment. +``` + +The selected backend is loaded through: + +```env +DATABASE_BACKEND=mssql +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +--- + +## Persistent Data Flow + +```text +/srv/romexis-data/ + sconfig/ + programdata/ + romexis_images/ + romexis_cache/ + romexis_ergodata/ + sql-backup/ + firebird/ +``` + +The same persistent data root can be used across server recreations. Backend-specific data stays in the selected database volume or host directory. + +--- + +## Admin Runtime Architecture + +`romexis-admin` provides a graphical Linux container for Romexis Admin / RomexisConfig. + +It starts: + +```text +Xvfb +Openbox +xcompmgr +x11vnc +noVNC / websockify +``` + +RomexisConfig can be started on demand when a VNC/noVNC client connects and stopped again when the last client disconnects. + +--- + +## mRomexis Web App Architecture + +`romexis-app` is a Tomcat image containing: + +```text +/usr/local/tomcat/webapps/ROOT.war +``` + +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. diff --git a/Backup-and-Restore.md b/Backup-and-Restore.md index de95bf2..3f8ccf0 100644 --- a/Backup-and-Restore.md +++ b/Backup-and-Restore.md @@ -1,77 +1,77 @@ -# Backup and Restore - -## MSSQL Backup Restore - -The migration service restores SQL Server backups through the shared backup directory. - -Host: - -```text -DATABASE_BACKUP_DIR=/srv/mssql-backup -``` - -Migration service: - -```text -/upload/database -``` - -SQL Server: - -```text -/var/opt/mssql/backup -``` - -Restore scripts should use the shared path so SQL Server can access the uploaded `.bak` file. - ---- - -## Firebird Backup Restore - -Firebird support includes original helper scripts from the macOS installer payload: - -```text -/opt/romexis-firebird-db/tools/Romexis_Firebird_Backup.sh -/opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh -``` - -Long-term restore strategy should support: - -```text -.fbk backup restore through gbak -.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. - ---- - -## Restart After Restore - -The migration service should not directly manipulate the Romexis process from the outside. - -Instead, it uses the shared restart state file: - -```text -/data/romexis_images/.romexis_restart_state -``` - -Expected pattern: - -1. migration service writes restart request -2. Romexis container notices request -3. Romexis process is restarted -4. Romexis container writes result -5. migration service reads result -6. migration service removes state file - ---- - -## Final Migration Completion - -A completed migration should: - -- preserve logs -- remove temporary SFTP user -- hide action buttons -- retain migration state for audit/debugging +# Backup and Restore + +## MSSQL Backup Restore + +The migration service restores SQL Server backups through the shared backup directory. + +Host: + +```text +DATABASE_BACKUP_DIR=/srv/mssql-backup +``` + +Migration service: + +```text +/upload/database +``` + +SQL Server: + +```text +/var/opt/mssql/backup +``` + +Restore scripts should use the shared path so SQL Server can access the uploaded `.bak` file. + +--- + +## Firebird Backup Restore + +Firebird support includes original helper scripts from the macOS installer payload: + +```text +/opt/romexis-firebird-db/tools/Romexis_Firebird_Backup.sh +/opt/romexis-firebird-db/tools/Romexis_Firebird_Restore.sh +``` + +Long-term restore strategy should support: + +```text +.fbk backup restore through gbak +.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. + +--- + +## Restart After Restore + +The migration service should not directly manipulate the Romexis process from the outside. + +Instead, it uses the shared restart state file: + +```text +/data/romexis_images/.romexis_restart_state +``` + +Expected pattern: + +1. migration service writes restart request +2. Romexis container notices request +3. Romexis process is restarted +4. Romexis container writes result +5. migration service reads result +6. migration service removes state file + +--- + +## Final Migration Completion + +A completed migration should: + +- preserve logs +- remove temporary SFTP user +- hide action buttons +- retain migration state for audit/debugging diff --git a/Base-Image.md b/Base-Image.md index 24d10f4..7d48e09 100644 --- a/Base-Image.md +++ b/Base-Image.md @@ -1,84 +1,84 @@ -# Base Image - -The base image provides reusable runtime dependencies for the Romexis Server image. - -Directory: - -```text -romexis-base/ -``` - ---- - -## Responsibilities - -The base image provides: - -- Java 11 runtime -- JavaFX/OpenJFX support -- Microsoft SQL Server command-line tools -- Firebird client libraries and tools -- common OS packages -- security updates - ---- - -## Architecture-Specific Tags - -```text -romexis-base-jre:11-amd64 -romexis-base-jre:11-arm64 -``` - -The base image is architecture-specific because it contains native runtime packages. - ---- - -## Firebird Tools - -For Firebird initialization, the Romexis container needs the Firebird CLI tools. - -The important tool is usually: - -```text -isql-fb -``` - -not: - -```text -isql -``` - -On Debian/Ubuntu, `isql` may refer to unixODBC. The Firebird initialization script should therefore default to: - -```bash -ISQL="${ISQL:-isql-fb}" -``` - -Required packages are typically: - -```text -firebird3.0-utils -libfbclient2 -``` - -Package names can differ depending on the base distribution. - ---- - -## SQL Server Tools - -The MSSQL initialization script uses: - -```text -/opt/mssql-tools18/bin/sqlcmd -``` - -This is required for: - -- waiting for SQL Server -- creating the database -- creating the Romexis database user -- importing SQL scripts -- updating Romexis data paths +# Base Image + +The base image provides reusable runtime dependencies for the Romexis Server image. + +Directory: + +```text +romexis-base/ +``` + +--- + +## Responsibilities + +The base image provides: + +- Java 11 runtime +- JavaFX/OpenJFX support +- Microsoft SQL Server command-line tools +- Firebird client libraries and tools +- common OS packages +- security updates + +--- + +## Architecture-Specific Tags + +```text +romexis-base-jre:11-amd64 +romexis-base-jre:11-arm64 +``` + +The base image is architecture-specific because it contains native runtime packages. + +--- + +## Firebird Tools + +For Firebird initialization, the Romexis container needs the Firebird CLI tools. + +The important tool is usually: + +```text +isql-fb +``` + +not: + +```text +isql +``` + +On Debian/Ubuntu, `isql` may refer to unixODBC. The Firebird initialization script should therefore default to: + +```bash +ISQL="${ISQL:-isql-fb}" +``` + +Required packages are typically: + +```text +firebird3.0-utils +libfbclient2 +``` + +Package names can differ depending on the base distribution. + +--- + +## SQL Server Tools + +The MSSQL initialization script uses: + +```text +/opt/mssql-tools18/bin/sqlcmd +``` + +This is required for: + +- waiting for SQL Server +- creating the database +- creating the Romexis database user +- importing SQL scripts +- updating Romexis data paths diff --git a/Build-System.md b/Build-System.md index 166ad90..980d718 100644 --- a/Build-System.md +++ b/Build-System.md @@ -1,125 +1,201 @@ -# Build System - -The build system is split into independent layers. - -```text -romexis-payload - | - v -romexis-server - ^ - | -romexis-base-jre - -romexis-firebird-payload - | - v -romexis-server -``` - ---- - -## Build Components - -### Payload build - -The payload build extracts the official Romexis installer. - -It produces: - -```text -/opt/romexis -/opt/romexis-mssql-db -/opt/romexis/version -``` - -### Firebird payload build - -The Firebird payload build extracts the macOS installer database package. - -It produces: - -```text -/opt/romexis-firebird-db -/opt/romexis-firebird-db/scripts -/opt/romexis-firebird-db/tools -/opt/romexis-firebird-db/templates -``` - -### Base image build - -The base image provides reusable runtime dependencies: - -- Java 11 -- JavaFX/OpenJFX -- SQL Server tools -- Firebird client libraries and tools -- OS dependencies - -### Server image build - -The final server image imports: - -- `/opt/romexis` from `romexis-payload` -- `/opt/romexis-mssql-db` from `romexis-payload` -- `/opt/romexis-firebird-db` from `romexis-firebird-payload` -- base runtime from `romexis-base-jre` -- Chilkat native library -- Java property agent -- runtime helper scripts - ---- - -## Local Build Commands - -Build payload: - -```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 -``` - -Build Firebird payload: - -```bash -docker build --build-arg ROMEXIS_VERSION=6.5.3.444.203 -t gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest ./romexis-firebird-payload -``` - -Build server image: - -```bash -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 -``` - ---- - -## Debug Build - -Disable cache and show full logs: - -```bash -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 -``` - ---- - -## 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. +# Build System + +The build system is split into independent layers and service images. + +```text +romexis-payload + | + +--> romexis-server + +--> romexis-admin + +--> romexis-mromexis-app + ^ + | +romexis-base-jre + +romexis-firebird-payload + | + v +romexis-server +``` + +--- + +## Build Components + +### Payload build + +The payload build extracts the official Romexis Windows installer. + +It produces: + +```text +/opt/romexis +/opt/romexis-mssql-db +/opt/romexis/version +``` + +It also provides files consumed by other service images, including Admin files and the mRomexis Web App WAR when available. + +### Firebird payload build + +The Firebird payload build extracts the macOS installer database package. + +It produces: + +```text +/opt/romexis-firebird-db +/opt/romexis-firebird-db/scripts +/opt/romexis-firebird-db/tools +/opt/romexis-firebird-db/templates +``` + +### Base image build + +The base image provides reusable runtime dependencies: + +- Java 11 +- JavaFX/OpenJFX +- SQL Server tools +- Firebird client libraries and tools +- OS dependencies + +### Server image build + +The final server image imports: + +- `/opt/romexis` from `romexis-payload` +- `/opt/romexis-mssql-db` from `romexis-payload` +- `/opt/romexis-firebird-db` from `romexis-firebird-payload` +- base runtime from `romexis-base-jre` +- Chilkat native library +- Java property agent +- runtime helper scripts + +### Admin image build + +The Admin image imports Romexis Admin files from the payload and adds a browser-accessible X11/noVNC runtime. + +Important runtime components: + +```text +Xvfb +Openbox +xcompmgr +x11vnc +noVNC/websockify +JavaFX +``` + +### mRomexis Web App build + +The mRomexis Web App image copies: + +```text +/opt/romexis/broker/mromexis-html.war +``` + +from the Romexis payload into Tomcat as: + +```text +/usr/local/tomcat/webapps/ROOT.war +``` + +This is only possible for Romexis 6.5.3 and newer. + +--- + +## Local Build Scripts + +Local builds are handled through: + +```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 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. diff --git a/CI-CD-Pipeline.md b/CI-CD-Pipeline.md index f84edcd..d64cc27 100644 --- a/CI-CD-Pipeline.md +++ b/CI-CD-Pipeline.md @@ -1,121 +1,176 @@ -# CI/CD Pipeline - -The project uses Drone CI to build and publish images to the Gitea container registry. - ---- - -## Main Pipeline Responsibilities - -The pipeline builds: - -```text -romexis-payload -romexis-firebird-payload -romexis-base-jre:11-amd64 -romexis-base-jre:11-arm64 -romexis-server:-amd64 -romexis-server:-arm64 -romexis-server: multiarch manifest -migration-service -``` - ---- - -## Payload Build Logic - -The Windows payload build checks version definitions and copy-map changes. - -Desired behavior: - -| Change | Behavior | -|---|---| -| New version added | build only new version | -| Existing URL changed | force rebuild affected version | -| Copy map changed | rebuild all payload versions | -| Extraction script changed | rebuild all payload versions | - ---- - -## Firebird Payload Build - -The Firebird payload is built after the Windows Romexis payload step. - -It uses: - -```text -romexis-firebird-payload/romexis-firebird-versions.env -``` - -The build pushes: - -```text -romexis-firebird-payload:latest -``` - -The server image consumes the shared Firebird payload image. - ---- - -## Server Build - -The server build pulls: - -```text -ROMEXIS_PAYLOAD_IMAGE -ROMEXIS_FIREBIRD_PAYLOAD_IMAGE -ROMEXIS_BASE_IMAGE -``` - -Then builds the final runtime image for each architecture. - ---- - -## 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`. - -Build command should include: - -```bash --t "$FIREBIRD_PAYLOAD_IMAGE:latest" -``` - -### Payload missing from final image - -Check the final image: - -```bash -docker run --rm --entrypoint find \ - gitea.buchhorster.de/planmeca/romexis-server: \ - /opt -maxdepth 3 -type f -``` +# CI/CD Pipeline + +The project uses Drone CI to build and publish images to the Gitea container registry. + +--- + +## Main Pipeline Responsibilities + +The pipeline builds: + +```text +romexis-payload +romexis-firebird-payload +romexis-base-jre:11-amd64 +romexis-base-jre:11-arm64 +romexis-server:-amd64 +romexis-server:-arm64 +romexis-admin:-amd64 +romexis-admin:-arm64 +romexis-mromexis-app:-amd64 +romexis-mromexis-app:-arm64 +romexis-migration-service:amd64 +romexis-migration-service:arm64 +multiarch manifests +``` + +--- + +## Branch Suffix Handling + +For `main`, image tags are published without a suffix. + +For feature branches, the branch name is normalized and appended as an image suffix: + +```text +-feature-romexis-admin +``` + +This allows feature branch images and manifests to be tested without overwriting `main` images. + +--- + +## Payload Build Logic + +The Windows payload build checks version definitions and copy-map changes. + +Desired behavior: + +| Change | Behavior | +|---|---| +| New version added | build only new version | +| Existing URL changed | force rebuild affected version | +| Copy map changed | rebuild all payload versions | +| Extraction script changed | rebuild all payload versions | + +--- + +## Firebird Payload Build + +The Firebird payload is built after the Windows Romexis payload step. + +It uses: + +```text +romexis-firebird-payload/romexis-firebird-versions.env +``` + +The build pushes: + +```text +romexis-firebird-payload:latest +``` + +The server image consumes the shared Firebird payload image. + +--- + +## Server Build + +The server build pulls: + +```text +ROMEXIS_PAYLOAD_IMAGE +ROMEXIS_FIREBIRD_PAYLOAD_IMAGE +ROMEXIS_BASE_IMAGE +``` + +Then builds the final runtime image for each architecture. + +--- + +## Admin Build + +The Admin build consumes the Romexis payload and builds: + +```text +romexis-admin:-amd64 +romexis-admin:-arm64 +romexis-admin: +romexis-admin:latest +``` + +The final image contains the graphical noVNC runtime and Romexis Admin / RomexisConfig files. + +--- + +## mRomexis Web App Build + +mRomexis Web App images are built only for Romexis versions where: + +```text +version >= 6.5.3 +``` + +Older versions are skipped because the payload does not contain: + +```text +/opt/romexis/broker/mromexis-html.war +``` + +Published tags: + +```text +romexis-mromexis-app:-amd64 +romexis-mromexis-app:-arm64 +romexis-mromexis-app: +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: /opt -maxdepth 3 -type f +``` diff --git a/Compose-Runtime.md b/Compose-Runtime.md new file mode 100644 index 0000000..5173a52 --- /dev/null +++ b/Compose-Runtime.md @@ -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 +``` diff --git a/Configuration.md b/Configuration.md index f02c74e..65c0633 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,141 +1,218 @@ -# Configuration - -Configuration is mostly handled through environment variables in `.env` and Docker Compose. - ---- - -## Core Variables - -| Variable | Description | -|---|---| -| `ROMEXIS_VERSION` | Romexis version to run | -| `TARGETARCH` | Target architecture suffix, e.g. `amd64` or `arm64` | -| `REGISTRY` | Container registry namespace | -| `ROMEXIS_IMAGE` | Romexis Server image name | -| `HOST_IP` | Host IP address exposed to Romexis clients | -| `ROMEXIS_DATA_ROOT` | Root directory for persistent Romexis data | - -Example: - -```env -ROMEXIS_VERSION=6.5.3.444.203 -TARGETARCH=amd64 -REGISTRY=gitea.buchhorster.de/patrick -ROMEXIS_IMAGE=romexis-server -HOST_IP=192.168.65.177 -ROMEXIS_DATA_ROOT=/srv/romexis-data -``` - ---- - -## Database Backend Selection - -Romexis uses `SERVER_DB` to identify the database backend. - -| Value | Backend | -|---|---| -| `5` | Microsoft SQL Server | -| `4` | Firebird | - -```env -SERVER_DB=5 -``` - -or: - -```env -SERVER_DB=4 -``` - ---- - -## Microsoft SQL Server Settings - -```env -MSSQL_PORT=1433 -MSSQL_SA_PASSWORD=Pwr0mex!s!!! -MSSQL_PID=Express - -ROMEXIS_DB_NAME=Romexis_db -ROMEXIS_DB_USER=romexis -ROMEXIS_DB_PASSWORD=romexis -``` - -Generated JDBC URL: - -```text -jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true; -``` - ---- - -## Firebird Settings - -```env -SERVER_DB=4 -FIREBIRD_PORT=3050 -FIREBIRD_USER=sysdba -FIREBIRD_PASSWORD=pwr0mex! -FIREBIRD_DB_PATH=/firebird/data/romexis.fdb -``` - -Generated JDBC URL: - -```text -jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb -``` - -For Romexis authentication: - -```env -ROMEXIS_DB_USER=sysdba -ROMEXIS_DB_PASSWORD=pwr0mex! -``` - ---- - -## 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. - ---- - -## RMI Ports - -```env -SERVER_RMI_LOW_PORT=1100 -SERVER_RMI_HIGH_PORT=1120 -``` - -These ports must be reachable from Romexis clients. - ---- - -## Migration Service Settings - -```env -MIGRATION_HTTP_PORT=8080 -MIGRATION_SFTP_PORT=2222 -MIGRATION_API_TOKEN=change-me -DATABASE_BACKUP_DIR=/srv/mssql-backup -``` - -`DATABASE_BACKUP_DIR` is shared between the migration service and the database backend for database restore workflows. +# Configuration + +Configuration is mostly handled through environment variables in `.env` and Docker Compose. + +--- + +## Core Variables + +| Variable | Description | +|---|---| +| `REGISTRY` | Container registry namespace | +| `ROMEXIS_VERSION` | Romexis version to run | +| `IMAGE_SUFFIX` | Optional branch-specific image suffix | +| `DATABASE_BACKEND` | Selected backend, usually `mssql` or `firebird` | +| `COMPOSE_FILE` | Compose file chain based on selected backend | +| `HOST_IP` | Host IP address exposed to Romexis clients | +| `ROMEXIS_DATA_ROOT` | Root directory for persistent Romexis data | + +Example: + +```env +REGISTRY=gitea.buchhorster.de/planmeca +ROMEXIS_VERSION=6.5.3.444.203 +IMAGE_SUFFIX= +DATABASE_BACKEND=mssql +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 +``` + +--- + +## Image Name Variables + +```env +ROMEXIS_IMAGE=romexis-server +MIGRATION_IMAGE=romexis-migration-service +ADMINISTRATION_IMAGE=romexis-admin +MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app +``` + +These are combined with `REGISTRY`, `ROMEXIS_VERSION` and `IMAGE_SUFFIX` by the Compose files. + +--- + +## Database Backend Selection + +Backend selection is controlled by Compose file selection, not only by `SERVER_DB`. + +### MSSQL + +```env +DATABASE_BACKEND=mssql +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +The MSSQL override then sets the Romexis backend values, for example: + +```env +SERVER_DB=5 +MSSQL_HOST=mssql +``` + +### Firebird + +```env +DATABASE_BACKEND=firebird +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +The Firebird override then sets the Romexis backend values, for example: + +```env +SERVER_DB=4 +FIREBIRD_HOST=firebird +``` + +--- + +## Microsoft SQL Server Settings + +```env +MSSQL_PORT=1433 +MSSQL_SA_PASSWORD=Pwr0mex!s!!! +MSSQL_PID=Express + +ROMEXIS_DB_NAME=Romexis_db +ROMEXIS_DB_USER=romexis +ROMEXIS_DB_PASSWORD=romexis +``` + +Generated JDBC URL: + +```text +jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true; +``` + +--- + +## Firebird Settings + +```env +FIREBIRD_PORT=3050 +FIREBIRD_USER=sysdba +FIREBIRD_PASSWORD=pwr0mex! +FIREBIRD_DB_PATH=/firebird/data/romexis.fdb +``` + +Generated JDBC URL: + +```text +jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb +``` + +For Romexis authentication: + +```env +ROMEXIS_DB_USER=sysdba +ROMEXIS_DB_PASSWORD=pwr0mex! +``` + +--- + +## RMI Ports + +```env +SERVER_RMI_LOW_PORT=1100 +SERVER_RMI_HIGH_PORT=1120 +``` + +These ports must be reachable from Romexis clients. + +--- + +## Romexis Admin 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 +``` + +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_= +``` + +This is primarily relevant for the Romexis server runtime. In the Admin container the PropertyAgent is disabled by default. diff --git a/Container-Images.md b/Container-Images.md index f678914..70bccb5 100644 --- a/Container-Images.md +++ b/Container-Images.md @@ -1,88 +1,155 @@ -# Container Images - -Images are published to the Gitea package registry namespace used by the project. - ---- - -## Main Images - -```text -gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64 -gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64 - -gitea.buchhorster.de/planmeca/romexis-payload: -gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest - -gitea.buchhorster.de/planmeca/romexis-server:-amd64 -gitea.buchhorster.de/planmeca/romexis-server:-arm64 -gitea.buchhorster.de/planmeca/romexis-server: - -gitea.buchhorster.de/planmeca/romexis-migration-service: -``` - ---- - -## Tagging Strategy - -### Base image - -Base images are architecture-specific: - -```text -romexis-base-jre:11-amd64 -romexis-base-jre:11-arm64 -``` - -### Windows payload image - -The Windows payload image is versioned by Romexis version: - -```text -romexis-payload:6.5.3.444.203 -``` - -It is architecture-independent. - -### Firebird payload image - -The Firebird payload contains the currently maintained Firebird SQL payload and is consumed as a shared image: - -```text -romexis-firebird-payload:latest -``` - -The Firebird SQL payload is not tied to the server image architecture. - -### Server image - -Server images are architecture-specific and also published as a multi-architecture manifest: - -```text -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 - -```bash -docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-amd64 -``` - -For multiarch usage: - -```bash -docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203 -``` - ---- - -## Local Tagging - -If Docker Compose expects a registry image but you built locally, tag it accordingly: - -```bash -docker tag romexis-server:local gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-amd64 -``` +# Container Images + +Images are published to the Gitea package registry namespace used by the project. + +--- + +## Main Images + +```text +gitea.buchhorster.de/planmeca/romexis-payload: +gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest + +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:-amd64 +gitea.buchhorster.de/planmeca/romexis-server:-arm64 +gitea.buchhorster.de/planmeca/romexis-server: + +gitea.buchhorster.de/planmeca/romexis-admin:-amd64 +gitea.buchhorster.de/planmeca/romexis-admin:-arm64 +gitea.buchhorster.de/planmeca/romexis-admin: +gitea.buchhorster.de/planmeca/romexis-admin:latest + +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-amd64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-arm64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app: +gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest + +gitea.buchhorster.de/planmeca/romexis-migration-service:amd64 +gitea.buchhorster.de/planmeca/romexis-migration-service:arm64 +gitea.buchhorster.de/planmeca/romexis-migration-service:latest +``` + +--- + +## Tagging Strategy + +### Payload image + +The Windows payload image is versioned by Romexis version and is architecture-independent: + +```text +romexis-payload:6.5.3.444.203 +``` + +### Base image + +Base images are architecture-specific and also published as a manifest: + +```text +romexis-base-jre:11-amd64 +romexis-base-jre:11-arm64 +romexis-base-jre:11 +``` + +### Server image + +Server images are architecture-specific and published as a multi-architecture manifest: + +```text +romexis-server:6.5.3.444.203-amd64 +romexis-server:6.5.3.444.203-arm64 +romexis-server:6.5.3.444.203 +``` + +### Admin image + +The Admin image uses the Romexis payload and provides the browser/noVNC Admin runtime: + +```text +romexis-admin:-amd64 +romexis-admin:-arm64 +romexis-admin: +romexis-admin:latest +``` + +### mRomexis Web App image + +The mRomexis Web App image is versioned by Romexis version: + +```text +romexis-mromexis-app:-amd64 +romexis-mromexis-app:-arm64 +romexis-mromexis-app: +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} +``` diff --git a/Database-Backends.md b/Database-Backends.md index 216dfa5..737e8bb 100644 --- a/Database-Backends.md +++ b/Database-Backends.md @@ -1,92 +1,144 @@ -Willkommen im Wiki.# 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. - ---- - -## Backend Identifiers - -| `SERVER_DB` | Backend | -|---|---| -| `5` | Microsoft SQL Server | -| `4` | Firebird | - ---- - -## Initialization Scripts - -The initialization entry point is: - -```text -/opt/init-romexis-db.sh -``` - -This script routes to: - -```text -/opt/init-romexis-mssql-db.sh -/opt/init-romexis-firebird-db.sh -``` - ---- - -## 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. - -Example: - -```text -6.0 -> 600 -6.1 -> 610 -6.3 -> 63 -6.4 -> 64 -``` - ---- - -## 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. +# Database Backends + +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. + +--- + +## Compose Backend Selection + +The database backend is selected in `.env` with `DATABASE_BACKEND` and `COMPOSE_FILE`. + +### 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 +``` + +The backend-specific Compose override sets the actual Romexis backend variables. + +--- + +## Backend Identifiers + +Romexis itself still uses `SERVER_DB` internally. + +| `SERVER_DB` | Backend | +|---|---| +| `5` | Microsoft SQL Server | +| `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. + +--- + +## Backend Services + +### MSSQL + +The MSSQL override starts the `mssql` service and configures Romexis to connect to: + +```text +mssql:1433 +``` + +Typical values: + +```env +MSSQL_SA_PASSWORD=Pwr0mex!s!!! +ROMEXIS_DB_NAME=Romexis_db +ROMEXIS_DB_USER=romexis +ROMEXIS_DB_PASSWORD=romexis +``` + +### Firebird + +The Firebird override starts the `firebird` service and configures Romexis to connect through Jaybird. + +Typical values: + +```env +FIREBIRD_USER=sysdba +FIREBIRD_PASSWORD=pwr0mex! +FIREBIRD_DB_PATH=/firebird/data/romexis.fdb +``` + +--- + +## Initialization Scripts + +The initialization entry point is: + +```text +/opt/init-romexis-db.sh +``` + +This script routes to: + +```text +/opt/init-romexis-mssql-db.sh +/opt/init-romexis-firebird-db.sh +``` + +--- + +## 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. diff --git a/Developer-Guide.md b/Developer-Guide.md index df0110b..d630700 100644 --- a/Developer-Guide.md +++ b/Developer-Guide.md @@ -1,111 +1,111 @@ -# Developer Guide - -This page describes the internal project structure and development workflow. - ---- - -## Main Project Directories - -```text -romexis-base/ - Runtime base image. - -romexis-payload/ - Windows installer payload extraction. - -romexis-firebird-payload/ - macOS Firebird SQL payload extraction. - -romexis/ - Final Romexis Server image. - -migration-service/ - Migration Web UI, REST API, SFTP and restore orchestration. - -migration-client/ - Source-side migration helper client. - -docs/ - Extended markdown documentation. -``` - ---- - -## Development Principles - -- Keep proprietary binaries out of Git. -- Keep installer extraction in payload images. -- Keep runtime dependencies in the base image. -- Keep final server image focused on assembly and runtime logic. -- Keep MSSQL and Firebird initialization separated. -- Use the wrapper script only for backend routing. -- Prefer explicit validation over silent incomplete images. - ---- - -## Database Init Scripts - -```text -init-romexis-db.sh - Routes to backend-specific init script. - -init-romexis-mssql-db.sh - Handles SQL Server initialization. - -init-romexis-firebird-db.sh - Handles Firebird initialization. -``` - ---- - -## Version-Aware Database Updates - -The database init scripts use an explicit Romexis update order. - -This is required because markers do not sort numerically. - -Example: - -```text -600, 610, 63, 64, 651, 652, 653 -``` - -The script resolves the target marker from `/opt/romexis/version` and runs updates until that marker. - ---- - -## Testing Image Contents - -```bash -docker run --rm --entrypoint find \ - gitea.buchhorster.de/planmeca/romexis-server: \ - /opt -maxdepth 3 -type f | sort -``` - -Open shell: - -```bash -docker run --rm -it --entrypoint bash \ - gitea.buchhorster.de/planmeca/romexis-server: -``` - ---- - -## Local Debug Compose Override - -```yaml -services: - romexis: - entrypoint: - - /bin/bash - - -c - - sleep infinity - stdin_open: true - tty: true -``` - -Then: - -```bash -docker compose exec romexis bash -``` +# Developer Guide + +This page describes the internal project structure and development workflow. + +--- + +## Main Project Directories + +```text +romexis-base/ + Runtime base image. + +romexis-payload/ + Windows installer payload extraction. + +romexis-firebird-payload/ + macOS Firebird SQL payload extraction. + +romexis/ + Final Romexis Server image. + +migration-service/ + Migration Web UI, REST API, SFTP and restore orchestration. + +migration-client/ + Source-side migration helper client. + +docs/ + Extended markdown documentation. +``` + +--- + +## Development Principles + +- Keep proprietary binaries out of Git. +- Keep installer extraction in payload images. +- Keep runtime dependencies in the base image. +- Keep final server image focused on assembly and runtime logic. +- Keep MSSQL and Firebird initialization separated. +- Use the wrapper script only for backend routing. +- Prefer explicit validation over silent incomplete images. + +--- + +## Database Init Scripts + +```text +init-romexis-db.sh + Routes to backend-specific init script. + +init-romexis-mssql-db.sh + Handles SQL Server initialization. + +init-romexis-firebird-db.sh + Handles Firebird initialization. +``` + +--- + +## Version-Aware Database Updates + +The database init scripts use an explicit Romexis update order. + +This is required because markers do not sort numerically. + +Example: + +```text +600, 610, 63, 64, 651, 652, 653 +``` + +The script resolves the target marker from `/opt/romexis/version` and runs updates until that marker. + +--- + +## Testing Image Contents + +```bash +docker run --rm --entrypoint find \ + gitea.buchhorster.de/planmeca/romexis-server: \ + /opt -maxdepth 3 -type f | sort +``` + +Open shell: + +```bash +docker run --rm -it --entrypoint bash \ + gitea.buchhorster.de/planmeca/romexis-server: +``` + +--- + +## Local Debug Compose Override + +```yaml +services: + romexis: + entrypoint: + - /bin/bash + - -c + - sleep infinity + stdin_open: true + tty: true +``` + +Then: + +```bash +docker compose exec romexis bash +``` diff --git a/FAQ.md b/FAQ.md index 3657aa2..ccc73d2 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,74 +1,74 @@ -# FAQ - -## Are Romexis binaries stored in Git? - -No. The repository does not store proprietary Romexis application binaries. - -The build system downloads official installer packages and extracts required files during payload builds. - ---- - -## Why use payload images? - -Payload images avoid repeated installer downloads and decouple installer extraction from final server image assembly. - ---- - -## 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. - ---- - -## What is the default database backend? - -Microsoft SQL Server. - -Use: - -```env -SERVER_DB=5 -``` - ---- - -## How do I enable Firebird? - -Use: - -```env -SERVER_DB=4 -FIREBIRD_PASSWORD=pwr0mex! -ROMEXIS_DB_USER=sysdba -ROMEXIS_DB_PASSWORD=pwr0mex! -``` - -and start the Firebird Compose variant. - ---- - -## Why does Firebird init use isql-fb? - -Because `isql` may be unixODBC's tool. Firebird's CLI is commonly named: - -```text -isql-fb -``` - ---- - -## 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. - ---- - -## Can I migrate from an existing Windows Romexis server? - -Yes, this is the purpose of the migration service and migration client workflow. - ---- - -## 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. +# FAQ + +## Are Romexis binaries stored in Git? + +No. The repository does not store proprietary Romexis application binaries. + +The build system downloads official installer packages and extracts required files during payload builds. + +--- + +## Why use payload images? + +Payload images avoid repeated installer downloads and decouple installer extraction from final server image assembly. + +--- + +## 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. + +--- + +## What is the default database backend? + +Microsoft SQL Server. + +Use: + +```env +SERVER_DB=5 +``` + +--- + +## How do I enable Firebird? + +Use: + +```env +SERVER_DB=4 +FIREBIRD_PASSWORD=pwr0mex! +ROMEXIS_DB_USER=sysdba +ROMEXIS_DB_PASSWORD=pwr0mex! +``` + +and start the Firebird Compose variant. + +--- + +## Why does Firebird init use isql-fb? + +Because `isql` may be unixODBC's tool. Firebird's CLI is commonly named: + +```text +isql-fb +``` + +--- + +## 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. + +--- + +## Can I migrate from an existing Windows Romexis server? + +Yes, this is the purpose of the migration service and migration client workflow. + +--- + +## 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. diff --git a/Firebird.md b/Firebird.md index a818d36..be83df2 100644 --- a/Firebird.md +++ b/Firebird.md @@ -1,150 +1,150 @@ -# Firebird - -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. - ---- - -## Compose Service - -Recommended Firebird service: - -```yaml -firebird: - image: jacobalberty/firebird:3.0 - container_name: romexis-firebird - environment: - ISC_PASSWORD: "${FIREBIRD_PASSWORD}" - FIREBIRD_DATABASE: "romexis.fdb" - ports: - - "${FIREBIRD_PORT:-3050}:3050" - volumes: - - ${ROMEXIS_DATA_ROOT}/firebird:/firebird/data - healthcheck: - test: ["CMD-SHELL", "nc -z localhost 3050 || exit 1"] - interval: 10s - timeout: 5s - retries: 30 - start_period: 20s - restart: unless-stopped -``` - -Do not configure the container to create a second `SYSDBA` user. `SYSDBA` already exists. - ---- - -## Romexis Settings - -```env -SERVER_DB=4 -FIREBIRD_PORT=3050 -FIREBIRD_USER=sysdba -FIREBIRD_PASSWORD=pwr0mex! -FIREBIRD_DB_PATH=/firebird/data/romexis.fdb - -ROMEXIS_DB_USER=sysdba -ROMEXIS_DB_PASSWORD=pwr0mex! -``` - -Generated JDBC URL: - -```text -jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb -``` - ---- - -## Firebird SQL Payload - -The Firebird SQL payload is extracted from the macOS Romexis installer and stored in: - -```text -/opt/romexis-firebird-db -``` - -Important files: - -```text -scripts/RX_Create_Database.sql -scripts/RX_Base_10fb_MAC.sql -scripts/rxdb.sh -scripts/rxupd.sh -tools/Romexis_Firebird_Backup.sh -tools/Romexis_Firebird_Restore.sh -templates/romexis_new.fdb -``` - ---- - -## Important Tooling Note - -The Firebird CLI tool should be: - -```text -isql-fb -``` - -not unixODBC `isql`. - -If you see this output: - -```text -unixODBC - isql and iusql -``` - -then the wrong tool is being used. - -Set: - -```bash -export ISQL=isql-fb -``` - -or make the init script default to: - -```bash -ISQL="${ISQL:-isql-fb}" -``` - ---- - -## Database Creation Strategy - -If the Firebird container creates an empty database via: - -```yaml -FIREBIRD_DATABASE: "romexis.fdb" -``` - -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. - ---- - -## Debugging Firebird Initialization - -Open a shell in the Romexis container: - -```bash -docker exec -it romexis-server bash -``` - -Run the initializer manually: - -```bash -ISQL=isql-fb DB_CREATE_VERBOSE=1 bash -x /opt/init-romexis-firebird-db.sh -``` - -Check connectivity: - -```bash -bash -c ': 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 - -| Area | Description | -|---|---| -| [Project Overview](Project-Overview) | High-level goals, features and supported platforms | -| [Architecture](Architecture) | Image layers, runtime containers and data flow | -| [Quick Start](Quick-Start) | Minimal steps to run the stack | -| [Configuration](Configuration) | Environment variables and runtime configuration | -| [Container Images](Container-Images) | Registry images, tags and manifests | -| [Build System](Build-System) | Payload, base and server build workflow | -| [Database Backends](Database-Backends) | MSSQL and Firebird database architecture | -| [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 | -| [Troubleshooting](Troubleshooting) | Common errors and fixes | - ---- - -## Current Core Components - -```text -romexis-payload/ - Builds architecture-independent payload images from the official Windows installer. - -romexis-firebird-payload/ - Builds a Firebird SQL payload from the official macOS installer. - -romexis-base/ - Builds the reusable Java 11 runtime base image. - -romexis/ - Builds the final Romexis Server image. - -migration-service/ - Provides browser-based and API-driven migration orchestration. - -migration-client/ - Provides the Windows migration helper client. - -docs/ - Contains extended project documentation. -``` - ---- - -## Recommended Reading Order - -1. [Project Overview](Project-Overview) -2. [Architecture](Architecture) -3. [Quick Start](Quick-Start) -4. [Configuration](Configuration) -5. [Database Backends](Database-Backends) -6. [Migration Service](Migration-Service) -7. [Build System](Build-System) -8. [Developer Guide](Developer-Guide) - ---- - -## Important Notes - -- No Romexis application binaries are committed to the repository. -- Official Planmeca installer packages are downloaded during payload builds. -- Microsoft SQL Server remains the default and most tested backend. -- Firebird support is being introduced in parallel for macOS/ARM64-oriented scenarios. -- The migration service is designed for moving existing Windows-based Romexis installations into the Docker stack. +# Romexis Docker Wiki + +Welcome to the Romexis Docker project wiki. + +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. + +--- + +## Main Areas + +| Area | Description | +|---|---| +| [Project Overview](Project-Overview) | High-level goals, features and supported platforms | +| [Architecture](Architecture) | Image layers, runtime containers and data flow | +| [Quick Start](Quick-Start) | Minimal steps to run the stack | +| [Compose Runtime](Compose-Runtime) | Base Compose file, backend overrides and `.env` selection | +| [Configuration](Configuration) | Environment variables and runtime configuration | +| [Container Images](Container-Images) | Registry images, tags, manifests and branch suffixes | +| [Romexis Admin](Romexis-Admin) | Browser-based RomexisConfig/Admin container via noVNC | +| [mRomexis Web App](mRomexis-WebApp) | Separate Tomcat-based mRomexis Web frontend container | +| [Build System](Build-System) | Payload, base, server, admin and web app build workflow | +| [Local Build Scripts](Local-Build-Scripts) | Local build helper scripts for Linux/macOS and Windows | +| [Database Backends](Database-Backends) | MSSQL and Firebird backend architecture | +| [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 | +| [Troubleshooting](Troubleshooting) | Common errors and fixes | + +--- + +## Current Core Components + +```text +romexis-payload/ + Builds architecture-independent payload images from the official Windows installer. + +romexis-firebird-payload/ + Builds a Firebird SQL payload from the official macOS installer. + +romexis-base/ + Builds the reusable Java 11 runtime base image. + +romexis/ + Builds the final Romexis Server image. + +romexis-admin/ + Builds the browser-accessible Romexis Admin / RomexisConfig container. + +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. + +migration-client/ + Provides the Windows migration helper client. + +scripts/ + Contains local build helpers such as build-local.sh and build-local.ps1. +``` + +--- + +## Current Runtime Layout + +The runtime is split into a base Compose file and backend-specific override files: + +```text +docker-compose.yml + Base runtime services and shared configuration. + +docker-compose.mssql.yml + 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. diff --git a/Local-Build-Scripts.md b/Local-Build-Scripts.md new file mode 100644 index 0000000..1944d95 --- /dev/null +++ b/Local-Build-Scripts.md @@ -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 +``` diff --git a/Microsoft-SQL-Server.md b/Microsoft-SQL-Server.md index 4538e1f..51d8661 100644 --- a/Microsoft-SQL-Server.md +++ b/Microsoft-SQL-Server.md @@ -1,77 +1,77 @@ -# Microsoft SQL Server - -Microsoft SQL Server is the default and most tested database backend. - ---- - -## Compose Service - -The MSSQL service uses the official Microsoft SQL Server image: - -```yaml -mssql: - image: mcr.microsoft.com/mssql/server:2022-latest - container_name: romexis-mssql - environment: - ACCEPT_EULA: "Y" - MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}" - MSSQL_PID: "${MSSQL_PID:-Express}" - ports: - - "${MSSQL_PORT}:1433" - volumes: - - mssql_data:/var/opt/mssql - - ${DATABASE_BACKUP_DIR}:/var/opt/mssql/backup -``` - ---- - -## Romexis Settings - -```env -SERVER_DB=5 -MSSQL_HOST=mssql -MSSQL_PORT=1433 -MSSQL_SA_PASSWORD= - -ROMEXIS_DB_NAME=Romexis_db -ROMEXIS_DB_USER=romexis -ROMEXIS_DB_PASSWORD= -``` - -Generated JDBC URL: - -```text -jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true; -``` - ---- - -## Initialization - -The MSSQL initializer: - -```text -/opt/init-romexis-mssql-db.sh -``` - -Responsibilities: - -- wait for SQL Server -- create Romexis database if missing -- create/update Romexis database user -- import base SQL scripts -- import update scripts up to the target schema marker -- update runtime paths in `RBA_Server_Param_S` - ---- - -## Backup Directory - -`DATABASE_BACKUP_DIR` is mounted into both the migration service and SQL Server: - -```text -Migration service: /upload/database -SQL Server: /var/opt/mssql/backup -``` - -This allows the migration service to upload a `.bak` file and trigger a database restore. +# Microsoft SQL Server + +Microsoft SQL Server is the default and most tested database backend. + +--- + +## Compose Service + +The MSSQL service uses the official Microsoft SQL Server image: + +```yaml +mssql: + image: mcr.microsoft.com/mssql/server:2022-latest + container_name: romexis-mssql + environment: + ACCEPT_EULA: "Y" + MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}" + MSSQL_PID: "${MSSQL_PID:-Express}" + ports: + - "${MSSQL_PORT}:1433" + volumes: + - mssql_data:/var/opt/mssql + - ${DATABASE_BACKUP_DIR}:/var/opt/mssql/backup +``` + +--- + +## Romexis Settings + +```env +SERVER_DB=5 +MSSQL_HOST=mssql +MSSQL_PORT=1433 +MSSQL_SA_PASSWORD= + +ROMEXIS_DB_NAME=Romexis_db +ROMEXIS_DB_USER=romexis +ROMEXIS_DB_PASSWORD= +``` + +Generated JDBC URL: + +```text +jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true; +``` + +--- + +## Initialization + +The MSSQL initializer: + +```text +/opt/init-romexis-mssql-db.sh +``` + +Responsibilities: + +- wait for SQL Server +- create Romexis database if missing +- create/update Romexis database user +- import base SQL scripts +- import update scripts up to the target schema marker +- update runtime paths in `RBA_Server_Param_S` + +--- + +## Backup Directory + +`DATABASE_BACKUP_DIR` is mounted into both the migration service and SQL Server: + +```text +Migration service: /upload/database +SQL Server: /var/opt/mssql/backup +``` + +This allows the migration service to upload a `.bak` file and trigger a database restore. diff --git a/Migration-Client.md b/Migration-Client.md index d20359f..090060e 100644 --- a/Migration-Client.md +++ b/Migration-Client.md @@ -1,54 +1,54 @@ -# Migration Client - -The migration client is the source-side helper for guided migrations from existing Romexis installations. - -Current direction: - -```text -Windows client first -Future: evaluate C# for broader platform support -``` - ---- - -## Responsibilities - -The client should help with: - -- detecting local Romexis installation paths -- detecting SQL Server connection settings -- creating a database backup -- detecting Romexis image and ergo data directories -- creating a migration job through the migration service API -- uploading data through rclone/SFTP -- calling API endpoints to advance workflow state -- displaying progress and logs - ---- - -## Why rclone? - -rclone is suitable for large migrations because it supports: - -- SFTP -- progress output -- retries -- resumable workflows -- directory synchronization -- configurable transfers/checkers - ---- - -## Python vs C# Direction - -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: - -- native Windows build -- possible macOS build -- stronger GUI options -- easier single-binary packaging -- better long-term maintainability for a desktop migration client - -The README should keep this as an architectural direction, not as a completed feature. +# Migration Client + +The migration client is the source-side helper for guided migrations from existing Romexis installations. + +Current direction: + +```text +Windows client first +Future: evaluate C# for broader platform support +``` + +--- + +## Responsibilities + +The client should help with: + +- detecting local Romexis installation paths +- detecting SQL Server connection settings +- creating a database backup +- detecting Romexis image and ergo data directories +- creating a migration job through the migration service API +- uploading data through rclone/SFTP +- calling API endpoints to advance workflow state +- displaying progress and logs + +--- + +## Why rclone? + +rclone is suitable for large migrations because it supports: + +- SFTP +- progress output +- retries +- resumable workflows +- directory synchronization +- configurable transfers/checkers + +--- + +## Python vs C# Direction + +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: + +- native Windows build +- possible macOS build +- stronger GUI options +- easier single-binary packaging +- better long-term maintainability for a desktop migration client + +The README should keep this as an architectural direction, not as a completed feature. diff --git a/Migration-Service.md b/Migration-Service.md index 84a9917..9b1a83f 100644 --- a/Migration-Service.md +++ b/Migration-Service.md @@ -1,153 +1,153 @@ -# Migration Service - -The Romexis Migration Service helps migrate an existing Romexis installation into the Docker-based Romexis Server stack. - -It provides: - -- Flask Web UI -- REST API -- temporary SFTP users -- migration job state tracking -- database backup upload -- manifest creation -- upload validation -- restore orchestration -- final completion/cancellation workflow - ---- - -## Why a Migration Service? - -Romexis installations can contain: - -- large SQL Server backups -- large image directories -- ergo data directories -- cache directories -- many small files - -Browser uploads alone are not ideal for this. Therefore the migration service combines: - -```text -Web UI / API - for orchestration and state - -SFTP - for large file and directory transfer -``` - ---- - -## Migration Job State - -Migration jobs are stored as JSON state files. - -Typical workflow: - -```text -created - -> database_uploaded - -> database_restored - -> upload_complete - -> validated - -> restored - -> completed -``` - -Final states: - -```text -completed -cancelled -failed -``` - ---- - -## SFTP User Lifecycle - -The service creates one temporary SFTP user per active migration. - -Important behavior: - -- active jobs recreate SFTP users on service startup -- completed jobs should not recreate SFTP users -- cancelled jobs should not recreate SFTP users -- failed jobs should not recreate SFTP users unless intentionally reactivated -- completing or cancelling a job removes or disables the temporary SFTP access - ---- - -## Manual Browser Workflow - -1. Create migration job in the Web UI. -2. Upload database backup through the browser. -3. The service creates `manifest.json` automatically. -4. Trigger database restore. -5. Upload file directories through SFTP. -6. Mark upload as complete. -7. Validate upload. -8. Run restore. -9. Complete migration and remove SFTP access. - ---- - -## SFTP Upload - -The Web UI shows the SFTP credentials and example commands. - -Typical rclone setup: - -```bash -rclone config create romexis-migration sftp \ - host \ - port \ - user \ - pass "$(rclone obscure '')" -``` - -Upload images: - -```bash -rclone sync "/PATH/TO/LOCAL/romexis_images" \ - "romexis-migration:/romexis_images" \ - --progress \ - --transfers 4 \ - --checkers 8 -``` - -Upload ergo data: - -```bash -rclone sync "/PATH/TO/LOCAL/romexis_ergodata" \ - "romexis-migration:/romexis_ergodata" \ - --progress \ - --transfers 4 \ - --checkers 8 -``` - -Optional cache upload: - -```bash -rclone sync "/PATH/TO/LOCAL/romexis_cache" \ - "romexis-migration:/romexis_cache" \ - --progress \ - --transfers 4 \ - --checkers 8 -``` - ---- - -## Restart Coordination - -The migration service and Romexis container coordinate restarts using a shared state file: - -```text -/data/romexis_images/.romexis_restart_state -``` - -The migration service writes a pending restart request. - -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. +# Migration Service + +The Romexis Migration Service helps migrate an existing Romexis installation into the Docker-based Romexis Server stack. + +It provides: + +- Flask Web UI +- REST API +- temporary SFTP users +- migration job state tracking +- database backup upload +- manifest creation +- upload validation +- restore orchestration +- final completion/cancellation workflow + +--- + +## Why a Migration Service? + +Romexis installations can contain: + +- large SQL Server backups +- large image directories +- ergo data directories +- cache directories +- many small files + +Browser uploads alone are not ideal for this. Therefore the migration service combines: + +```text +Web UI / API + for orchestration and state + +SFTP + for large file and directory transfer +``` + +--- + +## Migration Job State + +Migration jobs are stored as JSON state files. + +Typical workflow: + +```text +created + -> database_uploaded + -> database_restored + -> upload_complete + -> validated + -> restored + -> completed +``` + +Final states: + +```text +completed +cancelled +failed +``` + +--- + +## SFTP User Lifecycle + +The service creates one temporary SFTP user per active migration. + +Important behavior: + +- active jobs recreate SFTP users on service startup +- completed jobs should not recreate SFTP users +- cancelled jobs should not recreate SFTP users +- failed jobs should not recreate SFTP users unless intentionally reactivated +- completing or cancelling a job removes or disables the temporary SFTP access + +--- + +## Manual Browser Workflow + +1. Create migration job in the Web UI. +2. Upload database backup through the browser. +3. The service creates `manifest.json` automatically. +4. Trigger database restore. +5. Upload file directories through SFTP. +6. Mark upload as complete. +7. Validate upload. +8. Run restore. +9. Complete migration and remove SFTP access. + +--- + +## SFTP Upload + +The Web UI shows the SFTP credentials and example commands. + +Typical rclone setup: + +```bash +rclone config create romexis-migration sftp \ + host \ + port \ + user \ + pass "$(rclone obscure '')" +``` + +Upload images: + +```bash +rclone sync "/PATH/TO/LOCAL/romexis_images" \ + "romexis-migration:/romexis_images" \ + --progress \ + --transfers 4 \ + --checkers 8 +``` + +Upload ergo data: + +```bash +rclone sync "/PATH/TO/LOCAL/romexis_ergodata" \ + "romexis-migration:/romexis_ergodata" \ + --progress \ + --transfers 4 \ + --checkers 8 +``` + +Optional cache upload: + +```bash +rclone sync "/PATH/TO/LOCAL/romexis_cache" \ + "romexis-migration:/romexis_cache" \ + --progress \ + --transfers 4 \ + --checkers 8 +``` + +--- + +## Restart Coordination + +The migration service and Romexis container coordinate restarts using a shared state file: + +```text +/data/romexis_images/.romexis_restart_state +``` + +The migration service writes a pending restart request. + +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. diff --git a/Migration-Workflow.md b/Migration-Workflow.md index f24c32a..6b83d36 100644 --- a/Migration-Workflow.md +++ b/Migration-Workflow.md @@ -1,163 +1,163 @@ -# Migration Workflow - -This page describes the target migration workflow from an existing Romexis server into the Docker-based Romexis stack. - ---- - -## Source System - -The source system is usually a Windows-based Romexis server. - -Required data: - -```text -SQL Server database backup (.bak) -Romexis image directory -Romexis ergo data directory -optional Romexis cache directory -``` - -The cache directory is optional because it can usually be regenerated. - ---- - -## Target System - -The target system runs: - -```text -Romexis Server container -Database backend container -Migration Service container -Persistent data volumes -``` - ---- - -## Workflow Overview - -```text -Existing Romexis Server - | - | database backup - | image data - | ergo data - v -Romexis Migration Service - | - | validation - | database restore - | data restore - v -Docker-based Romexis Server -``` - ---- - -## Manual Workflow - -1. Open the migration Web UI. -2. Create a new migration job. -3. Upload the database backup in the browser. -4. Let the service create `manifest.json`. -5. Trigger database restore. -6. Upload images and ergo data via SFTP. -7. Mark upload complete. -8. Validate uploaded data. -9. Run restore. -10. Complete migration. -11. SFTP credentials are removed or disabled. - ---- - -## Client-Assisted Workflow - -The migration client is intended to automate most source-side steps: - -1. detect Romexis installation -2. detect database configuration -3. detect data directories -4. create or use a migration job -5. create database backup -6. upload data through rclone/SFTP -7. call API endpoints to advance the workflow -8. show logs and restore status - ---- - -## Expected Upload Layout - -```text -/upload/ -├── meta/ -│ └── manifest.json -├── database/ -│ └── Romexis_db.bak -├── romexis_images/ -├── romexis_ergodata/ -└── romexis_cache/ -``` - ---- - -## Manifest - -The manifest describes the uploaded migration data. - -Example: - -```json -{ - "migration_id": "example", - "name": "Example Migration", - "source_host": "old-romexis-server", - "database": { - "backup": "database/Romexis_db.bak" - }, - "romexis_images": true, - "romexis_ergodata": true, - "romexis_cache": false -} -``` - -The manual browser workflow can generate this automatically after database upload. - ---- - -## Validation - -Validation should check: - -- manifest exists -- database backup exists -- image directory exists -- ergo data directory exists -- optional cache directory exists if requested -- file counts -- total bytes -- future checksum data - ---- - -## Restore - -The restore step performs or coordinates: - -1. database restore -2. file placement into target volumes -3. permission fixes -4. Romexis restart -5. final status reporting - ---- - -## Completion - -After successful restore, the job should be marked completed. - -Completion should: - -- remove or disable temporary SFTP user -- hide workflow action buttons -- keep logs available -- preserve migration state file for audit/debugging +# Migration Workflow + +This page describes the target migration workflow from an existing Romexis server into the Docker-based Romexis stack. + +--- + +## Source System + +The source system is usually a Windows-based Romexis server. + +Required data: + +```text +SQL Server database backup (.bak) +Romexis image directory +Romexis ergo data directory +optional Romexis cache directory +``` + +The cache directory is optional because it can usually be regenerated. + +--- + +## Target System + +The target system runs: + +```text +Romexis Server container +Database backend container +Migration Service container +Persistent data volumes +``` + +--- + +## Workflow Overview + +```text +Existing Romexis Server + | + | database backup + | image data + | ergo data + v +Romexis Migration Service + | + | validation + | database restore + | data restore + v +Docker-based Romexis Server +``` + +--- + +## Manual Workflow + +1. Open the migration Web UI. +2. Create a new migration job. +3. Upload the database backup in the browser. +4. Let the service create `manifest.json`. +5. Trigger database restore. +6. Upload images and ergo data via SFTP. +7. Mark upload complete. +8. Validate uploaded data. +9. Run restore. +10. Complete migration. +11. SFTP credentials are removed or disabled. + +--- + +## Client-Assisted Workflow + +The migration client is intended to automate most source-side steps: + +1. detect Romexis installation +2. detect database configuration +3. detect data directories +4. create or use a migration job +5. create database backup +6. upload data through rclone/SFTP +7. call API endpoints to advance the workflow +8. show logs and restore status + +--- + +## Expected Upload Layout + +```text +/upload/ +├── meta/ +│ └── manifest.json +├── database/ +│ └── Romexis_db.bak +├── romexis_images/ +├── romexis_ergodata/ +└── romexis_cache/ +``` + +--- + +## Manifest + +The manifest describes the uploaded migration data. + +Example: + +```json +{ + "migration_id": "example", + "name": "Example Migration", + "source_host": "old-romexis-server", + "database": { + "backup": "database/Romexis_db.bak" + }, + "romexis_images": true, + "romexis_ergodata": true, + "romexis_cache": false +} +``` + +The manual browser workflow can generate this automatically after database upload. + +--- + +## Validation + +Validation should check: + +- manifest exists +- database backup exists +- image directory exists +- ergo data directory exists +- optional cache directory exists if requested +- file counts +- total bytes +- future checksum data + +--- + +## Restore + +The restore step performs or coordinates: + +1. database restore +2. file placement into target volumes +3. permission fixes +4. Romexis restart +5. final status reporting + +--- + +## Completion + +After successful restore, the job should be marked completed. + +Completion should: + +- remove or disable temporary SFTP user +- hide workflow action buttons +- keep logs available +- preserve migration state file for audit/debugging diff --git a/Payload-Images.md b/Payload-Images.md index 5e814d8..02e0441 100644 --- a/Payload-Images.md +++ b/Payload-Images.md @@ -1,135 +1,135 @@ -# Payload Images - -Payload images are reusable intermediate images containing extracted installer content. - ---- - -## Windows Payload - -Directory: - -```text -romexis-payload/ -``` - -Purpose: - -- download official Windows installer -- extract required InstallShield CAB components -- build `/opt/romexis` -- extract MSSQL initialization SQL files -- write `/opt/romexis/version` - -Output contract: - -```text -/opt/romexis -/opt/romexis-mssql-db -/opt/romexis/version -/opt/romexis/server/RomexisServer.jar -``` - -The payload must not contain architecture-specific runtime libraries like Chilkat. - ---- - -## Version File - -Supported Windows installer URLs are maintained in: - -```text -romexis-payload/romexis-versions.env -``` - -Example: - -```text -6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip -``` - ---- - -## Copy Map - -Installer extraction is controlled by: - -```text -romexis-payload/romexis-copy-map.tsv -``` - -Format: - -```text -SourceDestination -``` - -Example: - -```text -Server_jar /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. - ---- - -## Firebird Payload - -Directory: - -```text -romexis-firebird-payload/ -``` - -Purpose: - -- download official macOS DMG -- extract PKG payloads -- collect Firebird database SQL scripts -- collect original backup/restore helper scripts -- include `romexis_new.fdb` as reference/template - -Output contract: - -```text -/opt/romexis-firebird-db/version -/opt/romexis-firebird-db/scripts -/opt/romexis-firebird-db/tools -/opt/romexis-firebird-db/templates -/opt/romexis-firebird-db/layout -``` - -Important files: - -```text -/opt/romexis-firebird-db/scripts/rxdb.sh -/opt/romexis-firebird-db/scripts/rxupd.sh -/opt/romexis-firebird-db/scripts/RX_Base_10fb_MAC.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_Restore.sh -/opt/romexis-firebird-db/templates/romexis_new.fdb -``` - ---- - -## Inspecting a Payload Image - -If a payload image is based on `scratch`, it may not have a shell. - -Use: - -```bash -docker save gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest -o payload.tar -mkdir payload rootfs -tar -xf payload.tar -C payload -tar -xf payload//layer.tar -C rootfs -find rootfs/opt -type f | sort -``` - -If the image includes a shell: - -```bash -docker run --rm -it --entrypoint sh gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest -``` +# Payload Images + +Payload images are reusable intermediate images containing extracted installer content. + +--- + +## Windows Payload + +Directory: + +```text +romexis-payload/ +``` + +Purpose: + +- download official Windows installer +- extract required InstallShield CAB components +- build `/opt/romexis` +- extract MSSQL initialization SQL files +- write `/opt/romexis/version` + +Output contract: + +```text +/opt/romexis +/opt/romexis-mssql-db +/opt/romexis/version +/opt/romexis/server/RomexisServer.jar +``` + +The payload must not contain architecture-specific runtime libraries like Chilkat. + +--- + +## Version File + +Supported Windows installer URLs are maintained in: + +```text +romexis-payload/romexis-versions.env +``` + +Example: + +```text +6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip +``` + +--- + +## Copy Map + +Installer extraction is controlled by: + +```text +romexis-payload/romexis-copy-map.tsv +``` + +Format: + +```text +SourceDestination +``` + +Example: + +```text +Server_jar /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. + +--- + +## Firebird Payload + +Directory: + +```text +romexis-firebird-payload/ +``` + +Purpose: + +- download official macOS DMG +- extract PKG payloads +- collect Firebird database SQL scripts +- collect original backup/restore helper scripts +- include `romexis_new.fdb` as reference/template + +Output contract: + +```text +/opt/romexis-firebird-db/version +/opt/romexis-firebird-db/scripts +/opt/romexis-firebird-db/tools +/opt/romexis-firebird-db/templates +/opt/romexis-firebird-db/layout +``` + +Important files: + +```text +/opt/romexis-firebird-db/scripts/rxdb.sh +/opt/romexis-firebird-db/scripts/rxupd.sh +/opt/romexis-firebird-db/scripts/RX_Base_10fb_MAC.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_Restore.sh +/opt/romexis-firebird-db/templates/romexis_new.fdb +``` + +--- + +## Inspecting a Payload Image + +If a payload image is based on `scratch`, it may not have a shell. + +Use: + +```bash +docker save gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest -o payload.tar +mkdir payload rootfs +tar -xf payload.tar -C payload +tar -xf payload//layer.tar -C rootfs +find rootfs/opt -type f | sort +``` + +If the image includes a shell: + +```bash +docker run --rm -it --entrypoint sh gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest +``` diff --git a/Project-Overview.md b/Project-Overview.md index 9ae3db3..62a1771 100644 --- a/Project-Overview.md +++ b/Project-Overview.md @@ -1,124 +1,171 @@ -# Project Overview - -## Purpose - -The Romexis Docker project provides a reproducible Docker-based environment for running Planmeca Romexis Server on Linux. - -The project is designed to: - -- run Romexis Server in containers -- keep runtime configuration externalized -- avoid manual Windows-style setup steps -- support persistent application and database data -- support migration from existing installations -- support repeatable CI/CD builds -- prepare a path for both Microsoft SQL Server and Firebird database backends - ---- - -## Design Principles - -### No Romexis binaries in Git - -The repository does not contain Romexis application binaries. - -Instead, the build process downloads official installer packages and extracts only the required server components into payload images. - -### Layered image architecture - -The build system is split into reusable layers: - -```text -Payload image - Contains extracted Romexis application files and SQL payload. - -Base image - Contains reusable runtime dependencies such as Java, JavaFX and database tools. - -Server image - Combines payload + base + runtime scripts + Java agent. -``` - -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. - -This allows the same payload to be reused for both: - -```text -linux/amd64 -linux/arm64 -``` - -### Database backend flexibility - -Microsoft SQL Server remains the default backend. - -Firebird support is being added in parallel because macOS-based Romexis installations use Firebird and because this path is more realistic for ARM64 environments. - ---- - -## Main Features - -- Romexis Server 6.5 Docker runtime -- Microsoft SQL Server 2022 support -- Firebird backend preparation -- automatic database initialization -- persistent runtime volumes -- Java Property Agent for runtime property injection -- versioned payload images -- multi-architecture base and server images -- Drone CI/CD pipeline -- migration service with Web UI, REST API and SFTP -- Windows migration client -- Gitea package registry publishing - ---- - -## Supported Platforms - -| Platform | Status | -|---|---| -| linux/amd64 | Primary supported target | -| linux/arm64 | Supported for Romexis runtime images | -| Microsoft SQL Server on amd64 | Default backend | -| Firebird on amd64/arm64 | In progress / experimental | -| 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 installer Firebird SQL payload extraction. - -romexis/ - Final Romexis Server image. - -migration-service/ - Migration orchestration service. - -migration-client/ - Migration helper client. - -docs/ - Extended documentation. - -docker-compose.yml - Default runtime stack. - -docker-compose.firebird.yml - Firebird runtime variant. - -.drone.yml - CI/CD pipeline. -``` +# Project Overview + +## Purpose + +The Romexis Docker project provides a reproducible Docker-based environment for running Planmeca Romexis Server on Linux. + +The project is designed to: + +- run Romexis Server in containers +- keep runtime configuration externalized +- select the database backend through Docker Compose configuration +- avoid manual Windows-style setup steps +- support persistent application and database data +- provide browser-based access to Romexis Admin / RomexisConfig +- 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 + +--- + +## Main Runtime Services + +```text +romexis + Romexis Server backend runtime. + +mssql / firebird + Selected database backend loaded through Compose override files. + +romexis-admin + Browser-accessible Romexis Admin / RomexisConfig runtime using noVNC. + +romexis-app + Tomcat-based mRomexis Web App container. + +proxy + OpenResty/Nginx proxy for mRomexis Web App backend access. + +romexis-migration + Optional migration service for MSSQL-based migration workflows. +``` + +--- + +## Design Principles + +### No Romexis binaries in Git + +The repository does not contain Romexis application binaries. + +Instead, the build process downloads official installer packages and extracts only the required server, admin and web components into payload images. + +### Layered image architecture + +The build system is split into reusable layers: + +```text +Payload image + Contains extracted Romexis application files, SQL payload and web/admin artifacts. + +Base image + Contains reusable runtime dependencies such as Java, JavaFX and database tools. + +Service images + Build server, admin, migration and mRomexis runtime containers from the prepared layers. +``` + +### Architecture-independent payloads + +The Romexis payload itself is architecture independent. Architecture-specific parts such as native libraries remain in service runtime images. + +The same payload can be reused for: + +```text +linux/amd64 +linux/arm64 +``` + +### Compose-based backend selection + +Database backends are selected through `.env`: + +```env +DATABASE_BACKEND=mssql +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +The backend-specific Compose override sets the correct database service and Romexis database environment values. + +--- + +## Main Features + +- Romexis Server 6.5 Docker runtime +- Microsoft SQL Server 2022 backend +- Firebird backend through Compose override +- automatic database initialization +- persistent runtime volumes +- Java Property Agent for server-side runtime property injection +- versioned payload images +- multi-architecture service images +- Romexis Admin container with browser/noVNC access +- VNC-session-controlled Admin lifecycle +- localized Admin splash screen +- mRomexis Web App container for Romexis 6.5.3 and newer +- OpenResty/Nginx proxy for mRomexis backend requests +- local build scripts for Linux/macOS and Windows +- Drone CI/CD pipeline +- migration service with Web UI, REST API and SFTP +- Windows migration client +- Gitea package registry publishing + +--- + +## Supported Platforms + +| Platform | Status | +|---|---| +| linux/amd64 | Primary supported target | +| linux/arm64 | Supported for Romexis runtime images | +| Microsoft SQL Server on amd64 | Default backend | +| 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. +``` diff --git a/Project-Structure.md b/Project-Structure.md index 1353404..5003366 100644 --- a/Project-Structure.md +++ b/Project-Structure.md @@ -1,63 +1,102 @@ -# Project Structure - -```text -. -├── .drone.yml -├── .env.sample -├── docker-compose.yml -├── docker-compose.firebird.yml -├── README.md -├── README.de.md -├── docs/ -│ ├── BUILD.md -│ ├── DEVELOPERS.md -│ ├── MIGRATION_README.md -│ └── MIGRATION_WORKFLOW.md -├── romexis-base/ -│ └── Dockerfile -├── romexis-payload/ -│ ├── Dockerfile -│ ├── romexis-versions.env -│ ├── romexis-copy-map.tsv -│ ├── download-romexis-installer-parts.py -│ └── extract-and-copy-romexis-parts.sh -├── romexis-firebird-payload/ -│ ├── Dockerfile -│ ├── romexis-firebird-versions.env -│ └── helper scripts -├── romexis/ -│ ├── Dockerfile -│ ├── entrypoint.sh -│ ├── init-romexis-db.sh -│ ├── init-romexis-mssql-db.sh -│ ├── init-romexis-firebird-db.sh -│ ├── fix-keystore-alias.sh -│ └── RomexisPropertyAgent.java -├── migration-service/ -│ ├── Dockerfile -│ ├── entrypoint.sh -│ ├── app/ -│ ├── scripts/ -│ └── ssh/ -└── migration-client/ - └── client files -``` - ---- - -## Root README Files - -Only the main README files should stay at repository root: - -```text -README.md -README.de.md -``` - -Extended documentation belongs in: - -```text -docs/ -``` - -The wiki can then provide a navigable, user-facing documentation layer. +# Project Structure + +```text +. +├── .drone.yml +├── .env.sample +├── docker-compose.yml +├── docker-compose.mssql.yml +├── docker-compose.firebird.yml +├── README.md +├── README.de.md +├── BUILD.md +├── BUILD.de.md +├── DEVELOPERS.md +├── scripts/ +│ ├── build-local.sh +│ └── build-local.ps1 +├── romexis-base/ +│ └── Dockerfile +├── romexis-payload/ +│ ├── Dockerfile +│ ├── romexis-versions.env +│ ├── romexis-copy-map.tsv +│ ├── download-romexis-installer-parts.py +│ └── extract-and-copy-romexis-parts.sh +├── romexis-firebird-payload/ +│ ├── Dockerfile +│ ├── romexis-firebird-versions.env +│ └── helper scripts +├── romexis/ +│ ├── Dockerfile +│ ├── entrypoint.sh +│ ├── init-romexis-db.sh +│ ├── init-romexis-mssql-db.sh +│ ├── init-romexis-firebird-db.sh +│ ├── fix-keystore-alias.sh +│ └── RomexisPropertyAgent.java +├── romexis-admin/ +│ ├── Dockerfile +│ ├── start.sh +│ └── native helper sources +├── romexis-mromexis-app/ +│ ├── Dockerfile +│ └── nginx.conf +├── migration-service/ +│ ├── Dockerfile +│ ├── entrypoint.sh +│ ├── app/ +│ ├── scripts/ +│ └── ssh/ +└── migration-client/ + └── client files +``` + +--- + +## Compose Files + +```text +docker-compose.yml + Base runtime stack. + +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. diff --git a/Quick-Start.md b/Quick-Start.md index 3b872ae..55049d5 100644 --- a/Quick-Start.md +++ b/Quick-Start.md @@ -1,168 +1,206 @@ -# Quick Start - -## 1. Prepare environment - -Copy the sample environment file: - -```bash -cp .env.sample .env -``` - -Edit `.env` and set at least: - -```env -ROMEXIS_VERSION=6.5.3.444.203 -TARGETARCH=amd64 - -REGISTRY=gitea.buchhorster.de/patrick -ROMEXIS_IMAGE=romexis-server - -HOST_IP= - -MSSQL_SA_PASSWORD= -ROMEXIS_DB_PASSWORD= -``` - -or create minimal one - -```env -ROMEXIS_VERSION=6.5.3.444.203 -TARGETARCH=amd64 - -REGISTRY=gitea.buchhorster.de/planmeca -ROMEXIS_IMAGE=romexis-server -MIGRATION_IMAGE=romexis-migration-service - -SERVER_DB=5 - -HOST_IP=192.168.65.100 # Replace IP with Host IP - -MSSQL_PORT=1433 -MSSQL_SA_PASSWORD=Pwr0mex!s!!! -MSSQL_PID=Express - -ROMEXIS_DB_NAME=Romexis_db -ROMEXIS_DB_USER=romexis -ROMEXIS_DB_PASSWORD=romexis - -SERVER_RMI_LOW_PORT=1100 -SERVER_RMI_HIGH_PORT=1120 - -ROMEXIS_DATA_ROOT=/srv/romexis-data -DATABASE_BACKUP_DIR=/srv/mssql-backup - -MIGRATION_HTTP_PORT=8080 -MIGRATION_SFTP_PORT=2222 -MIGRATION_API_TOKEN=change-me -``` - - ---- - -## 2. Start default MSSQL stack - -```bash -docker compose up -d -``` - -Show logs: - -```bash -docker compose logs -f romexis -docker compose logs -f mssql -``` - ---- - -## 3. Start Firebird stack - -If using the Firebird compose variant (with firebird setiings in .env file): - -```bash -docker compose -f docker-compose.firebird.yml up -d -``` - -Or combine the base compose file with a Firebird override: - -```bash -docker compose -f docker-compose.yml -f docker-compose.firebird.yml up -d -``` - ---- - -## 4. Recreate after image changes - -```bash -docker compose up --force-recreate -d -``` - -With rebuild: - -```bash -docker compose up --build --force-recreate -d -``` - -No cache rebuild: - -```bash -docker compose build --no-cache --pull -docker compose up --force-recreate -d -``` - ---- - -## 5. Open a shell in the Romexis container - -```bash -docker exec -it romexis-server bash -``` - -If bash is unavailable: - -```bash -docker exec -it romexis-server sh -``` - -With Compose: - -```bash -docker compose exec romexis bash -``` - ---- - -## 6. Check database initialization - -Inside the Romexis container: - -```bash -/opt/init-romexis-db.sh -``` - -Verbose database initialization: - -```bash -DB_CREATE_VERBOSE=1 /opt/init-romexis-db.sh -``` - -For Firebird debugging: - -```bash -ISQL=isql-fb DB_CREATE_VERBOSE=1 bash -x /opt/init-romexis-firebird-db.sh -``` - ---- - -## 7. 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/application data. +# Quick Start + +## 1. Prepare environment + +Copy the sample environment file: + +```bash +cp .env.sample .env +``` + +Edit `.env` and set at least the Romexis version, registry namespace, backend selection and passwords. + +Minimal MSSQL example: + +```env +REGISTRY=gitea.buchhorster.de/planmeca +ROMEXIS_VERSION=6.5.3.444.203 +IMAGE_SUFFIX= + +ROMEXIS_IMAGE=romexis-server +MIGRATION_IMAGE=romexis-migration-service +ADMINISTRATION_IMAGE=romexis-admin +MROMEXIS_WEBAPP_IMAGE=romexis-mromexis-app + +DATABASE_BACKEND=mssql +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml + +HOST_IP=192.168.65.100 + +MSSQL_PORT=1433 +MSSQL_SA_PASSWORD=Pwr0mex!s!!! +MSSQL_PID=Express + +ROMEXIS_DB_NAME=Romexis_db +ROMEXIS_DB_USER=romexis +ROMEXIS_DB_PASSWORD=romexis + +SERVER_RMI_LOW_PORT=1100 +SERVER_RMI_HIGH_PORT=1120 + +ROMEXIS_DATA_ROOT=/srv/romexis-data +DATABASE_BACKUP_DIR=/srv/romexis-data/sql-backup + +ADMIN_NOVNC_PORT=6080 +ADMIN_VNC_PORT=5900 +ADMIN_VNC_PASSWORD=promax +ADMIN_RESOLUTION=1280x900x24 +ADMIN_LANGUAGE=de +DEBUG_XTERM=false +ADMIN_VNC_LIFECYCLE=true + +MROMEXIS_WEB_PORT=8081 + +MIGRATION_HTTP_PORT=8080 +MIGRATION_SFTP_PORT=2222 +MIGRATION_API_TOKEN=change-me +``` + +For Firebird, change the backend selection: + +```env +DATABASE_BACKEND=firebird +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +--- + +## 2. Start the selected stack + +After `.env` is configured, the same command is used for MSSQL and Firebird: + +```bash +docker compose up -d +``` + +Show the effective Compose configuration: + +```bash +docker compose config +``` + +--- + +## 3. Show logs + +```bash +docker compose logs -f romexis +``` + +Database backend logs: + +```bash +docker compose logs -f mssql +# or +docker compose logs -f firebird +``` + +Admin container logs: + +```bash +docker compose logs -f romexis-admin +``` + +mRomexis Web App logs: + +```bash +docker compose logs -f romexis-app +``` + +--- + +## 4. Open browser-based services + +Romexis Admin / RomexisConfig through noVNC: + +```text +http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true +``` + +mRomexis Web App through the proxy: + +```text +http://localhost:8081 +``` + +Adjust the ports if `ADMIN_NOVNC_PORT` or `MROMEXIS_WEB_PORT` were changed in `.env`. + +--- + +## 5. Recreate after image changes + +```bash +docker compose up -d --force-recreate +``` + +Pull and recreate: + +```bash +docker compose pull +docker compose up -d --force-recreate +``` + +--- + +## 6. Open shells 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 shell: + +```bash +docker compose run --rm --entrypoint /bin/bash romexis-app +``` + +--- + +## 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. diff --git a/Reference-BUILD.de.md b/Reference-BUILD.de.md index 4229874..8629840 100644 --- a/Reference-BUILD.de.md +++ b/Reference-BUILD.de.md @@ -2,7 +2,7 @@ [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: - reproduzierbare Docker-Builds -- wiederverwendbares Runtime-Basisimage +- wiederverwendbare Image-Schichten +- lokale Entwickler-Builds über Skripte - native `amd64`- und `arm64`-Images - Multiarch-Manifeste - minimale finale Runtime-Images - 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: +``` ### 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 -- Microsoft SQL Server Kommandozeilenwerkzeuge -- Firebird-Clienttools und Bibliotheken -- gemeinsame Betriebssystem-Laufzeitbibliotheken +Enthält gemeinsame Server-Laufzeitabhängigkeiten wie Java, JavaFX/OpenJFX-Unterstützung, SQL-Werkzeuge, Firebird-Clientbibliotheken und gemeinsame Betriebssystembibliotheken. Tags: ```text 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 ``` -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 -Das Server Image wird aus `romexis/Dockerfile` gebaut. +Gebaut aus: -Es enthält: +```text +romexis/Dockerfile +``` -- extrahierte Romexis-Serverdateien -- Romexis-Datenbank-SQL-Skripte -- native Chilkat-Laufzeitbibliothek -- Romexis Java Property Agent -- Runtime-Hilfsskripte -- Entrypoint- und Initialisierungslogik +Verwendet: -Architekturspezifische Tags: +```text +romexis-payload: +romexis-base-jre:11- +``` + +Ergänzt: + +- native Chilkat-Laufzeit +- Romexis Java PropertyAgent +- Server-Entrypoint +- Datenbankinitialisierung +- KeyVault- und Pfadvorbereitung + +Tags: ```text gitea.buchhorster.de/planmeca/romexis-server:-amd64 gitea.buchhorster.de/planmeca/romexis-server:-arm64 -``` - -Multiarch-Manifest-Tag: - -```text gitea.buchhorster.de/planmeca/romexis-server: ``` ---- +### 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 | -|---------|--------------| -| `TARGETARCH` | Zielarchitektur, normalerweise `amd64` oder `arm64`. | -| `ROMEXIS_VERSION` | Angeforderte Romexis-Version oder Versionspräfix. | +Tags: -### 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 | -|---------|--------------| -| `IMAGE_VERSION` | OCI-Image-Label-Version des Base Images. | +### Romexis Admin Image -### Server-Image-Argumente +Gebaut aus: -| Argument | Beschreibung | -|---------|--------------| -| `ROMEXIS_BASE_IMAGE` | Basisimage-Referenz für die finale Romexis-Server-Stage. | -| `CHILKAT_VERSION` | Version der nativen Chilkat-Bibliothek. | +```text +romexis-admin/Dockerfile +``` + +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:-amd64 +gitea.buchhorster.de/planmeca/romexis-admin:-arm64 +gitea.buchhorster.de/planmeca/romexis-admin: +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:-amd64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-arm64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app: +gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest +``` --- ## Versionsauflösung -Romexis-Versionen werden in folgender Datei definiert: +Unterstützte Romexis-Versionen werden in folgender Datei definiert: ```text romexis-payload/romexis-versions.env @@ -110,106 +196,84 @@ Format: Build-Eingabe: -```bash -ROMEXIS_VERSION=6.5.3 +```env +ROMEXIS_VERSION=6.5.3.444.203 ``` -Das Dockerfile löst den neuesten passenden Eintrag auf und schreibt die tatsächlich verwendete Version nach: - -```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. +Die CI-Pipeline iteriert über diese Datei und baut die benötigten Image-Familien für die verfügbaren Versionen. --- -## 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: - -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: +Lokale Builds werden ausgeführt über: ```text -romexis-payload/romexis-copy-map.tsv +scripts/build-local.sh +scripts/build-local.ps1 ``` -ist die zentrale Zuordnung zwischen Installer-Komponenten und Zielverzeichnissen. - -Format: - -```text -SourceDestination -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 +### Linux/macOS ```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 -TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis +```powershell +.\scripts\build-local.ps1 -Targets all ``` -### Lokal gebauten Stack starten +### Ausgewählte Image-Familien bauen ```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 -TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build --no-cache romexis-base -TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build --no-cache romexis +```env +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 +``` + +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 @@ -227,52 +291,6 @@ docker buildx 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 \ - --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 docker buildx build \ --platform linux/amd64 \ @@ -287,54 +305,96 @@ docker buildx build \ ./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 -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 - 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 - vorhandenes Payload ohne relevante Änderung: überspringen -Veröffentlichte Image-Familien: +### mRomexis-Versionsregel + +mRomexis-WebApp-Images werden nur gebaut, wenn gilt: ```text -romexis-payload: -romexis-base-jre:11-amd64 -romexis-base-jre:11-arm64 -romexis-base-jre:11 -romexis-server:-amd64 -romexis-server:-arm64 -romexis-server: -romexis-migration-service:amd64 -romexis-migration-service:arm64 -romexis-migration-service:latest +version >= 6.5.3 ``` +Ä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. -2. `romexis-server:-amd64` bauen und veröffentlichen. -3. `romexis-base-jre:11-arm64` bauen und veröffentlichen. -4. `romexis-server:-arm64` bauen und veröffentlichen. -5. Multiarch-Manifest erstellen und veröffentlichen. +```text +:-amd64 +:-arm64 +``` -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 +: +``` + +Für ausgewählte Dienste wird zusätzlich ein `latest` Alias aus der Default-Romexis-Version in `.env.sample` erzeugt. + +Buildx verwendet: ```bash --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 -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 +Für `main` bleibt `IMAGE_SUFFIX` leer: + +```env +IMAGE_SUFFIX= ``` -Für CI: +Für Feature-Branches wird ein Branch-Suffix verwendet: -```text -base amd64 -> server amd64 -> base arm64 -> server arm64 -> manifest +```env +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 @@ -377,23 +479,19 @@ Das finale Server Image enthält: /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: - -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. +```text +/usr/local/tomcat/webapps/ROOT.war +``` diff --git a/Reference-BUILD.md b/Reference-BUILD.md index cfe3eb1..1fe6ddd 100644 --- a/Reference-BUILD.md +++ b/Reference-BUILD.md @@ -2,7 +2,7 @@ [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: - reproducible Docker builds -- a reusable runtime base image +- reusable image layers +- local developer builds through scripts - native `amd64` and `arm64` images - multi-architecture manifests - minimal final runtime images - 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: +``` ### 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 -- Microsoft SQL Server command-line tools -- Firebird client tools and libraries -- common operating system runtime libraries +Contains shared server runtime dependencies such as Java, JavaFX/OpenJFX support, SQL tooling, Firebird client libraries and common OS libraries. Tags: ```text 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 ``` -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 -The server image is built from `romexis/Dockerfile`. +Built from: -It contains: +```text +romexis/Dockerfile +``` -- extracted Romexis server files -- Romexis database SQL scripts -- native Chilkat runtime library -- Romexis Java property agent -- runtime helper scripts -- entrypoint and initialization logic +Consumes: -Architecture-specific tags: +```text +romexis-payload: +romexis-base-jre:11- +``` + +Adds: + +- native Chilkat runtime +- Romexis Java PropertyAgent +- server entrypoint +- database initialization scripts +- KeyVault and path preparation logic + +Tags: ```text gitea.buchhorster.de/planmeca/romexis-server:-amd64 gitea.buchhorster.de/planmeca/romexis-server:-arm64 -``` - -Multi-architecture manifest tag: - -```text gitea.buchhorster.de/planmeca/romexis-server: ``` ---- +### 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 | -|---------|-------------| -| `TARGETARCH` | Target architecture, usually `amd64` or `arm64`. | -| `ROMEXIS_VERSION` | Requested Romexis version or version prefix. | +Tags: -### 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 | -|---------|-------------| -| `IMAGE_VERSION` | OCI image label version for the base image. | +### Romexis Admin Image -### Server image arguments +Built from: -| Argument | Description | -|---------|-------------| -| `ROMEXIS_BASE_IMAGE` | Base image reference used by the final Romexis Server stage. | -| `CHILKAT_VERSION` | Native Chilkat library version. | +```text +romexis-admin/Dockerfile +``` + +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:-amd64 +gitea.buchhorster.de/planmeca/romexis-admin:-arm64 +gitea.buchhorster.de/planmeca/romexis-admin: +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:-amd64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-arm64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app: +gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest +``` --- ## Version Resolution -Romexis versions are defined in: +Supported Romexis versions are defined in: ```text romexis-payload/romexis-versions.env @@ -110,108 +196,86 @@ Format: Build input: -```bash -ROMEXIS_VERSION=6.5.3 +```env +ROMEXIS_VERSION=6.5.3.444.203 ``` -The Dockerfile resolves the newest matching entry and writes the resolved version to: - -```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. +The CI pipeline iterates over this file and builds the required image families for the available versions. --- -## 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: - -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: +Local builds are handled by: ```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. - -Format: - -```text -SourceDestination -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 +### Linux/macOS ```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 -TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis +```powershell +.\scripts\build-local.ps1 -Targets all ``` -### Start the locally built stack +### Build selected image families ```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 -TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build --no-cache romexis-base -TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build --no-cache romexis +```env +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 +``` + +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 docker buildx build \ @@ -225,53 +289,7 @@ docker buildx build \ ./romexis-base ``` -### 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: +### Server Image ```bash docker buildx build \ @@ -287,54 +305,96 @@ docker buildx build \ ./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 -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 - changed URL for an existing version: rebuild that version - changed `romexis-copy-map.tsv`, payload Dockerfile or helper scripts: rebuild all payload versions - 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 -romexis-payload: -romexis-base-jre:11-amd64 -romexis-base-jre:11-arm64 -romexis-base-jre:11 -romexis-server:-amd64 -romexis-server:-arm64 -romexis-server: -romexis-migration-service:amd64 -romexis-migration-service:arm64 -romexis-migration-service:latest +version >= 6.5.3 ``` +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`. -2. Build and push `romexis-server:-amd64`. -3. Build and push `romexis-base-jre:11-arm64`. -4. Build and push `romexis-server:-arm64`. -5. Create and push the multi-architecture manifest. +```text +:-amd64 +:-arm64 +``` -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 +: +``` + +For selected services, a `latest` alias is also created from the default Romexis version configured in `.env.sample`. + +Buildx uses: ```bash --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 -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 `main`, `IMAGE_SUFFIX` is empty: + +```env +IMAGE_SUFFIX= ``` -For CI: +For feature branches, use a branch suffix: -```text -base amd64 -> server amd64 -> base arm64 -> server arm64 -> manifest +```env +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 @@ -377,23 +479,19 @@ The final server image contains: /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: - -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. +```text +/usr/local/tomcat/webapps/ROOT.war +``` diff --git a/Reference-README-compose.md b/Reference-README-compose.md new file mode 100644 index 0000000..bd77126 --- /dev/null +++ b/Reference-README-compose.md @@ -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 +``` diff --git a/Reference-README.de.md b/Reference-README.de.md index a366552..3ab7f10 100644 --- a/Reference-README.de.md +++ b/Reference-README.de.md @@ -1,595 +1,628 @@ -# Romexis Docker - -[English](README.md) | [Deutsch](README.de.md) | [Build-Prozess](BUILD.de.md) | [Entwicklerdokumentation](DEVELOPERS.md) | [![Build Status](https://drone.buchhorster.de/api/badges/planmeca/romexis-server-docker/status.svg?ref=refs/heads/main)] - -> Containerisierte Ausführung von Planmeca Romexis Server 6.5 unter Linux mit Docker, Microsoft SQL Server und einem wiederverwendbaren Multiarch-Romexis-Basisimage. - ---- - -## Überblick - -Dieses Projekt baut und betreibt den Planmeca Romexis Server in Docker. - -Der Build-Prozess extrahiert die benötigten Romexis-Serverdateien direkt aus dem offiziellen Romexis-Windows-Installer. Im Repository werden keine Romexis-Programmbinaries gespeichert. - -Der aktuelle Build ist in Payload-, Base- und Server-Image-Schichten aufgeteilt: - -1. **Romexis Base Image** - - Stellt Java 11 mit JavaFX-Unterstützung bereit. - - Enthält Microsoft SQL Server Kommandozeilenwerkzeuge. - - Enthält Firebird-Clientbibliotheken. - - Wird separat für `amd64` und `arm64` gebaut. - -2. **Romexis Server Image** - - Baut auf dem Romexis Base Image auf. - - Lädt und extrahiert den ausgewählten Romexis-Installer. - - Erstellt die finale `/opt/romexis`-Verzeichnisstruktur. - - Fügt Java Property Agent, Laufzeitskripte und Datenbankinitialisierung hinzu. - -Diese Trennung reduziert Duplikate, vereinfacht die Wartung und erlaubt die Wiederverwendung des Laufzeit-Basisimages für unterschiedliche Romexis-Versionen. - ---- - -## Features - -- Romexis Server 6.5 in Docker -- Microsoft SQL Server 2022 Unterstützung -- Automatische Datenbankinitialisierung -- Persistente Speicherung aller Nutzdaten -- Automatische Vorbereitung von KeyVault und ProgramData -- Unterstützung vorhandener Datenbank-Volumes -- Multi-Stage Docker Build -- Multiarch-Image-Publishing für `amd64` und `arm64` -- Dediziertes wiederverwendbares Romexis Base Image -- Mapping-basierte Installer-Extraktion über `romexis-copy-map.tsv` -- Selektive InstallShield-CAB-Extraktion -- Romexis-Installerversionen werden über `romexis-versions.env` verwaltet -- Keine Windows Registry erforderlich -- Kein RomexisConfig-Aufruf erforderlich -- Linux-kompatible Laufzeitpfade -- Java-Property-Injection über `RomexisPropertyAgent` -- CI/CD Build-Unterstützung über Drone - ---- - -## Architektur - -```text -+----------------------+ -| Romexis Clients | -+----------+-----------+ - | - | RMI / Romexis-Protokollports - v -+----------------------+ -| Romexis Server | -| Docker | -+----------+-----------+ - | - | JDBC - v -+----------------------+ -| Microsoft SQL Server | -| Docker | -+----------------------+ -``` - ---- - -## Unterstützte Plattformen - -Der Build-Prozess unterstützt folgende Zielarchitekturen: - -| Architektur | Docker-Plattform | Tag-Suffix | -|------------|------------------|------------| -| x86_64 | `linux/amd64` | `-amd64` | -| ARM64 | `linux/arm64` | `-arm64` | - -Die Drone-Pipeline erstellt architekturspezifische Images und veröffentlicht anschließend ein Multiarch-Manifest ohne Architektur-Suffix. - ---- - -## Voraussetzungen - -### Laufzeithost - -- Linux-Host -- Docker Engine -- Docker Compose Plugin -- Netzwerkverbindung zwischen Romexis-Clients und den veröffentlichten RMI-Ports - -### Build-Host - -- Docker Engine mit BuildKit-Unterstützung -- Docker Buildx -- Docker Compose Plugin -- Zugriff auf die Romexis-Installer-Download-URLs aus `romexis-payload/romexis-versions.env` -- Zugriff auf die konfigurierte Container-Registry -- Ausreichend Speicherplatz für Installer-Extraktion und Docker-Build-Cache - -### Empfohlene Ressourcen - -- 8 GB RAM -- 4 CPU-Kerne -- 20 GB freier Speicherplatz für den Betrieb -- Zusätzlicher freier Speicherplatz auf Build-Hosts für Build-Cache und extrahierte Installerdateien - ---- - -## Container Images - -Die Images werden in der Gitea Container Registry des Projekts veröffentlicht. - -### Image-Struktur - -```text -gitea.buchhorster.de/planmeca/romexis-base-jre:11-amd64 -gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64 - -gitea.buchhorster.de/planmeca/romexis-server:-amd64 -gitea.buchhorster.de/planmeca/romexis-server:-arm64 -gitea.buchhorster.de/planmeca/romexis-server: -``` - -Die architekturspezifischen Tags werden für das Multiarch-Manifest verwendet. - -### Beispiel-Pull - -```bash -docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203 -``` - -### Installierte Romexis-Version prüfen - -```bash -docker run --rm \ - --entrypoint cat \ - gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203 \ - /opt/romexis/version -``` - ---- - -## Versionsverwaltung - -Die Datei `romexis-payload/romexis-versions.env` ordnet unterstützte Romexis-Versionen den offiziellen Installer-URLs zu. - -Beispiel: - -```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 -``` - -Das Build-Argument `ROMEXIS_VERSION` kann eine vollständige Version oder ein Präfix enthalten. - -Beispiel: - -```bash -ROMEXIS_VERSION=6.5.3 -``` - -Der Build löst dies zur neuesten passenden Version auf, zum Beispiel: - -```text -6.5.3.444.203 -``` - -Die aufgelöste Version wird im Image gespeichert: - -```text -/opt/romexis/version -``` - ---- - -## Projektstruktur - -```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 -``` - ---- - -## Betrieb mit fertigen Images - -Für den normalen Betrieb wird `docker-compose.yml` verwendet. - -```bash -ROMEXIS_VERSION=6.5.3.444.203 docker compose up -d -``` - -Logs anzeigen: - -```bash -docker compose logs -f -``` - -Nur Romexis: - -```bash -docker compose logs -f romexis -``` - -Nur SQL Server: - -```bash -docker compose logs -f mssql -``` - -Umgebung stoppen: - -```bash -docker compose down -``` - ---- - -## Lokaler Build mit Docker Compose - -Für lokale Builds wird `docker-compose.build.yml` verwendet. - -Das Base Image muss vor dem Romexis Server Image gebaut werden, da das Server-Dockerfile das Basisimage über das Build-Argument `ROMEXIS_BASE_IMAGE` verwendet. - -```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 -``` - -Für einen 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 -``` - -Weitere Details stehen in [BUILD.de.md](BUILD.de.md). - ---- - - ---- - -## Aktueller Architekturstand - -Das Projekt verwendet inzwischen drei Build-Schichten statt nur Base- und Server-Image: - -1. **Romexis Payload Image** - - wird aus `romexis-payload/Dockerfile` gebaut - - lädt und extrahiert den offiziellen Romexis-Installer - - enthält `/opt/romexis` und `/opt/romexis-mssql-db` - - ist architekturunabhängig und wird als `romexis-payload:` getaggt - -2. **Romexis Base Image** - - wird aus `romexis-base/Dockerfile` gebaut - - enthält Java, JavaFX, SQL-Tools und gemeinsame Runtime-Bibliotheken - - ist architekturspezifisch - -3. **Romexis Server Image** - - wird aus `romexis/Dockerfile` gebaut - - verwendet Payload Image und Base Image - - ergänzt Chilkat, Java Property Agent, Laufzeitskripte und Startlogik - -Durch das Payload Image müssen Installer-ZIP und CAB-Dateien nicht bei jedem Server-Build erneut heruntergeladen und extrahiert werden. - ---- - -## Migration Service - -Das Repository enthält jetzt einen Romexis Migration Service und einen Windows Migration Client. - -Der Migration Service stellt bereit: - -- Web UI und REST API für Migrationsjobs -- temporäre SFTP-Zugangsdaten pro Job -- Datenbankbackup-Upload über den Browser -- automatische serverseitige `manifest.json`-Erzeugung -- SQL Server Datenbank-Restore -- Upload-Validierung -- Datei-Restore-Workflow -- Abbruch und Bereinigung von Migrationen -- Abschluss einer Migration mit Entfernung des SFTP-Zugangs -- koordinierten Romexis-Neustart über eine gemeinsame State-Datei - -Unterstützte Migrationswege: - -1. **Windows Migration Client** - - erkennt Romexis-Installation, SQL-Server-Konfiguration und Datenverzeichnisse - - erstellt oder nutzt ein Datenbankbackup - - lädt Daten per rclone/SFTP hoch - - kommuniziert mit der Migration Service API - -2. **Manueller Browser- und SFTP-Workflow** - - Migrationsjob im Web UI erstellen - - Datenbankbackup über den Browser hochladen - - Manifest vom Server erzeugen lassen - - `romexis_images`, `romexis_ergodata` und optional `romexis_cache` per SFTP hochladen - - validieren, wiederherstellen und Migration abschließen - -Der Romexis-Neustart nach dem Restore wird über folgende Datei koordiniert: - -```text -/data/romexis_images/.romexis_restart_state -``` - -Der Migration Service schreibt die Neustartanforderung, der Romexis-Entrypoint führt den Neustart aus und schreibt den finalen Status zurück. - - -## Persistente Datenverzeichnisse - -### sconfig - -Gemountet nach: - -```text -/opt/romexis/sconfig -``` - -Enthält persistente Romexis-Serverkonfiguration. - -### programdata - -Gemountet nach: - -```text -/programdata/Planmeca/Romexis -``` - -Entspricht dem Windows-Pfad `%ProgramData%\Planmeca\Romexis` und enthält KeyVault sowie sicherheitsrelevante Dateien. - -### romexis_images - -Gemountet nach: - -```text -/data/romexis_images -``` - -Speichert Patientenbilder. - -### romexis_cache - -Gemountet nach: - -```text -/data/romexis_cache -``` - -Speichert Cache-Daten. - -### romexis_ergodata - -Gemountet nach: - -```text -/data/romexis_ergodata -``` - -Speichert Ergo- und Zusatzdaten. - ---- - -## Datenbankinitialisierung - -Beim ersten Start: - -1. SQL Server startet. -2. Romexis wartet, bis SQL Server als erreichbar gilt. -3. Die Datenbank `Romexis_db` wird erstellt, falls sie fehlt. -4. Der Datenbankbenutzer `romexis` wird erstellt, falls er fehlt. -5. Romexis-Schema- und Update-Skripte werden importiert. -6. Linux-Datenpfade werden in die Datenbank geschrieben. - -Die Initialisierung wird übersprungen, wenn Datenbank und Romexis-Benutzer bereits existieren. - -Deaktivieren: - -```yaml -ROMEXIS_INIT_DB: "0" -``` - -Ausführliche SQL-Ausgabe: - -```yaml -DB_CREATE_VERBOSE: "true" -``` - ---- - -## KeyVault und ProgramData - -Romexis erwartet einen Windows-ähnlichen `ProgramData`-Pfad. Der Entrypoint setzt: - -```bash -ProgramData=/programdata -``` - -Der KeyVault-Pfad wird in `romexis_server.properties` geschrieben: - -```properties -SERVER_KEYVAULT_PATH=/programdata/Planmeca/Romexis/sconfig -``` - -Der Entrypoint initialisiert fehlende Schlüsseldateien aus den im Image enthaltenen Defaults: - -- `static_keys_default.p12` -> `static_keys.p12` -- `initial_keyvault.p12` -> `keyvault.p12` - ---- - -## RomexisConfig - -`RomexisConfig` wird absichtlich nicht ausgeführt. - -In einem Linux-Container kann RomexisConfig versuchen, über Advapi32/JNA auf Windows-Registry-Funktionen zuzugreifen. Die notwendigen Aufgaben übernimmt stattdessen der Docker-Entrypoint. - -Ersetzte Aufgaben: - -- KeyVault-Vorbereitung -- ProgramData-Handling -- Datenbankkonfiguration -- Linux-Pfadkonfiguration -- Runtime-Property-Injection - ---- - -## Erweiterte Konfiguration - -### Datenbank-URL - -Standardmäßig erzeugt der Entrypoint: - -```text -jdbc:sqlserver://:;databaseName=;encrypt=true;trustServerCertificate=true; -``` - -Eine vollständige JDBC-URL kann explizit gesetzt werden: - -```yaml -ROMEXIS_DB_URL: "jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;" -``` - -### Datenbank-Backend - -```yaml -SERVER_DB: "5" -``` - -Wert `5` steht für Microsoft SQL Server. - -### RMI Host und Ports - -```yaml -SERVER_RMI_HOSTNAME: "192.168.65.177" -SERVER_RMI_LOW_PORT: "1100" -SERVER_RMI_HIGH_PORT: "1120" -``` - -`SERVER_RMI_HOSTNAME` muss für Romexis-Clients erreichbar sein. - -### Property Agent - -Der Java Property Agent kann Romexis `RxProperties` über Umgebungsvariablen setzen. - -Syntax: - -```yaml -PROPERTY_AGENT_SET_: "" -``` - -Standardverhalten: - -```yaml -PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES: "true" -``` - -Diese Einstellung ist für zuverlässiges KeyVault-Handling unter Docker/Linux erforderlich. - ---- - -## Troubleshooting - -### SQL Server prüfen - -```bash -docker compose logs mssql -``` - -### Romexis prüfen - -```bash -docker compose logs romexis -``` - -### SQL-Server-Verbindung testen - -```bash -docker exec -it romexis-mssql \ - /opt/mssql-tools18/bin/sqlcmd \ - -C \ - -S localhost \ - -U sa \ - -P 'Pwr0mex!s!!!' \ - -Q "SELECT 1" -``` - -### Aufgelöste Romexis-Version prüfen - -```bash -docker exec -it romexis-server cat /opt/romexis/version -``` - -### Keystore-Alias-Probleme - -Falls Romexis meldet: - -```text -Failed to get keystore entry by alias: -server_certificate_... -``` - -ausführen: - -```bash -docker exec -it romexis-server /opt/fix-keystore-alias.sh -``` - ---- - -## Bekannte Einschränkungen - -- Nur Serverbetrieb wurde getestet. -- `RomexisConfig` wird im Container nicht unterstützt. -- Microsoft SQL Server ist das primär unterstützte Datenbank-Backend. -- Firebird-Clientbibliotheken sind im Base Image enthalten, die aktuelle Compose-Laufzeitumgebung fokussiert SQL Server. -- Multiarch-Images werden vom Build-Prozess unterstützt; die funktionale Validierung hängt von Plattform und verfügbaren Romexis-Komponenten ab. - ---- - -## Lizenz - -### Romexis - -Planmeca Romexis ist proprietäre Software. - -Dieses Repository enthält keine Romexis-Programmdateien. Der offizielle Installer wird während des Builds anhand von `romexis-versions.env` heruntergeladen. - -### Chilkat - -Dieses Projekt nutzt die von Romexis benötigte Chilkat-Bibliothek. Sie wird während des Builds passend zur Zielarchitektur heruntergeladen. - ---- - -## Haftungsausschluss - -Dieses Projekt steht in keiner Verbindung zu Planmeca Oy. - -Die Nutzung erfolgt auf eigene Verantwortung. - -Vor dem produktiven Einsatz werden vollständige Backups und Tests dringend empfohlen. +# Romexis Docker + +[English](README.md) | [Build-Prozess](BUILD.de.md) | [Entwicklerdokumentation](DEVELOPERS.md) + +> Containerisierte Bereitstellung von Planmeca Romexis Server unter Linux mit Docker, Datenbank-Backend-Auswahl über Docker Compose, optionalem Migration Service, browserbasiertem Romexis Admin und separatem mRomexis WebApp Container. + +--- + +## Überblick + +Dieses Projekt baut und betreibt Planmeca Romexis Dienste in Docker. + +Die benötigten Romexis-Programmdateien werden während des Builds aus dem offiziellen Romexis-Windows-Installer extrahiert. Im Repository werden keine Romexis-Binaries gespeichert. + +Der Runtime-Stack ist in klar getrennte Dienste aufgeteilt: + +- **Romexis Server** + Hauptdienst mit RMI-Ports, Datenbankzugriff, KeyVault-Vorbereitung und Laufzeitkonfiguration. + +- **Datenbank-Backend** + Auswahl über `DATABASE_BACKEND` und `COMPOSE_FILE` in der `.env`. Unterstützte Compose-Backends sind aktuell `mssql` und `firebird`. + +- **Romexis Migration Service** + Optionaler Web/API-Dienst für Restore- und Migrationsabläufe. + +- **Romexis Admin** + Browserbasierter Admin-/RomexisConfig-Container über Xvfb, Openbox, xcompmgr, x11vnc und noVNC. + +- **mRomexis WebApp** + Separater Tomcat-Container für die mRomexis-Weboberfläche ab Romexis 6.5.3. + +--- + +## Hauptfunktionen + +- Romexis Server in Docker +- Microsoft SQL Server und Firebird als Compose-Backends +- Backend-Auswahl über `.env` +- Lokale Build-Skripte für reproduzierbare Entwickler-Builds +- Multiarch-Images für `amd64` und `arm64` +- Payload-Image für Installer-Extraktion +- Wiederverwendbares Base-Runtime-Image +- Server-Image aus Payload- und Base-Image +- Migration-Service-Image +- Romexis-Admin-Image mit Browser/noVNC-Zugriff +- mRomexis-WebApp-Image +- Branch-spezifische Image-Suffixe über `IMAGE_SUFFIX` +- Java PropertyAgent für serverseitige Runtime-Properties +- Drone CI/CD mit Multiarch-Manifesten + +--- + +## Runtime-Compose-Struktur + +Die Laufzeitumgebung ist in eine Basis-Compose-Datei und backend-spezifische Override-Dateien aufgeteilt: + +```text +.env.sample +docker-compose.yml +docker-compose.mssql.yml +docker-compose.firebird.yml +scripts/build-local.sh +scripts/build-local.ps1 +``` + +Die Basisdatei enthält datenbankunabhängige Dienste wie: + +```text +romexis +romexis-admin +romexis-app +proxy +``` + +Die Backend-Override-Dateien ergänzen oder überschreiben datenbankspezifische Dienste und Umgebungsvariablen: + +```text +docker-compose.mssql.yml +docker-compose.firebird.yml +``` + +`docker-compose.build.yml` wird nicht mehr benötigt. Lokale Image-Builds laufen über `scripts/build-local.*`. + +--- + +## Backend-Auswahl über `.env` + +Der Stack kann mit einem einheitlichen Befehl gestartet werden, wenn das gewünschte Backend in `.env` gesetzt ist. + +### MSSQL + +```env +DATABASE_BACKEND=mssql +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Start: + +```bash +docker compose up -d +``` + +### Firebird + +```env +DATABASE_BACKEND=firebird +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Start: + +```bash +docker compose up -d +``` + +In nativen Windows-Shells kann als Compose-Dateitrenner `;` statt `:` erforderlich sein: + +```env +COMPOSE_PATH_SEPARATOR=; +COMPOSE_FILE=docker-compose.yml;docker-compose.${DATABASE_BACKEND}.yml +``` + +Die effektive Konfiguration prüfen: + +```bash +docker compose config +``` + +--- + +## Schnellstart + +Runtime-Konfiguration erstellen: + +```bash +cp .env.sample .env +``` + +Mindestens anpassen: + +```env +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= +``` + +Stack starten: + +```bash +docker compose up -d +``` + +Logs anzeigen: + +```bash +docker compose logs -f +``` + +Stack stoppen: + +```bash +docker compose down +``` + +--- + +## Runtime-Dienste + +### Romexis Server + +Der Dienst `romexis` startet den eigentlichen Romexis-Backend-Prozess. + +Er bereitet vor: + +- Romexis-Server-Properties +- KeyVault- und ProgramData-Pfade +- Datenbankverbindung +- Linux-Datenpfade +- RMI-Host und RMI-Ports +- optionale Datenbankinitialisierung + +Logs: + +```bash +docker compose logs -f romexis +``` + +Installierte Romexis-Version prüfen: + +```bash +docker exec -it romexis-server cat /opt/romexis/version +``` + +### Datenbank-Backend + +Das aktive Backend wird über `COMPOSE_FILE` geladen. + +Für MSSQL ergänzt die Override-Datei den SQL-Server-Dienst und konfiguriert Romexis für Microsoft SQL Server. + +Für Firebird ergänzt die Override-Datei den Firebird-Dienst und konfiguriert Romexis für Firebird. + +Prüfen: + +```bash +docker compose ps +docker compose logs -f +docker compose config +``` + +### Migration Service + +Der Migration Service unterstützt Romexis-Migrationen und Restore-Workflows. + +Er stellt bereit: + +- Web UI und REST API für Migrationsjobs +- Datenbankbackup-Upload +- temporären SFTP-Zugang pro Migrationsjob +- serverseitige `manifest.json`-Erzeugung +- Datenbank-Restore +- Datei-Restore +- Validierung und Bereinigung +- koordinierten Romexis-Neustart über eine gemeinsame State-Datei + +Die Neustartkoordination erfolgt über: + +```text +/data/romexis_images/.romexis_restart_state +``` + +### Romexis Admin + +Der Dienst `romexis-admin` stellt Romexis Admin / RomexisConfig über noVNC bereit. + +Beim Containerstart werden die grafischen Runtime-Komponenten gestartet: + +```text +Xvfb -> Openbox -> xcompmgr -> x11vnc -> noVNC +``` + +RomexisConfig selbst kann erst beim Aufbau einer VNC/noVNC-Verbindung gestartet werden. Dadurch läuft das Admin-Tool nicht dauerhaft im Hintergrund. + +Admin UI öffnen: + +```text +http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true +``` + +Typische Admin-Variablen: + +```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 +``` + +`ADMIN_LANGUAGE` unterstützt: + +```text +de +en +``` + +Der gleiche Sprachwert wird für den Splashscreen und den `language=` Parameter von RomexisConfig verwendet. + +`DEBUG_XTERM=true` öffnet zusätzlich ein Debug-Terminal in der VNC-Sitzung. + +`ADMIN_VNC_LIFECYCLE=true` bedeutet: + +- erster VNC/noVNC-Client verbindet sich -> RomexisConfig startet +- letzter VNC/noVNC-Client trennt sich -> RomexisConfig wird beendet +- während des Starts wird ein lokalisierter Splashscreen angezeigt + +### mRomexis WebApp + +Der Dienst `romexis-app` stellt die mRomexis Weboberfläche als eigenständige Tomcat-Anwendung bereit. + +Wichtig: + +```text +mromexis-html.war existiert erst ab Romexis 6.5.3. +``` + +Ältere Payload-Versionen enthalten diese WAR-Datei nicht und können daher kein gültiges mRomexis-WebApp-Image bauen. + +Die WebApp wird normalerweise über den Proxy-Dienst veröffentlicht. Der Proxy behandelt auch den `/proxy?url=...` Endpunkt der Anwendung. + +Der Proxy schreibt mRomexis-Proxy-Anfragen auf den internen Romexis-Backend-Dienst um, anstatt dem vom Browser gelieferten Host zu vertrauen. Dadurch müssen keine internen IP-Adressen gepflegt werden und der Endpunkt wird nicht zu einem offenen HTTP-Proxy. + +Typische Variable: + +```env +MROMEXIS_WEB_PORT=8081 +``` + +mRomexis WebApp öffnen: + +```text +http://localhost:8081/ +``` + +--- + +## Container Images + +Das Projekt verwendet folgende Image-Familien: + +```text +gitea.buchhorster.de/planmeca/romexis-payload: + +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:-amd64 +gitea.buchhorster.de/planmeca/romexis-server:-arm64 +gitea.buchhorster.de/planmeca/romexis-server: + +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:-amd64 +gitea.buchhorster.de/planmeca/romexis-admin:-arm64 +gitea.buchhorster.de/planmeca/romexis-admin: +gitea.buchhorster.de/planmeca/romexis-admin:latest + +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-amd64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-arm64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app: +gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest +``` + +Für Feature-Branches wird `IMAGE_SUFFIX` an den Tag angehängt: + +```env +IMAGE_SUFFIX=-feature-romexis-admin +``` + +Beispiel: + +```text +gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203-feature-romexis-admin +``` + +--- + +## Lokale Image-Builds + +Lokale Builds laufen über Skripte. + +Linux/macOS: + +```bash +chmod +x scripts/build-local.sh +./scripts/build-local.sh all +``` + +Windows PowerShell: + +```powershell +.\scripts\build-local.ps1 -Targets all +``` + +Nur ausgewählte Image-Familien bauen: + +```bash +./scripts/build-local.sh base server +./scripts/build-local.sh admin mromexis +./scripts/build-local.sh migration +``` + +Typische lokale `.env` Werte: + +```env +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 +``` + +Weitere Build-Details stehen in [BUILD.de.md](BUILD.de.md). + +--- + +## Persistente Datenverzeichnisse + +### sconfig + +Gemountet nach: + +```text +/opt/romexis/sconfig +``` + +Enthält persistente Romexis-Serverkonfiguration. + +### programdata + +Gemountet nach: + +```text +/programdata/planmeca/romexis +``` + +Entspricht dem Windows-Pfad `%ProgramData%\Planmeca\Romexis` und enthält KeyVault sowie sicherheitsrelevante Dateien. + +### romexis_images + +Gemountet nach: + +```text +/data/romexis_images +``` + +Speichert Patientenbilder. + +### romexis_cache + +Gemountet nach: + +```text +/data/romexis_cache +``` + +Speichert Cache-Daten. + +### romexis_ergodata + +Gemountet nach: + +```text +/data/romexis_ergodata +``` + +Speichert Ergo- und Zusatzdaten. + +--- + +## Datenbankinitialisierung + +Beim ersten Start kann der Server-Entrypoint das konfigurierte Datenbank-Backend initialisieren. + +Typische Aufgaben beim ersten Start: + +1. Auf das gewählte Datenbank-Backend warten. +2. Romexis-Datenbank erstellen, falls sie fehlt. +3. Romexis-Datenbankbenutzer erstellen, falls er fehlt. +4. Schema- und Update-Skripte importieren, sofern zutreffend. +5. Linux-Datenpfade in die Datenbank schreiben. +6. Romexis Server starten. + +Initialisierung deaktivieren: + +```env +ROMEXIS_INIT_DB=0 +``` + +Ausführliche SQL-Ausgabe aktivieren: + +```env +DB_CREATE_VERBOSE=true +``` + +--- + +## KeyVault und ProgramData + +Romexis erwartet einen Windows-ähnlichen `ProgramData`-Pfad. Der Entrypoint setzt: + +```bash +ProgramData=/programdata +``` + +Der KeyVault-Pfad wird in `romexis_server.properties` geschrieben. + +Fehlende Schlüsseldateien werden bei Bedarf aus den im Image enthaltenen Defaults initialisiert. + +--- + +## RomexisConfig und Admin-Konfiguration + +Der Server-Container führt RomexisConfig beim Start nicht aus. + +Administrative Konfiguration erfolgt über den separaten `romexis-admin` Container. Dadurch bleibt der Server-Container auf den Backend-Prozess fokussiert und wird nicht mit einem grafischen Konfigurationstool vermischt. + +--- + +## Erweiterte Konfiguration + +### Datenbank-Backend + +Die Backend-Auswahl erfolgt auf Compose-Ebene: + +```env +DATABASE_BACKEND=mssql +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Die backend-spezifische Compose-Override-Datei setzt anschließend die passenden Romexis-Datenbankvariablen. + +### RMI Host und Ports + +```env +SERVER_RMI_HOSTNAME=192.168.65.177 +SERVER_RMI_LOW_PORT=1100 +SERVER_RMI_HIGH_PORT=1120 +``` + +`SERVER_RMI_HOSTNAME` muss für Romexis-Clients erreichbar sein. + +### PropertyAgent + +Der Java PropertyAgent kann Romexis `RxProperties` über Umgebungsvariablen setzen. + +Syntax: + +```env +PROPERTY_AGENT_SET_= +``` + +Beispiel: + +```env +PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true +``` + +Dies ist hauptsächlich für die Romexis-Server-Laufzeit relevant. Im Admin-Container ist der PropertyAgent standardmäßig deaktiviert. + +--- + +## Troubleshooting + +### Effektive Compose-Konfiguration prüfen + +```bash +docker compose config +``` + +### Alle Dienste prüfen + +```bash +docker compose ps +docker compose logs -f +``` + +### Romexis Server prüfen + +```bash +docker compose logs -f romexis +``` + +### Admin Container prüfen + +```bash +docker compose logs -f romexis-admin +``` + +### Shell im Admin-Service öffnen + +```bash +docker compose run --rm --entrypoint /bin/bash romexis-admin +``` + +### Aufgelöste Romexis-Version prüfen + +```bash +docker exec -it romexis-server cat /opt/romexis/version +``` + +### Keystore-Alias-Probleme + +Falls Romexis einen fehlenden Server-Zertifikat-Alias meldet: + +```bash +docker exec -it romexis-server /opt/fix-keystore-alias.sh +``` + +--- + +## Bekannte Einschränkungen + +- Romexis-Binaries sind nicht Bestandteil dieses Repositorys. +- Das mRomexis-WebApp-Image erfordert Romexis 6.5.3 oder neuer. +- Romexis Admin wird über eine browserbasierte VNC-Sitzung bereitgestellt, nicht als native Desktop-Anwendung. +- Multiarch-Images werden gebaut und veröffentlicht; die funktionale Validierung hängt von Plattform und verfügbaren Romexis-Komponenten ab. +- Vor produktivem Einsatz sind Backups, Lizenzprüfung und umgebungsspezifische Tests erforderlich. + +--- + +## Lizenz + +### Romexis + +Planmeca Romexis ist proprietäre Software. + +Dieses Repository enthält keine Romexis-Programmdateien. Der offizielle Installer wird während des Builds anhand von `romexis-payload/romexis-versions.env` heruntergeladen. + +### Chilkat + +Dieses Projekt nutzt die von Romexis benötigte Chilkat-Bibliothek. Sie wird während des Builds passend zur Zielarchitektur heruntergeladen. + +--- + +## Haftungsausschluss + +Dieses Projekt steht in keiner Verbindung zu Planmeca Oy. + +Die Nutzung erfolgt auf eigene Verantwortung. + +Vor dem produktiven Einsatz werden vollständige Backups und Tests dringend empfohlen. diff --git a/Reference-README.md b/Reference-README.md index 5e5afc1..3929a78 100644 --- a/Reference-README.md +++ b/Reference-README.md @@ -1,595 +1,630 @@ -# 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/planmeca/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/planmeca/romexis-base-jre:11-amd64 -gitea.buchhorster.de/planmeca/romexis-base-jre:11-arm64 - -gitea.buchhorster.de/planmeca/romexis-server:-amd64 -gitea.buchhorster.de/planmeca/romexis-server:-arm64 -gitea.buchhorster.de/planmeca/romexis-server: -``` - -The architecture-specific tags are used internally by the multi-architecture manifest. - -### Example pull - -```bash -docker pull gitea.buchhorster.de/planmeca/romexis-server:6.5.3.444.203 -``` - -### Verify installed Romexis version - -```bash -docker run --rm \ - --entrypoint cat \ - gitea.buchhorster.de/planmeca/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:`. - -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://:;databaseName=;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_: "" -``` - -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. +# Romexis Docker + +[Deutsch](README.de.md) | [Build process](BUILD.md) | [Developer notes](DEVELOPERS.md) + +> 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: + +```text +.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: + +```text +romexis +romexis-admin +romexis-app +proxy +``` + +The backend override files add or override database-specific services and environment values: + +```text +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 + +```env +DATABASE_BACKEND=mssql +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Start: + +```bash +docker compose up -d +``` + +### Firebird + +```env +DATABASE_BACKEND=firebird +COMPOSE_PATH_SEPARATOR=: +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Start: + +```bash +docker compose up -d +``` + +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 +``` + +To verify which files and values are active: + +```bash +docker compose config +``` + +--- + +## Quick Start + +Create your runtime configuration: + +```bash +cp .env.sample .env +``` + +Edit at least: + +```env +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: + +```bash +docker compose up -d +``` + +View logs: + +```bash +docker compose logs -f +``` + +Stop the stack: + +```bash +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: + +```bash +docker compose logs -f romexis +``` + +Check the installed Romexis version: + +```bash +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: + +```bash +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: + +```text +/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: + +```text +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: + +```text +http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true +``` + +Typical Admin environment values: + +```env +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=false +``` + +`ADMIN_LANGUAGE` supports: + +```text +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: + +```text +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: + +```env +MROMEXIS_WEB_PORT=8081 +``` + +Open the mRomexis Web App through the configured proxy port: + +```text +http://localhost:8081/ +``` + +--- + +## Container Images + +The project uses these image families: + +```text +gitea.buchhorster.de/planmeca/romexis-payload: + +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:-amd64 +gitea.buchhorster.de/planmeca/romexis-server:-arm64 +gitea.buchhorster.de/planmeca/romexis-server: + +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:-amd64 +gitea.buchhorster.de/planmeca/romexis-admin:-arm64 +gitea.buchhorster.de/planmeca/romexis-admin: +gitea.buchhorster.de/planmeca/romexis-admin:latest + +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-amd64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-arm64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app: +gitea.buchhorster.de/planmeca/romexis-mromexis-app:latest +``` + +For feature branches, `IMAGE_SUFFIX` is appended to the tag: + +```env +IMAGE_SUFFIX=-feature-romexis-admin +``` + +Example: + +```text +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: + +```bash +chmod +x scripts/build-local.sh +./scripts/build-local.sh all +``` + +Windows PowerShell: + +```powershell +.\scripts\build-local.ps1 -Targets all +``` + +Build only selected image families: + +```bash +./scripts/build-local.sh base server +./scripts/build-local.sh admin mromexis +./scripts/build-local.sh migration +``` + +Common local `.env` values: + +```env +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](BUILD.md). + +--- + +## Persistent Data Directories + +### sconfig + +Mounted to: + +```text +/opt/romexis/sconfig +``` + +Contains persistent Romexis server configuration files. + +### programdata + +Mounted to: + +```text +/programdata/planmeca/romexis +``` + +Mirrors the Windows `%ProgramData%\Planmeca\Romexis` location and contains KeyVault and security related 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, 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: + +```env +ROMEXIS_INIT_DB=0 +``` + +Enable verbose SQL output: + +```env +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`. + +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: + +```env +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 + +```env +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: + +```env +PROPERTY_AGENT_SET_= +``` + +Example: + +```env +PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true +``` + +This is primarily relevant for the Romexis server runtime. In the Admin container the PropertyAgent is disabled by default. + +--- + +## Troubleshooting + +### Inspect effective Compose configuration + +```bash +docker compose config +``` + +### Check all services + +```bash +docker compose ps +docker compose logs -f +``` + +### Check Romexis server + +```bash +docker compose logs -f romexis +``` + +### Check Admin container + +```bash +docker compose logs -f romexis-admin +``` + +### Open a shell in the Admin service + +```bash +docker compose run --rm --entrypoint /bin/bash romexis-admin +``` + +### Check resolved Romexis version + +```bash +docker exec -it romexis-server cat /opt/romexis/version +``` + +### Keystore alias issues + +If Romexis reports a missing server certificate alias, run: + +```bash +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. diff --git a/Release-Process.md b/Release-Process.md index 3818ae3..43e573f 100644 --- a/Release-Process.md +++ b/Release-Process.md @@ -1,67 +1,67 @@ -# Release Process - -## Release Inputs - -A release usually includes: - -- built and pushed container images -- updated documentation -- release notes -- optional migration service changes -- optional client changes - ---- - -## Suggested Release Steps - -1. Ensure the repository builds cleanly. -2. Verify payload image availability. -3. Verify base images for target architectures. -4. Verify server images for target architectures. -5. Verify multiarch manifests. -6. Test Docker Compose startup. -7. Test database initialization. -8. Test migration service startup. -9. Create release notes. -10. Publish Gitea release. -11. Verify Gitea packages. - ---- - -## Image Verification - -```bash -docker pull gitea.buchhorster.de/planmeca/romexis-server:-amd64 -docker pull gitea.buchhorster.de/planmeca/romexis-server: -``` - -Inspect: - -```bash -docker manifest inspect gitea.buchhorster.de/planmeca/romexis-server: -``` - ---- - -## Release Notes Should Mention - -- new features -- migration service changes -- database backend changes -- breaking changes -- required environment variable changes -- known limitations - ---- - -## Gitea Areas - -Use Gitea as follows: - -| Area | Purpose | -|---|---| -| Code | Source code and Dockerfiles | -| Releases | Human-readable versioned release notes | -| Packages | Published container images | -| Wiki | Operational and developer documentation | -| Issues | Bugs, feature requests and planning | +# Release Process + +## Release Inputs + +A release usually includes: + +- built and pushed container images +- updated documentation +- release notes +- optional migration service changes +- optional client changes + +--- + +## Suggested Release Steps + +1. Ensure the repository builds cleanly. +2. Verify payload image availability. +3. Verify base images for target architectures. +4. Verify server images for target architectures. +5. Verify multiarch manifests. +6. Test Docker Compose startup. +7. Test database initialization. +8. Test migration service startup. +9. Create release notes. +10. Publish Gitea release. +11. Verify Gitea packages. + +--- + +## Image Verification + +```bash +docker pull gitea.buchhorster.de/planmeca/romexis-server:-amd64 +docker pull gitea.buchhorster.de/planmeca/romexis-server: +``` + +Inspect: + +```bash +docker manifest inspect gitea.buchhorster.de/planmeca/romexis-server: +``` + +--- + +## Release Notes Should Mention + +- new features +- migration service changes +- database backend changes +- breaking changes +- required environment variable changes +- known limitations + +--- + +## Gitea Areas + +Use Gitea as follows: + +| Area | Purpose | +|---|---| +| Code | Source code and Dockerfiles | +| Releases | Human-readable versioned release notes | +| Packages | Published container images | +| Wiki | Operational and developer documentation | +| Issues | Bugs, feature requests and planning | diff --git a/Romexis-Admin.md b/Romexis-Admin.md new file mode 100644 index 0000000..fefb10a --- /dev/null +++ b/Romexis-Admin.md @@ -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. diff --git a/Runtime-Layout.md b/Runtime-Layout.md index eea409d..d55cb10 100644 --- a/Runtime-Layout.md +++ b/Runtime-Layout.md @@ -1,72 +1,136 @@ -# Runtime Layout - -## Persistent Data - -Recommended persistent root: - -```text -/srv/romexis-data -``` - -Typical directories: - -```text -/srv/romexis-data/romexis_images -/srv/romexis-data/romexis_ergodata -/srv/romexis-data/romexis_cache -/srv/romexis-data/firebird -``` - ---- - -## Romexis Container Paths - -```text -/opt/romexis -/opt/romexis/server -/opt/romexis/sconfig -/opt/romexis/programdata - -/data/romexis_images -/data/romexis_ergodata -/data/romexis_cache -``` - ---- - -## 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 -``` +# Runtime Layout + +## Persistent Data + +Recommended persistent root: + +```text +/srv/romexis-data +``` + +Typical directories: + +```text +/srv/romexis-data/sconfig +/srv/romexis-data/programdata +/srv/romexis-data/romexis_images +/srv/romexis-data/romexis_ergodata +/srv/romexis-data/romexis_cache +/srv/romexis-data/sql-backup +/srv/romexis-data/firebird +``` + +--- + +## Runtime Services + +```text +romexis + Main Romexis Server process. + +mssql + Microsoft SQL Server backend when DATABASE_BACKEND=mssql. + +firebird + Firebird backend when DATABASE_BACKEND=firebird. + +romexis-admin + Browser-accessible Romexis Admin / RomexisConfig runtime. + +romexis-app + Tomcat-based mRomexis Web App. + +proxy + OpenResty/Nginx proxy for mRomexis Web App. + +romexis-migration + Optional migration service for MSSQL workflows. +``` + +--- + +## Romexis Container Paths + +```text +/opt/romexis +/opt/romexis/server +/opt/romexis/sconfig +/programdata/planmeca/romexis + +/data/romexis_images +/data/romexis_ergodata +/data/romexis_cache +``` + +--- + +## Admin Container Paths + +```text +/opt/romexis/admin +/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 +``` diff --git a/Server-Image.md b/Server-Image.md index c2c13c9..af1d056 100644 --- a/Server-Image.md +++ b/Server-Image.md @@ -1,99 +1,100 @@ -# Server Image - -Directory: - -```text -romexis/ -``` - -The final Romexis Server image combines the prepared payload, runtime base image and runtime scripts. - ---- - -## Build Inputs - -```text -ROMEXIS_BASE_IMAGE -ROMEXIS_PAYLOAD_IMAGE -ROMEXIS_FIREBIRD_PAYLOAD_IMAGE -ROMEXIS_VERSION -TARGETARCH -CHILKAT_VERSION -``` - -Example defaults: - -```dockerfile -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 ROMEXIS_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-payload:${ROMEXIS_VERSION} -ARG ROMEXIS_FIREBIRD_PAYLOAD_IMAGE=gitea.buchhorster.de/planmeca/romexis-firebird-payload:latest -``` - ---- - -## Build Stages - -```text -Stage 1: romexis-payload - Imports /opt/romexis and /opt/romexis-mssql-db. - -Stage 2: romexis-firebird-payload - Imports /opt/romexis-firebird-db. - -Stage 3: agent-build - Compiles RomexisPropertyAgent.java. - -Stage 4: final image - Assembles runtime image. -``` - ---- - -## Runtime Scripts - -The final image includes: - -```text -/entrypoint.sh -/opt/init-romexis-db.sh -/opt/init-romexis-mssql-db.sh -/opt/init-romexis-firebird-db.sh -/opt/init-romexis-db.sh -/opt/fix-keystore-alias.sh -``` - ---- - -## Java Property Agent - -The image includes: - -```text -/opt/romexis/server/RomexisPropertyAgent.jar -``` - -This allows runtime property injection before Romexis starts. - -Example environment variable pattern: - -```text -PROPERTY_AGENT_SET_KEY_= -``` - ---- - -## Runtime Validation - -The Dockerfile should validate important payload outputs during build, especially: - -```text -/opt/romexis/server/RomexisServer.jar -/opt/romexis/version -/opt/romexis-mssql-db -/opt/romexis-firebird-db -``` - -Failing early is preferred over producing an incomplete runtime image. +# Server Image + +Directory: + +```text +romexis/ +``` + +The final Romexis Server image combines the prepared payload, runtime base image, Firebird payload and runtime scripts. + +--- + +## Build Inputs + +```text +ROMEXIS_BASE_IMAGE +ROMEXIS_PAYLOAD_IMAGE +ROMEXIS_FIREBIRD_PAYLOAD_IMAGE +ROMEXIS_VERSION +TARGETARCH +IMAGE_SUFFIX +CHILKAT_VERSION +``` + +Example defaults: + +```dockerfile +ARG TARGETARCH=amd64 +ARG ROMEXIS_VERSION=6.5.3.444.203 +ARG IMAGE_SUFFIX= + +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 +Stage 1: romexis-payload + Imports /opt/romexis and /opt/romexis-mssql-db. + +Stage 2: romexis-firebird-payload + Imports /opt/romexis-firebird-db. + +Stage 3: agent-build + Compiles RomexisPropertyAgent.java. + +Stage 4: final image + Assembles runtime image. +``` + +--- + +## Runtime Scripts + +The final image includes: + +```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 +``` + +--- + +## Java Property Agent + +The image includes: + +```text +/opt/romexis/server/RomexisPropertyAgent.jar +``` + +This allows runtime property injection before Romexis starts. + +Example environment variable pattern: + +```text +PROPERTY_AGENT_SET_KEY_= +``` + +--- + +## Runtime Validation + +The Dockerfile should validate important payload outputs during build, especially: + +```text +/opt/romexis/server/RomexisServer.jar +/opt/romexis/version +/opt/romexis-mssql-db +/opt/romexis-firebird-db +``` + +Failing early is preferred over producing an incomplete runtime image. diff --git a/Source-README-References.md b/Source-README-References.md index 9ff6b16..1b9d05f 100644 --- a/Source-README-References.md +++ b/Source-README-References.md @@ -1,12 +1,13 @@ -# Source README References - -These source documents were used as the basis for the wiki package. - -- [BUILD.de](Reference-BUILD.de) -- [BUILD](Reference-BUILD) -- [DEVELOPERS.de](Reference-DEVELOPERS.de) -- [DEVELOPERS](Reference-DEVELOPERS) -- [MIGRATION_README](Reference-MIGRATION_README) -- [MIGRATION_WORKFLOW](Reference-MIGRATION_WORKFLOW) -- [README.de](Reference-README.de) -- [README](Reference-README) +# Source README References + +These source documents were used as the basis for the wiki package. + +- [BUILD.de](Reference-BUILD.de) +- [BUILD](Reference-BUILD) +- [README.de](Reference-README.de) +- [README](Reference-README) +- [README Compose Refactor](Reference-README-compose) +- [DEVELOPERS.de](Reference-DEVELOPERS.de) +- [DEVELOPERS](Reference-DEVELOPERS) +- [MIGRATION_README](Reference-MIGRATION_README) +- [MIGRATION_WORKFLOW](Reference-MIGRATION_WORKFLOW) diff --git a/Troubleshooting.md b/Troubleshooting.md index bc3dc57..4d29137 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -1,186 +1,226 @@ -# Troubleshooting - -## Firebird mode still starts MSSQL initialization - -Check: - -```bash -docker exec -it romexis-server env | grep -E 'SERVER_DB|ROMEXIS_DB|FIREBIRD' -``` - -Expected Firebird values: - -```text -SERVER_DB=4 -ROMEXIS_DB_URL=jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb -ROMEXIS_DB_USER=sysdba -ROMEXIS_DB_PASSWORD=pwr0mex! -``` - -If `SERVER_DB` is missing, the entrypoint may default to MSSQL: - -```bash -SERVER_DB="${SERVER_DB:-5}" -``` - -Set: - -```env -SERVER_DB=4 -``` - ---- - -## 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. - -Check inside the Romexis container: - -```bash -cat /opt/init-romexis-db.sh -ls -lah /opt/init-romexis-* -``` - -The wrapper must not contain: - -```bash -MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:?MSSQL_SA_PASSWORD is required}" -``` - -That belongs only in: - -```text -/opt/init-romexis-mssql-db.sh -``` - -Rebuild without cache: - -```bash -docker buildx prune -a -f -docker compose build --no-cache --pull -docker compose up --force-recreate -``` - ---- - -## Firebird shows unixODBC isql help - -If you see: - -```text -unixODBC - isql and iusql -``` - -then the wrong `isql` tool is used. - -Use: - -```bash -isql-fb -``` - -Set: - -```bash -export ISQL=isql-fb -``` - -Or change the init script default: - -```bash -ISQL="${ISQL:-isql-fb}" -``` - ---- - -## Firebird database file already exists - -If the Firebird container creates the database using: - -```yaml -FIREBIRD_DATABASE: "romexis.fdb" -``` - -then the Romexis init script should not run `CREATE DATABASE` again. - -It should connect to the existing empty database and import the SQL scripts. - ---- - -## Firebird SYSDBA duplicate key error - -Error: - -```text -violation of PRIMARY or UNIQUE KEY constraint -PLG$USER_NAME = 'SYSDBA' -``` - -Cause: - -The Firebird container was instructed to create `SYSDBA` again. - -Remove user creation variables from the Firebird service and keep only: - -```yaml -environment: - ISC_PASSWORD: "${FIREBIRD_PASSWORD}" - FIREBIRD_DATABASE: "romexis.fdb" -``` - ---- - -## Payload latest tag not found - -Error: - -```text -romexis-firebird-payload:latest: not found -``` - -Fix the Firebird payload CI build to push: - -```bash --t "$FIREBIRD_PAYLOAD_IMAGE:latest" -``` - ---- - -## Build still uses old files - -Clean local build cache: - -```bash -docker buildx prune -a -f -``` - -Then rebuild with: - -```bash -docker compose build --no-cache --pull -``` - -In CI, also check whether the build is skipped because the image already exists in the registry. - ---- - -## Start container with bash for debugging - -In Compose: - -```yaml -entrypoint: - - /bin/bash - - -c - - sleep infinity - -stdin_open: true -tty: true -``` - -Then: - -```bash -docker compose exec romexis bash -``` +# Troubleshooting + +## Inspect effective Compose configuration + +Because the active backend is selected through `.env`, start with: + +```bash +docker compose config +``` + +Check that the expected backend override was loaded. + +--- + +## Wrong database backend starts + +Check `.env`: + +```env +DATABASE_BACKEND=mssql +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +or: + +```env +DATABASE_BACKEND=firebird +COMPOSE_FILE=docker-compose.yml:docker-compose.${DATABASE_BACKEND}.yml +``` + +Then inspect the running container environment: + +```bash +docker compose exec romexis env | grep -E 'SERVER_DB|ROMEXIS_DB|MSSQL|FIREBIRD' +``` + +Expected backend identifiers: + +```text +SERVER_DB=5 # MSSQL +SERVER_DB=4 # Firebird +``` + +--- + +## Firebird mode still starts MSSQL initialization + +If `SERVER_DB` is missing, the entrypoint may default to MSSQL. + +Check: + +```bash +docker compose exec romexis env | grep SERVER_DB +``` + +The Firebird Compose override must set: + +```env +SERVER_DB=4 +``` + +--- + +## 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. + +Check inside the Romexis container: + +```bash +docker compose exec romexis cat /opt/init-romexis-db.sh +docker compose exec romexis ls -lah /opt/init-romexis-* +``` + +Rebuild and recreate: + +```bash +docker buildx prune -a -f +./scripts/build-local.sh server +docker compose up -d --force-recreate +``` + +--- + +## Firebird shows unixODBC isql help + +If you see: + +```text +unixODBC - isql and iusql +``` + +then the wrong `isql` tool is used. + +Use: + +```bash +isql-fb +``` + +or set: + +```bash +export ISQL=isql-fb +``` + +--- + +## Admin container does not start RomexisConfig + +Check logs: + +```bash +docker compose logs -f romexis-admin +``` + +If `ADMIN_VNC_LIFECYCLE=true`, RomexisConfig starts only after a VNC/noVNC client connects. + +Open: + +```text +http://localhost:6080/vnc.html?host=localhost&port=6080&autoconnect=true +``` + +--- + +## Admin JavaFX or translucency errors + +Romexis Admin requires Openbox and xcompmgr. + +The Admin image should include: + +```text +openbox +xcompmgr +x11-utils +openjfx +libopenjfx-java +libopenjfx-jni +``` + +Errors such as `TRANSLUCENT translucency is not supported` usually mean the compositor is missing or not running. + +--- + +## Admin splash screen is not shown + +The splash screen uses `xmessage` from `x11-utils`. + +Check: + +```bash +docker compose run --rm --entrypoint which romexis-admin xmessage +``` + +--- + +## mRomexis Web App build fails because WAR is missing + +`mromexis-html.war` exists only in Romexis 6.5.3 and newer. + +Check the payload: + +```bash +docker run --rm --entrypoint find gitea.buchhorster.de/planmeca/romexis-payload:6.5.3.444.203 /opt/romexis -name 'mromexis-html.war' +``` + +--- + +## mRomexis Web App backend calls fail + +Check proxy logs: + +```bash +docker compose logs -f proxy +``` + +Check Romexis backend reachability from the proxy container: + +```bash +docker compose exec proxy wget -O- http://romexis:8093/ || true +``` + +--- + +## 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 +``` diff --git a/_Footer.md b/_Footer.md index 6e9a998..d9dffe8 100644 --- a/_Footer.md +++ b/_Footer.md @@ -1,11 +1,11 @@ ---- - -Romexis Docker Project Wiki - -Repository areas: - -- **Code**: source files, Dockerfiles and helper scripts -- **Releases**: published project releases and release notes -- **Packages**: container images in the Gitea package registry -- **Wiki**: operational and developer documentation - +--- + +Romexis Docker Project Wiki + +Repository areas: + +- **Code**: source files, Dockerfiles and helper scripts +- **Releases**: published project releases and release notes +- **Packages**: container images in the Gitea package registry +- **Wiki**: operational and developer documentation + diff --git a/_Sidebar.md b/_Sidebar.md index 7a554de..0841d3d 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -1,44 +1,48 @@ -# Romexis Docker Wiki - -- [Home](Home) - -## Getting Started -- [Project Overview](Project-Overview) -- [Architecture](Architecture) -- [Quick Start](Quick-Start) -- [Use with Docker + WSL in Windows](Docker-Desktop-WSL-Windows) -- [Configuration](Configuration) -- [Container Images](Container-Images) - -## Build System -- [Build System](Build-System) -- [Payload Images](Payload-Images) -- [Base Image](Base-Image) -- [Server Image](Server-Image) -- [CI/CD Pipeline](CI-CD-Pipeline) - -## Database -- [Database Backends](Database-Backends) -- [Microsoft SQL Server](Microsoft-SQL-Server) -- [Firebird](Firebird) - -## Migration -- [Migration Service](Migration-Service) -- [Migration Workflow](Migration-Workflow) -- [Migration Client](Migration-Client) - -## Operations -- [Runtime Layout](Runtime-Layout) -- [Backup and Restore](Backup-and-Restore) -- [Troubleshooting](Troubleshooting) -- [Security](Security) - -## Development -- [Developer Guide](Developer-Guide) -- [Java Property Agent](Java-Property-Agent) -- [Project Structure](Project-Structure) -- [Release Process](Release-Process) -- [FAQ](FAQ) - -## Source Documents -- [Source README References](Source-README-References) +# Romexis Docker Wiki + +- [Home](Home) + +## Getting Started +- [Project Overview](Project-Overview) +- [Architecture](Architecture) +- [Quick Start](Quick-Start) +- [Use with Docker + WSL in Windows](Docker-Desktop-WSL-Windows) +- [Compose Runtime](Compose-Runtime) +- [Configuration](Configuration) +- [Container Images](Container-Images) + +## Runtime Services +- [Romexis Admin](Romexis-Admin) +- [mRomexis Web App](mRomexis-WebApp) +- [Runtime Layout](Runtime-Layout) +- [Backup and Restore](Backup-and-Restore) +- [Troubleshooting](Troubleshooting) +- [Security](Security) + +## Build System +- [Build System](Build-System) +- [Local Build Scripts](Local-Build-Scripts) +- [Payload Images](Payload-Images) +- [Base Image](Base-Image) +- [Server Image](Server-Image) +- [CI/CD Pipeline](CI-CD-Pipeline) + +## Database +- [Database Backends](Database-Backends) +- [Microsoft SQL Server](Microsoft-SQL-Server) +- [Firebird](Firebird) + +## Migration +- [Migration Service](Migration-Service) +- [Migration Workflow](Migration-Workflow) +- [Migration Client](Migration-Client) + +## Development +- [Developer Guide](Developer-Guide) +- [Java Property Agent](Java-Property-Agent) +- [Project Structure](Project-Structure) +- [Release Process](Release-Process) +- [FAQ](FAQ) + +## Source Documents +- [Source README References](Source-README-References) diff --git a/mRomexis-WebApp.md b/mRomexis-WebApp.md new file mode 100644 index 0000000..cb40cde --- /dev/null +++ b/mRomexis-WebApp.md @@ -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:-amd64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app:-arm64 +gitea.buchhorster.de/planmeca/romexis-mromexis-app: +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 +```