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 formatSESSION_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:
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
CONFIG
variable).
Common rules (for the 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 theCONFIG
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 optionallyCONFIG
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
- for the initial "blank" portal setup, default theming etc are taken from
- configurations stored in the
module-info.json
files, one per each module, details can be found here