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 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. This token is used as an authentication method to let you 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, the setup token is no longer used and can be removed from the configuration.

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 the profiles.

Repository connections are set using the following startup configuration methods:

The properties used to configure these datasources are listed in Startup configuration reference.

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

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

Define startup configuration using environment variables

This section explains how to quickly create a simple startup configuration using system environment variables. For simplicity, the examples below are made 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, user names, 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 the Windows Control Panel if you prefer a graphical interface.

In the following examples the instruction SET can be replaced by SETX if you want to set the Environment variables permanently.

Startup configuration for PostgreSQL

Example 1. 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 2. 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

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

You can set startup parameters using environment variables. The use of a configuration file or Java system properties provides additional flexibility. Details about using these startup configuration methods are included in the next section.

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