Configure the Runtime
Overview
There are several ways to configure the Runtime:
-
Use environment variables to configure the startup parameters of the runtime process.
-
Use the Runtime configuration file to configure scheduling, services, security, repositories, logging and other advanced runtime parameters.
-
Use a legacy scheduler configuration file to configure the runtime built-in scheduler service.
Environment variables
Startup variables
The following optional environment variables may be defined to configure the Runtime startup.
| Environment variable | Description |
|---|---|
|
Path of the Java Virtual Machine used by the Runtime. This variable is set to the default Java Virtual Machine installed, and may be changed to use a specific JVM version. |
|
Path of directory containing the configuration file. Use this property to store the configuration separately from the Runtime installation. For example, |
|
Space separated list of additional Java arguments to use when executing Runtime runnable scripts. Use the same syntax as the command line. Example 1. Example list of arguments:
|
|
Space separated list of additional Java arguments to use when executing the Runtime Example 2. Example list of arguments:
|
With the default configuration, the xDI Runtime memory is automatically managed by the JVM. This is recommended and enough in most cases. If you want to force memory settings, use the XDI_RUNTIME_OPTS and XDI_COMMAND_OPTS variables to pass the corresponding Java settings, such as -Xmx, -Xms and -Xss.
|
Environment variables in configuration files
You can use system environment variables in Runtime configuration file parameters using the following syntax:
${environment.variable:<ENV_VARIABLE_NAME>:<default value>}
In this syntax:
-
<ENV_VARIABLE_NAME>is the environment variable name -
<default value>is the fallback value to use if the environment variable is unset.
For example, with the following syntax the launchSchedulerEngine parameter will take the value of the XDI_DESIGNER_SCHEDULER_ENABLE environment variable, but fall back to a true value if that environment variable is unset.
<parameter
name="launchSchedulerEngine"
value="${environment.variable:XDI_DESIGNER_SCHEDULER_ENABLE:true}"
/>
You can find examples of configurations customized with environment variables in the properties/samples/enginesParameters directory.
|
| Use this mechanism to configure Runtime entirely using environment variables, such as when running it in Docker containers. |
Deprecated environment variables
Some environment variables from older versions of Semarchy xDI are still available but are deprecated, and will no longer work after Designer version 2024.1 LTS. They are listed in the following table, along with suggested replacements.
| Legacy environment variable | Suggested replacement |
|---|---|
|
|
|
|
|
Add related java options to |
|
Add related java options to |
|
Add related java options to |
|
(not needed, no replacement) |
|
(not needed, no replacement) |
Migrating the STAMBIA_INIT_MEMORY, STAMBIA_MAX_MEMORY, and STAMBIA_STACK_SIZE environment variables is optional. We recommend removing them, and letting the Java virtual machine manage memory by itself.
|
Configuration files
The runtime uses an engineParameters.xml file to store its configuration. This file is located in the properties sub-directory of the Runtime installation directory by default.
You can define the configuration file location for the runtime by setting an XDI_RUNTIME_PROPERTIES_LOCATION environment variable.
To make upgrades easier, it is recommended to copy the properties directory to a location outside the runtime installation directory, and set the XDI_RUNTIME_PROPERTIES_LOCATION to point to the new location. This way, overwriting the runtime folder during an upgrade will not lose any configuration information.
|
The runtime also supports a legacy configuration file named engineScheduler.properties which holds a standalone scheduler configuration.
Runtime configuration file
By default, the Runtime configuration file is located in the properties sub-directory of the Runtime installation directory, and is named engineParameters.xml.
You can use this file to configure:
-
The scheduler parameters
-
The services that are started, listening ports, etc.
-
The security parameters, such as hostname and user/password restrictions, roles, etc.
-
The repositories which store deliveries
-
The log storage where session logs are stored
Scheduler configuration file
Previous versions of Runtime used an engineScheduler.properties file to store scheduler configuration information. Runtime still supports this file for compatibility purposes.
Refer to Legacy configuration file for more information.
| Support for this file may be removed in future releases. |