Define the startup configuration

This page 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 setup token, which is required for the first login.

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

Startup configuration contents

Setup token

The setup token is a value required the first time you connect to Semarchy xDM to create or upgrade the repository. It serves as an authentication method to configure the administrator login and password.

The setup token must be defined as a SEMARCHY_SETUP_TOKEN system environment variable or system property.

After the initial installation or upgrade, make sure to delete the setup token from the configuration as it is no longer required.

Repository connections

The repository requires two connections:

  • 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 mainly used by xDM Discovery to browse profiles.

Repository connections are established using the following startup configuration methods:

For the complete list of properties used to configure these datasources, see Startup configuration reference.

The startup configuration may also include the secrets management configuration to:

  • Employ multiple key management services (KMS) for encrypting secrets stored within the repository, with one of them designated as current KMS.

  • Use multiple secrets managers for accessing secrets (i.e., passwords, keys, etc.) stored in external secrets managers such as AWS Secrets Manager, Azure Key Vault, or Google Cloud Secret Manager.

Define startup configuration using environment variables

This section explains how to quickly create a startup configuration using system environment variables. For simplicity, the examples below are tailored for Windows instances running Tomcat as a service.

To create a startup configuration:

  1. From the samples provided below, copy the one that corresponds to your database technology.

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

  3. Execute the commands with a command prompt on the application server.

System environment variables can be set using Windows Control Panel if you prefer a graphical interface.

In the examples below, replace the instruction SET with SETX if you want to set the environment variables permanently.

Startup configuration for PostgreSQL

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

Sample configuration for an 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

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

Startup parameters can be set using environment variables. The use of a configuration file or Java system properties provides additional flexibility. For more information, see Startup configuration methods.

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