Define the Startup Configuration

This document explains how to define the Semarchy xDM startup configuration.

Introduction

The Startup Configuration is the bootstrap configuration required for Semarchy xDM to start. It includes:

  • The Repository Datasources configuration, required for Semarchy xDM to access the repository database.

  • Optionally, the Secrets Management configuration, used to encrypt secrets using key management services or store secrets in secrets managers.

The startup configuration is composed of properties, set using the following methods:

For the first startup of the Semarchy xDM application, you also need to configure a Setup Token you will use to authenticate and create the repository. The setup token must be passed as an environment variable.

Required Configuration

The startup configuration is required for Semarchy xDM to start and connect the repository database. Make sure to prepare that configuration before installing or starting the application.

Similarly, the Setup Token will be requested to access Semarchy xDM for the first login. Make sure to set this token before the first access.

Create a Startup Configuration

This section explains how to quickly create a simple startup configuration using environment variables.

To create a startup configuration:

  1. Edit the file containing the application server environment variables:

    • If you run Tomcat as a process, edit the setenv.sh (Linux/Unix) or setenv.bat (Windows). This file is located in the /bin sub-folder in the Apache Tomcat installation folder.

    • If you run Tomcat as a service, edit the /etc/default/tomcat9 file.

    • For other application servers, refer to the server documentation.

  2. Append to this file the samples below to create the startup configuration environment variables.

  3. Adapt the variable values to your configuration, using the database name, user names, and passwords that you entered when configuring the database schemas.

Make sure to select the sample corresponding to your database technology and your server operating system.

Startup Configuration for PostgreSQL

Example 1. Sample configuration for a PostgreSQL repository (Linux/Unix).
# Repository datasource
export XDM_REPOSITORY_DRIVER=org.postgresql.Driver
export XDM_REPOSITORY_URL=jdbc:postgresql://localhost:5432/postgres
export XDM_REPOSITORY_USERNAME=repository_user
export XDM_REPOSITORY_PASSWORD=repository_password
# Repository read-only datasource credentials
export XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
export XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
# Setup Token
export SEMARCHY_SETUP_TOKEN=mySecretValue
Example 2. Sample configuration for a PostgreSQL repository (Windows).
rem Repository datasource
set XDM_REPOSITORY_DRIVER=org.postgresql.Driver
set XDM_REPOSITORY_URL=jdbc:postgresql://localhost:5432/postgres
set XDM_REPOSITORY_USERNAME=repository_user
set XDM_REPOSITORY_PASSWORD=repository_password
rem Repository read-only datasource credentials
set XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
set XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
rem Setup Token
set SEMARCHY_SETUP_TOKEN=mySecretValue

Startup Configuration for SQL Server

Example 3. Sample configuration for a SQL Server repository (Linux/Unix).
# Repository datasource
export XDM_REPOSITORY_DRIVER=com.microsoft.sqlserver.jdbc.SQLServerDriver
export XDM_REPOSITORY_URL=jdbc:sqlserver://localhost:1433;databaseName=REPOSITORY
export XDM_REPOSITORY_USERNAME=repository_user
export XDM_REPOSITORY_PASSWORD=repository_password
# Repository read-only datasource credentials
export XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
export XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
# Setup Token
export SEMARCHY_SETUP_TOKEN=mySecretValue
Example 4. Sample configuration for a SQL Server repository (Windows).
rem Repository datasource
set XDM_REPOSITORY_DRIVER=com.microsoft.sqlserver.jdbc.SQLServerDriver
set XDM_REPOSITORY_URL=jdbc:sqlserver://localhost:1433;databaseName=REPOSITORY
set XDM_REPOSITORY_USERNAME=repository_user
set XDM_REPOSITORY_PASSWORD=repository_password
rem Repository read-only datasource credentials
set XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
set XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
rem Setup Token
set SEMARCHY_SETUP_TOKEN=mySecretValue

Startup Configuration for Oracle

