HCMS Client application configuration

[]

This chapter contains a comprehensive overview of all Client configuration options and how and why they must be set.

Introduction

Application configuration is subject to changes during the whole implementation project. A basic configuration is provided during the initial installation, e.g., local installation and allows to start a blank portal. Indeed, any customization requires changes in this default configuration, especially, for the purpose of frontend development.

Configuration exists in the JSON format.

Note: throughout this document we refer to a virtual configuration that exists on runtime. docker-compose.yml also contains a template with the most important Client configuration properties, but not all possible properties.

In-memory merge on image build

How virtual configuration is created

With the source code, we provide config.standalone.json which is copied as config.json when the Docker image is built. config.json is listed in .gitignore to prevent you from commiting it and getting into conflict with changes done by other developers in your team, or from sharing secrets.

Adding configuration by editing any of those files is possible, but is not recommended, until we explicitly ask you to do so in the documentation. Since it is challenging to replace a file inside the Docker container, the final configuration is created by merging config.json with the CONFIG environmental variable - another JSON - that contains your custom values. With "merge" we mean an in-memory merge on startup of the container (of the application).

Apart from the CONFIG variable, the Docker container also accepts some other variables.

Such ad-hoc virtual configuration allows you to avoid sending sensitive data to Git (instead, you use the environmental variable), but helps to keep mandatory configuration in place (for this, you use the config.json).

Overview of environmental variables

CONFIG variable can encompass anything that does not fit into the other variables and needs to be in JSON format
SESSION_SECRET variable only contains a secret and needs to be in a string format

How to add environmental variables

Below is an example of passing the CONFIG variable to the Docker container on start:

BASH

export CONFIG='{"prefix":"/hcms-client", "sessionSecret":"xxx"}'
docker run --env CONFIG

For CI/CD automations, you can simply add your variables to the Helm Chart or any other pipeline configuration.

Rules for merging properties

Common rules (for the `CONFIG` variable).

Please keep in mind that, depending on the value data type in the property, the outcome of the merge is different.

If the value for the same property in the CONFIG variable and in the default file is a JSON object, then those objects are merged (combined into one)!
- For nested properties, the merge happens only if the same condition (JSON meets JSON) is met on all levels.
If at least on one level the value of the property in the config.json is non-object, this value is simply replaced by the value from the CONFIG variable. Therefore, please make sure you use correct values to prevent undesired overrides.

Special cases

The property sessionSecret is always overriden by the value in the SESSION_SECRET variable.

Special notes on configuration

Running application outside of the Docker image

If you want to run the application without building a Docker image, you will need to create the config.json manually and not from the config.standalone.json file, but from the /backend/config.local.json instead.

Schema directory

Warning keep in mind that the hardcoded (default) location for schemas that is created during the image build ensures stable functioning of the application. You can change it in the config.json created for local development and debugging purposes as exaplined above. However it is highly possible that, by doing this, you will actually break the application.

Dynamic portal configuration

Theming and other dynamic (and less critical) configuration is not part of the main configuration. The main configuration only points to it using various methods as described here.

Module configuration

Module configuration is assembled from multiple elements:

main portal configuration (config.json and optionally CONFIG variable) that defines which modules should be present in the UI, see also here
design/dynamic configuration as mentioned above and described here
- for the initial "blank" portal setup, default theming etc are taken from moduleConfig.json
configurations stored in the module-info.json files, one per each module, details can be found here