diff --git a/Java-Property-Agent.md b/Java-Property-Agent.md new file mode 100644 index 0000000..9cf6f66 --- /dev/null +++ b/Java-Property-Agent.md @@ -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: +``` + +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 | + + diff --git a/_Sidebar.md b/_Sidebar.md index a726055..06239ef 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -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)