Startup configuration methods

This page describes the different startup configuration methods for Semarchy xDM.

The startup configuration is composed of a set of Configuration Properties with their values. Property names are lowercase strings with dot delimiters. They start with the xdm. prefix.

For example:

xdm.config.file configures the location of the default configuration file.
xdm.secrets.internal.kms.current configures the alias of the current key management service used to encrypt secrets.

There are three ways to set the configuration properties:

Java system properties
Environment variables
Configuration file

Configuration method priority

The value of each property is read in the following order:

From the configuration file.
From the corresponding environment variable, overriding the configuration file value.
From the Java system property, overriding the configuration file and/or environment variable values.

For example, if a property is set in the configuration file and as a Java system property, then the Java system property is used.

The different methods for the startup configuration are useful for each type of setup:

Environment variables are typically used for container or cloud deployments.
The configuration file is a simple way to make the configuration persistent for a traditional on-premises setup.
Java system properties are commonly used in Java application deployments.

Java system properties

With this method, configuration properties are set in the startup command of the Java Machine running Semarchy xDM, using the following syntax:

-D<property.name>=<value>

For example:

-Dxdm.secrets.internal.kms.current=awscorporate

For Tomcat, you can set such a property in the <tomcat>/bin/setenv.sh|bat file, as shown below:

CATALINA_OPTS="$CATALINA_OPTS -Dxdm.secrets.internal.kms.current=awscorporate"

On Windows, you can alternatively use the Tomcat Configuration GUI tool to define these properties in the Java Options field of the Java tab.

Environment variables

With this method, variables are set in the environment running the Java machine.

The variable names are derived from the Java properties, uppercased and with all the dots replaced by underscore characters. For example, the xdm.secrets.internal.kms.current property value is set in the XDM_SECRETS_INTERNAL_KMS_CURRENT environment variable.

The following examples illustrate how to set this configuration property in the environment.

Example 1. Set a configuration property with an environment variable (Linux/UNIX)

# Set environment variable: Unix/Linux
export XDM_SECRETS_INTERNAL_KMS_CURRENT=awscorporate
# See the variable value
# echo $XDM_SECRETS_INTERNAL_KMS_CURRENT

Example 2. Set a configuration property with an environment variable (Windows)

rem Set environment variable: Windows
set XDM_REPOSITORY_DRIVER=oracle.jdbc.OracleDriver
rem See the variable value
rem echo %XDM_REPOSITORY_DRIVER%

When running Tomcat as a service on Windows, it is recommended to set the startup configuration using environment variables. It can be achieved either:

From the Windows Control Panel.

Environment variables set in the Control Panel must be set as System Variables when Tomcat runs as a service.
By configuring the service using the Tomcat tooling.
Example 3. Add an environment variable for Tomcat running as a service (Windows)
```
tomcat9 //US//Tomcat9 ++Environment XDM_REPOSITORY_DRIVER=oracle.jdbc.OracleDriver
```

Semarchy xDM automatically recognizes the configuration properties from the environment variables.

The /samples folder in the Semarchy xDM package that you downloaded contains complete configuration samples using environment variables, in the setenv_sample.sh and setenv_sample.bat files.

Configuration file

You can define startup configuration properties in a single properties file.

When starting, by default, Semarchy xDM looks for a <USER_HOME>/.xdm/config.properties properties file containing the startup configuration. You can also change the location of this file using the xdm.config.file configuration property.

Property (Environment Variable) Description

Property (Environment Variable)	Description
`xdm.config.file` (`XDM_CONFIG_FILE`)	Startup configuration file path. Defaults to `<USER_HOME>/.xdm/config.properties`, where `<USER_HOME>` is the home directory of the user starting the Semarchy xDM server.

xdm.config.file
(XDM_CONFIG_FILE)

Startup configuration file path. Defaults to <USER_HOME>/.xdm/config.properties, where <USER_HOME> is the home directory of the user starting the Semarchy xDM server.

Example 4. Configure the configuration file location in <tomcat_home>/bin/setenv.sh (Linux/UNIX)

# Append this line to setenv.sh
CATALINA_OPTS="$CATALINA_OPTS -Dxdm.config.file=/etc/xdm/dev_001.properties"

Example 5. Configure the configuration file location in <tomcat_home>bin\setenv.bat (Windows)

rem Append this line to setenv.bat
set "CATALINA_OPTS=%CATALINA_OPTS% -Dxdm.config.file=\<USER_HOME>\xdm\dev_001.properties"

When running Tomcat as a process, you can quickly configure the startup configuration using this properties file.

To create the startup configuration:

In the Home directory of the user starting the application server running Semarchy xDM, create a folder named .xdm.
In that folder, create a config.properties file, using one of the samples below.

Configuration file samples

The following samples define the repository datasources using a configuration file.

Example 6. Sample configuration file for a PostgreSQL repository.

# Repository datasource
xdm.repository.driver=org.postgresql.Driver
xdm.repository.url=jdbc:postgresql://localhost:5432/postgres
xdm.repository.username=repository_user
xdm.repository.password=repository_password
# Repository read-only datasource credentials
xdm.repository.readonly.username=repository_readonly_user
xdm.repository.readonly.password=repository_readonly_password

Example 7. Sample configuration file for an SQL Server repository.

# Repository datasource
xdm.repository.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
xdm.repository.url=jdbc:sqlserver://localhost:1433;databaseName=REPOSITORY
xdm.repository.username=repository_user
xdm.repository.password=repository_password
# Repository read-only datasource credentials
xdm.repository.readonly.username=repository_readonly_user
xdm.repository.readonly.password=repository_readonly_password

Example 8. Sample configuration file for an Oracle repository.

# Repository datasource
xdm.repository.driver=oracle.jdbc.OracleDriver
xdm.repository.url=jdbc:oracle:thin:@localhost:1521:XE
xdm.repository.username=repository_user
xdm.repository.password=repository_password
# Repository read-only datasource credentials
xdm.repository.readonly.username=repository_readonly_user
xdm.repository.readonly.password=repository_readonly_password
# Set the current schema of the readonly user to the repository
xdm.repository.readonly.connectioninitsql=ALTER SESSION SET CURRENT_SCHEMA = repository_user

The /samples folder in the Semarchy xDM package that you downloaded contains a complete configuration property file sample named config_sample.properties.