Local installation HCMS CSK

Please make sure that you have read the HCMS CSK infrastructure overview  and understand components of the application.

Scope of this guide

The following tutorials provide instructions on how to install the HCMS Client Starter Kit locally, for development or demonstration purposes. However:

• It is limited to the installation itself. How to start with the actual development, is described in the next chapter.

• With some modifications, it can also be used with some kind of docker infrastructure system like Kubernetes; such modifications are out of scope for this guide.

Note: The articles in this section are numbered: please follow the numbering order to achieve a successful installation.

Notes on this setup

This is a special setup created to allow development even with the current state of very restrictive browser behavior. As a bonus, it also provides a very convenient way to create demo environment without an advanced knowledge of cloud architecture and (more importantly) without network administration permissions.

Detailed discussion about this special setup

This section is an optional reading: it is not mandatory, but it might provide some helpful background information.

HCMS Client has been designed as a "cloud-based" application. Running it on a single machine is a challenge. As a solution, we provide instructions for running it locally in more than one container. In particular, this setup helps to solve the following challenges:

• Dedicated, special DNS domain for the application is not available yet (or cannot be easily obtained at all).

  • Solution: combination of HTTP "forward" proxy and Docker Compose networking.

  • When a browser uses configured HTTP "forward" proxy, the DNS domain is not needed because hostname resolution is done by the proxy itself. This proxy is running in a container where Docker Compose provides this hostname (instead of DNS).

    • Note that most browsers actually don't use forward proxy for http://localhost:* requests. This is important for when doing local frontend development.

  • Host resolution uses special property external_links in the docker-compose.yml - it adds custom hostname, without the need of DNS server.

  • squid is used for this purpose and exposed on port 3128

    • The image is built from scratch (based on the alpine linux) and run as a separate container.

• Both parts of the application (hcms and hcms-client) are available on the single domain, with path-based routing (/hcms/ prefix for hcms container, all other traffic to hcms-client).

  • Solution: HTTP "reverse" proxy

  • haproxy is used for this purpose

    • It is not run as a separate container, but inside the hcms-client container instead. This means that the hcms-client docker image is not used directly (new auxiliary one is built).

• https protocol (TLS/SSL termination)

  • Solution: the haproxy again

  • Both certificate and the private key are provided as a file in mounted directory ssl (that filename is hardcoded as hcmsclient.pem).

  • If available, the certificate+key can be provided as an optional parameter of the preparation script (prepare-env.sh).

• Automatically generated (self-signed) TLS certificate

  • Solution: openssl (used as a part of openjdk image)

  • The preparation script (prepare-env.sh) checks the provided PEM file (if any) or the ./ssl/hcmsclient.pem (if it already exists). If the file is present, contains both key and certificate and the certificate is for the correct domain, it is used. Otherwise, new self-signed certificate is generated and saved as ./ssl/hcmsclient.pem (which is then used by the haproxy).

  • Note that self-signed certificate does not automatically work in any browser and must be explicitly accepted. This might require a secret code (notably in Chrome, the secret code is thisisunsafe)

• Using self-signed certificate in cross-component communication.

  • Solution 1: for hcms-client, special environment variable NODE_TLS_REJECT_UNAUTHORIZED is set to value 0

    • This is done directly in the Dockerfile

  • Solution 2: for hcms, the certificate is added to the list of trusted certificates

    • This is done by mounting the cacerts file directly inside JDK.

    • This cacerts file is patched by the preparation script (prepare-env.sh).

    • Note that the certificate is added even when it is actually provided from external source (and, presumably, isn't self-signed at all). This might be useful when a non-standard CA is used.

• Using cookies in a javascript from different domain (SameSite=None;Secure; flags required for all cookies)

  • Needed for local frontend development - otherwise, request to both backends are always sent without any cookie and thus are all unauthorized.

  • Solution: header rewriting (regular expression) in the haproxy

    • Enabled by non-empty environment variable UNSECURE_DEVELOPMENT, see the entry point script  entrypoint.sh

  • Must be explicitly enabled by the -d option of the preparation script (prepare-env.sh).

  • Warning: this mode also disables other security checks and in general should be used only in combination with some firewall rules.

• JWT secret and corresponding cookie access_token must be correctly configured. Also, user tracking must be enabled.

  • Solution: the HCMS configuration stored on server is actually ignored and a local configuration file is used instead.

  • The JWT secret key can be provided, but that is an optional step and a new random one is generated if necessary. This is perfectly fine, because the only important requirement is that both parts of the application use the same key.

  • In the real environment, both must be configured via the commandline client (or a corresponding change of the config xml). This is part of the cloud installation guide

    • Template configuration files are stored in  hcms-config.templates  directory and the ones with correctly filled values are in  hcms-config  directory. The latter one is then mounted in the  hcms  docker container.

    • It is possible to make custom changes, but please remember that the content of  hcms-config  is erased every time the preparation script runs!