Example 5. Sample configuration for an Oracle repository (Linux/Unix).
# Repository datasource
export XDM_REPOSITORY_DRIVER=oracle.jdbc.OracleDriver
export XDM_REPOSITORY_URL=jdbc:oracle:thin:@localhost:1521:XE
export XDM_REPOSITORY_USERNAME=repository_user
export XDM_REPOSITORY_PASSWORD=repository_password
# Repository read-only datasource credentials
export XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
export XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
# Set the current schema of the readonly user to the repository
export XDM_REPOSITORY_READONLY_CONNECTIONINITSQL="ALTER SESSION SET CURRENT_SCHEMA = '$XDM_REPOSITORY_USERNAME'"
# Setup Token
export SEMARCHY_SETUP_TOKEN=mySecretValue
Example 6. Sample configuration for an Oracle repository (Windows).
rem Repository datasource
set XDM_REPOSITORY_DRIVER=oracle.jdbc.OracleDriver
set XDM_REPOSITORY_URL=jdbc:oracle:thin:@localhost:1521:XE
set XDM_REPOSITORY_USERNAME=repository_user
set XDM_REPOSITORY_PASSWORD=repository_password
rem Repository read-only datasource credentials
set XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
set XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
rem Set the current schema of the readonly user to the repository
set XDM_REPOSITORY_READONLY_CONNECTIONINITSQL='ALTER SESSION SET CURRENT_SCHEMA = repository_user'
rem Setup Token
set SEMARCHY_SETUP_TOKEN=mySecretValue

When the startup configuration is defined, you can move to the next step and deploy Semarchy xDM.

You can also read the next sections to learn more about the startup configuration contents and configuration methods.

Startup Configuration Contents

This section details the contents of the startup configuration.

Repository Connections

In the samples above, two connections to the repository are defined:

  • The Repository Datasource, with credentials allowing to read from and write into the repository schema.

  • The Repository Read-Only Datasource, with credentials allowing to read a subset of the tables stored in the repository schema. This datasource is used mainly by xDM Discovery to browse the profiles.

The properties used to configure these datasources are listed in the Startup Configuration Reference

Setup Token

In the samples, the SEMARCHY_SETUP_TOKEN environment variable contains the Setup Token.

The Setup Token is a value required the first time you connect to Semarchy xDM to create or upgrade the repository. This token is used as an authentication method to let you configure the administrator login and password.

After the initial installation or upgrade, the setup token is no longer used and can be removed from the configuration.

Secrets Management

The startup configuration may also include the secrets management configuration:

  • Multiple Key Management Services (KMS) to encrypt secrets stored in the repository, with one of them set as the Current KMS.

  • Multiple Secrets Managers to access secrets (passwords, keys, etc) stored in external secrets managers such as AWS Secrets Manager, Azure Key Vault, or Google Cloud Secret Manager.

The Secrets Management configuration properties are detailed in Secrets Management.

Startup Configuration Methods

This section explains the methods to set the startup configuration properties.

The startup configuration is composed of a set of Configuration Properties with their values. Properties names are lowercase strings with dots 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

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"

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 userscore characters. For example, the xdm.secrets.internal.kms.current property value will be set in the XDM_SECRETS_INTERNAL_KMS_CURRENT environment variable.

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

Example 7. 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 8. Set a configuration property with an environment variable (Windows)
rem Set environment variable: Windows
set XDM_SECRETS_INTERNAL_KMS_CURRENT "awscorporate"
rem See the variable value
rem echo %XDM_SECRETS_INTERNAL_KMS_CURRENT%

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

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, Semarchy xDM looks by default 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

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 9. Configure the configuration file location in <tomcat_home>/bin/setenv.sh.
# Append this line to setenv.sh
CATALINA_OPTS="$CATALINA_OPTS -Dxdm.config.file=/etc/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:

  1. In the Home directory of the user starting the application server running Semarchy xDM, create a folder named .xdm.

  2. Create in that folder 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 10. 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 11. Sample configuration file for a 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 12. 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.

Configuration Methods Priority

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

  1. From the configuration file,

  2. From the corresponding environment variable, overriding the configuration file value,

  3. 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.