Set Environment Configuration Properties

Introduction

Goal

Specify environment-specific configuration properties using configuration files.

Background

Applications typically require some environment-specific configuration to operate. For example, credentials or an API key to access a third-party service. In Bloomreach Cloud, you can specify such configuration properties using configuration files containing key-value pairs. The configuration files use the Java properties file format and can be used to specify Java system properties as well.

Create a Configuration File

In a plain text file, specify the key-value pairs in the Java properties file format, e.g.:

foo.service.url=https://example.org/foo/
foo.service.key=ABev2c6Rp5tC1YTYiklHn2hvn54XiZhu3Ce9Wte6

Manage Configuration Files

In Mission Control, navigate to the Files screen and select the Configurations tab:

Use the button in the bottom right corner to upload a configuration file.

Use each configuration file's context menu to rename it or delete it:

Configuration files cannot be replaced. If you upload a configuration file with the same name as a previously uploaded file, Bloomreach Cloud will append a suffix to the file name. For example, blue.properties becomes blue (1).properties.

Deploy Configuration Files with a Distribution

Navigate to the applicable environment and click on Deploy an application (or Redeploy an application).

In addition to selecting the distribution, you can select one or more configuration files to copy. Bloomreach Cloud will set a Java system property brc.appconfigfiles with a comma-separated list of file names as value.

Optionally, you can specify a new name for the configuration file. This is useful in case you manage differently named versions of the properties file but want to be able to always refer to the same file name from the distribution. For example, you could use semantic versioning in the names of the uploaded configuration files (blue.1.0.0.properties, blue.2.0.0.properties, blue.2.0.1.properties, etc.) but always use the same non-versioned name (blue.properties) when deploying in an environment.

You can also select on or more configuration files to use as Java system properties. In this case, Bloomreach Cloud will set a Java system property for each key-value pair in the configuration file(s). You can use the CMS admin panel to see the Java system properties with their values.

Retrieve Environment Name

Use the Java system property brc.environmentname to retrieve the name of an environment in your code.

Specify the Location of a Configuration File as Java System Property

Some use cases require that the location of a configuration file uploaded to Bloomreach Cloud is specified as a Java system property. To achieve this, use the variable ${APP_CONFIG_PATH} as in the following example:

spring.config.location=${APP_CONFIG_PATH}/spring.properties

Bloomreach Cloud will replace the variable with the actual path and pass spring.config.location as Java system property.

The location of the configuration files is also exposed through a  Java system property called brc.appconfigpath.

Configuring Javax.net.truststore

BRC does not allow javax.net.truststore as a parameter. If javax.net.truststore exists in the app config file as a parameter, the file upload will fail.

Configuring your brXM project to load HST config files

To use the BRC environment-specific config files for core brXM config files such as the platform.properties file, some small adjustments are required to the project.

For example, to deploy a different  platform.properties file to each environment:
1. BRC uses the system property brc.appconfigpath to identify the directory where the config files are deployed, so we need to make sure our HST config files are loaded from that directory. Set the hst-config-properties context-param to the value ${brc.appconfigpath}/platform.properties in the web.xml file in the /cms project:

<context-param>
    <param-name>hst-config-properties</param-name>
    <param-value>${brc.appconfigpath}/platform.properties</param-value>
</context-param>

2. In order for the local environment to keep working, we need to specify the system property brc.appconfigpath ourselves in the cargo profile by setting the system property in the cargo.run profile of the main pom.xml file of the project:

<brc.appconfigpath>conf</brc.appconfigpath>

3. Follow the instructions above to upload the different config files and deploy them. 
It's important to pay attention to the naming of the files during deployment, because we want to deploy all the files as platform.properties from the perspective of the CMS application. So for example in our case we could upload the environment-specific files: platform-production.properties, platform-acceptance.properties, and platform-test.properties but we would always deploy them as just platform.properties.

Configure repo.bootstrap

With BRC v12.6 it is possible to override the repo.bootstrap argument in a configuration file. For example:

repo.bootstrap=full

The default value is true and we recommend not to change it except for very special circumstances when you know what the effect is. Select the "use as Java system properties" option for the configuration file in the (re)deploy step.

To find out the BRC version, set the path of Mission Control to "#/version", so the complete URL would be something like: https://missioncontrol.customer.bloomreach.cloud/#/version

Configure timezone

You can adjust the timezone of the JVM on the server by uploading a configuration property file with a specified timezone like for example:

user.timezone=Etc/UTC

Change the timezone as desired. When deploying the CMS distribution, include the file as a Java system properties file.