Add Java Property Agent page

2026-06-29 18:55:55 +00:00
parent 8e3da2ee55
commit 4cbceb041c
2 changed files with 225 additions and 0 deletions
@@ -0,0 +1,224 @@
+# Java Property Agent
+
+## Purpose
+
+The `RomexisPropertyAgent` is a small Java Instrumentation Agent used by the Romexis Docker project to configure Romexis `RxProperties` during JVM startup.
+
+It allows selected Romexis runtime properties to be set through environment variables before the Romexis Server application fully starts.
+
+This is required because some Romexis behavior is decided very early during JVM startup and cannot reliably be changed later by editing files inside the container.
+
+---
+
+## Why the Agent Exists
+
+When starting `RomexisServer.jar` under Linux, Romexis internally selected behavior that matched the macOS runtime path.
+
+That macOS-specific behavior was not compatible with the Linux Docker environment.
+
+The critical property was:
+
+```text
+KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES
+```
+
+For the Romexis Server to start correctly inside the Linux container, this property had to be set to:
+
+```text
+true
+```
+
+This makes Romexis behave like the Windows server runtime in this area and use the expected server properties based key vault password location.
+
+Without this override, the Romexis Server startup under Linux could fail because the wrong platform-specific property handling was selected.
+
+---
+
+## Required Docker Setting
+
+The most important environment variable currently used by the Docker image is:
+
+```env
+PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true
+```
+
+This is translated by the Java agent into:
+
+```java
+RxProperties.setProperty(
+    RxProperties.KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES,
+    true
+);
+```
+
+This override is one of the reasons why Romexis Server can run reliably in the Linux-based container.
+
+---
+
+## Why a Java Agent Instead of Patching Files?
+
+The Java agent approach avoids:
+
+- patching Romexis application files
+- modifying proprietary Romexis JARs
+- editing configuration files after startup has already begun
+- maintaining custom binary patches
+- rebuilding Romexis itself
+
+Instead, the Docker runtime can control these settings using ordinary environment variables.
+
+This is safer, easier to maintain and better suited for automated deployments.
+
+---
+
+## How It Works
+
+The agent is loaded by the JVM before the Romexis application starts.
+
+It scans all environment variables with the prefix:
+
+```text
+PROPERTY_AGENT_SET_
+```
+
+The part after the prefix is interpreted as a field name from:
+
+```java
+romexis_lib_base.types.RxProperties
+```
+
+Example:
+
+```env
+PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true
+```
+
+The agent removes the prefix:
+
+```text
+KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES
+```
+
+Then it looks up the matching public field in `RxProperties`.
+
+If the field exists, the agent reads the actual Romexis property key and calls the matching `RxProperties.setProperty(...)` method.
+
+---
+
+## Supported Value Types
+
+The agent automatically converts values to one of the following types:
+
+| Environment value | Java type |
+|---|---|
+| `true` / `false` | `Boolean` |
+| integer values | `Integer` |
+| all other values | `String` |
+
+---
+
+## Unknown Properties
+
+If an environment variable references a field that does not exist in `RxProperties`, the agent does not fail the startup.
+
+Instead, it logs a warning:
+
+```text
+JavaAgent WARN: RxProperties field not found: <field>
+```
+
+This makes the mechanism safe for optional or version-dependent properties.
+
+---
+
+## Intended Use Cases
+
+The Java Property Agent is intended for:
+
+- Docker deployments
+- Kubernetes deployments
+- automated configuration management
+- runtime customization
+- platform compatibility fixes
+- controlled Romexis server behavior overrides
+
+---
+
+## Build Integration
+
+The agent source is compiled during the Romexis Server image build.
+
+The Dockerfile uses a dedicated build stage:
+
+```text
+agent-build
+```
+
+The result is copied into the final image as:
+
+```text
+/opt/romexis/server/RomexisPropertyAgent.jar
+```
+
+The JAR manifest contains:
+
+```text
+Premain-Class: RomexisPropertyAgent
+```
+
+This allows the JVM to load it through:
+
+```text
+-javaagent:/opt/romexis/server/RomexisPropertyAgent.jar
+```
+
+---
+
+## Runtime Integration
+
+The Romexis entrypoint adds the Java agent to the Romexis Server JVM startup command.
+
+The property override is then applied before `RomexisServer.jar` continues its normal startup sequence.
+
+Typical runtime configuration:
+
+```env
+PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true
+```
+
+---
+
+## Example Log Output
+
+Successful property application:
+
+```text
+JavaAgent: set KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES=true
+JavaAgent: 1 properties applied
+```
+
+Unknown property:
+
+```text
+JavaAgent WARN: RxProperties field not found: SOME_UNKNOWN_FIELD
+```
+
+---
+
+## Important Notes
+
+- The agent does not modify Romexis binaries.
+- The agent does not patch class files.
+- The agent only calls public `RxProperties` fields and setter methods.
+- Unknown fields are ignored with a warning.
+- This mechanism should only be used for properties that are understood and intentionally overridden.
+
+---
+
+## Current Critical Property
+
+| Property | Value | Reason |
+|---|---|---|
+| `KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES` | `true` | Forces Romexis Server to use the server-properties based behavior required for Linux Docker startup |
+
+
@@ -35,6 +35,7 @@

 ## Development
 - [Developer Guide](Developer-Guide)
+- [Java Property Agent]](Java-Property-Agent)
 - [Project Structure](Project-Structure)
 - [Release Process](Release-Process)
 - [FAQ](FAQ)