How to upgrade HCMS CSK

Important notice

We highly recommend you to have your build pipeline automated to facilitate development and upgrades of your application.
When upgrading to the latest version, always repeat the server preparation part! This ensures that masterdata and all XSLT templates are up-to-date and also creates any other missing service and module configurations. However, the server preparation scripts do not modify existing configurations. For this reason, in some cases, a manual intervention may be necessary, depending on which version you are on and to which version you want to upgrade.
We try to provide generalistic instructions, but a lot depends on your setup and we cannot cover every specific deployment.

Upgrade from 1.x to 2.0

Please keep in mind that the latest HCMS CSK version is 4. Although we provide upgrade instructions for version 2, the rest of the present documentation is written for version 4.

Clone HCMS CSK git repository

BASH

git clone https://gitlab.censhare.com/oc/product/release/hcms-client-starter-kit.git

Update statistics cleanup configuration

Without this step, the user statistics module won't work and no data visualizations will be displayed. To avoid this, we need to remove one of user tracking automations prior to starting the server preparation. Preparation scripts will re-create it correctly, and the problem won't appear. The corresponding configuration is stored in the Admin Client, under Modules / Statistics / HCMS Client - User Tracking Cleanup.

Exact steps:

in the Admin Client, under Modules / Statistics
- remove the "HCMS Client - User Tracking Cleanup"
- push the "Update server configuration" or "Synchronize remote servers" button Note that although this configuration is stored in the Admin Client, it cannot be updated in its GUI due to a bug.

Run the server preparation

Run the server preparation scripts. Among other configurations, the "HCMS Client - User Tracking Cleanup" is created again, with updated content.

Build and deploy the application

Build and deploy the HCMS CSK image

Upgrade from 2.x or 3.x to 4.0

The main challenge of upgrading to version 4 comes from the fact that only version 4 uses a Docker Compose setup. Please feel free to check the explanatory articel on Docker Compose setup as well as other steps in the local installation chapter which is based on Docker Compose.

Clone HCMS CSK git repository

BASH

git clone https://gitlab.censhare.com/oc/product/release/hcms-client-starter-kit.git

Run the server preparation

Run the server preparation scripts.

Add the session encryption key

HCMS CSK version 4 uses a session encryption key. This is a new feature which was not present in the previous versions. For this reason, the key will be by default missing in the config-json.md after the upgrade. Without this value set, the application will not start at all! There are multiple ways to set it, depending on the target environment - local or production - and the CI/CD automation setup you are using.

add a new property "sessionSecret" to the configuration JSON (config.json) or
add this value in the Helm Chart if you use CI/CD and Helm or
pass it as an environment variable SESSION_SECRET to the Docker container on the next steps
BASH
```
docker run --env SESSION_SECRET
```
or
change the default value in the docker-compose.yml (for the local installations only, see the next step!)

The value must be at least 32 characters long. This requirement might be lower when using the database as a session store. Details about the value, implementation and possible session storages can be found in the config JSON documentation.

Build and deploy the application

Build and deploy the application using one of the methods described below. Which one to choose will depend on the environment and/or whether you want to use Docker Compose or physically separated Docker containers. Please also feel free to check the local installation chapter to learn about the Docker Compose setup for local development.

for Docker Compose / local installation setup:
- prepare your Docker host
- build and deploy composed images
for the productive upgrade:
- build and deploy the HCMS CSK image