Created by James Hurrell on Jan 09, 2023

Summary: CAST Dashboards (Health, Engineering, Health/Engineering combined, Security) can be installed on Linux and Microsoft Windows operating systems as a set of Docker containers. This section explains how to install and upgrade them.

Introduction

This documentation provides instructions for deploying the standalone CAST Dashboards (Health, Engineering, Health/Engineering combined, Security) on a Docker instance. You can choose to deploy all four Dashboards at the same time, only one, or any combination: technically this means there is one single Docker container that can serve one single Dashboard type, all Dashboard types, or a combination.

Note that out of the box local authentication is configured (username/password can be defined). LDAP authentication can also be configured (SAML is not supported).

Step 1 - ensure deployment requirements are in place

Ensure that all requirements are in place. This includes the installation of any third-party software that is required to run CAST Dashboards on Docker.

Installation of third-party software is out of scope of this documentation, however, some tips can be found in the following third-party documentation:

Ubuntu 

CentOS

Microsoft Windows

Step 2 - pull the image and start the container

The CAST Dashboard image is stored on Docker Hub: https://hub.docker.com/r/castimaging/dashboards_linux so your machine must have access to this. To pull the latest image (i.e. containing the latest release of the Dashboards) and start the container, use the following pull command:

docker run --name <name> -e CSS_HOST=<css_server> -e CSS_DB_NAME=<db_name> -e CSS_USER=<css_username> -e CSS_PASSWORD=<css_password> -e CSS_PORT=<css_port> [-e CSS_HOST_x=<css_server> [-e CSS_PORT_x=<css_port> -e CSS_USER_x=<css_username> -e CSS_PASSWORD_x=<css_password> -e CSS_DB_NAME_x=<db_name>]] -e deployHDED=yes -p <HDED_host_port>:8080 -e deployH=yes -p <H_host_port>:8081 -e deployE=yes -p <E_host_port>:8082 -e deployS=yes -p <S_host_port>:8083 -e CSS_MEASURE_SCHEMA=<measurement_schema> -e CSS_CENTRAL_SCHEMA="<schema1>, <schema2>" -e castDashboardLicense='<license>' -e USERADMIN=<myuser> -e PASSWORDADMIN=<mypassword> -e SECURITYMODE=default|ldap castimaging/dashboards_linux:<tag>

Where the following is true:

OptionMandatory?Description
--name <name>(error)

This command is optional. Assigns a name to the container.

-e CSS_HOST=<css_server>(tick)

Define the host name or IP address of your CAST Storage Service/PostgreSQL instance. This instance will be used for two things:

  • to store the cast_dashboards schema which contains user/authorizations/license information - if this schema already exists from a previous installation, it will be re-used, otherwise it is created from scratch during the deployment
  • to access the Measurement and Dashboard (Central) schemas containing your application information

See below if you need to define additional CAST Storage Service/PostgreSQL instances if your Measurement and Dashboards schemas are stored on different hosts. Note that the cast_dashboards schema will ALWAYS be stored on the instance defined in the option CSS_HOST.

-e CSS_DB_NAME=<db_name>(error)This command is optional. Defines the database name in which the relevant schemas are stored on the CAST Storage Service/PostgreSQL configured in the CSS_HOST field. If you omit this option, then the default "postgres" database will be used.
-e CSS_USER=<css_username>(tick)

Define the credentials for the CAST Storage Service/PostgreSQL configured in the CSS_HOST field. Default credentials are:

  • css_username=operator
  • css_password=CastAIP
-e CSS_PASSWORD=<css_password>(tick)
-e CSS_PORT=<css_port>(tick)Define the port number for the CAST Storage Service/PostgreSQL configured in the CSS_HOST field.
[-e CSS_HOST_x=<css_server> [-e CSS_PORT_x=<css_port> -e CSS_USER_x=<css_username> -e CSS_PASSWORD_x=<css_password> -e CSS_DB_NAME_x=<db_name>]](error)

These options allow you to define additional CAST Storage Service/PostgreSQL instances if your Dashboard or Measurement schemas are stored on hosts other than the host defined in the CSS_HOST option:

  • If you do not use these options, then it is assumed that your Dashboard and Measurement schemas are all stored on the instance defined with the CSS_HOST option.
  • The cast_dashboards schema will ALWAYS be stored on the instance defined in the option CSS_HOST and cannot be defined on an additional instance.
  • You can reference any number of additional CAST Storage Service/PostgreSQL instances, but you should always start the "x" suffix from "2" and then increment by one for each additional instance. Therefore if you want to define two additional CAST Storage Service/PostgreSQL instances, you should use 2 and 3 as follows:
    • -e CSS_HOST_2=<css_server> -e CSS_PORT_2=<css_port> -e CSS_USER_2=<css_username> -e CSS_PASSWORD_2=<css_password> -e CSS_DB_NAME_2=<db_name> -e CSS_HOST_3=<css_server> -e CSS_PORT_3=<css_port> -e CSS_USER_3=<css_username> -e CSS_PASSWORD_3=<css_password> -e CSS_DB_NAME_3=<db_name>
  • The following are optional: -e CSS_PORT_x=<css_port> -e CSS_USER_x=<css_username> -e CSS_PASSWORD_x=<css_password> -e CSS_DB_NAME_x=<db_name>. If you do not use them:
    • -e CSS_PORT_x=<css_port> -e CSS_USER_x=<css_username> -e CSS_PASSWORD_x=<css_password> will use the same values defined for the mandatory options -e CSS_PORT=<css_port> -e CSS_USER=<css_username> -e CSS_PASSWORD=<css_password>
    • The default "postgres" database will be used if you omit -e CSS_DB_NAME_x=<db_name>
  • If you define additional CAST Storage Service/PostgreSQL instances, then you MUST specify the host for the following commands: -e CSS_MEASURE_SCHEMA and -e CSS_CENTRAL_SCHEMA as follows:
    • -e CSS_MEASURE_SCHEMA=<css host of measurement schema>:<measurement schema>
    • -e CSS_CENTRAL_SCHEMA="<css host of central schema 1>:<schema1>,<schema2>,<schema2> <css host of central schema 2>:<schema1>,<schema2>,<schema3>"
-e deployHDED=yes|no -p <HDED_host_port>:8080(tick) (One pair minimum)

These pairs of commands define the Dashboards you want to deploy in the single Docker container and the port they will run on. You must include at least one pair of commands (i.e. at least one Dashboard type):

-e Deploy options

Define (yes or no) whether you want to deploy the:

  • deployHDED = combined Health/Engineering Dashboard
  • deployH = Health Dashboard
  • deployE = Engineering Dashboard
  • deployS = Security Dashboard
Note that you can deploy all four Dashboards at the same time, only one, or any combination: technically this means there is one single Docker container that can serve one single Dashboard type, all Dashboard types, or a combination.

-p Port options

Define which "public" ports the chosen Dashboards should run on (i.e. the ports that end users will use to access the dashboards). The syntax is as follows where the public port must be unique and the internal port MUST not change:

public_port:internal_port

The internal ports MUST be defined as follows:

  • Combined Health/Engineering = 8080
  • Health Dashboard = 8081
  • Engineering Dashboard = 8082
  • Security Dashboard = 8083

For example to deploy only the combined Health/Engineering dashboard on public port 80, use the following:

  • -e deployHDED=yes -p 80:8080

To deploy the combined Health Dashboard on port 8080 and the Security Dashboard on public port 80:

  • -e deployH=yes -p 8080:8081 -e deployS=yes -p 80:8083
-e deployH=yes|no -p <H_host_port>:8081
-e deployE=yes|no -p <E_host_port>:8082
-e deployS=yes|no -p <S_host_port>:8083
-e CSS_MEASURE_SCHEMA=<measurement_schema>(error)

This command is optional. Defines the name of the Measurement schema. Only required if you have chosen to deploy the following:

  • deployHDED=yes
  • deployH=yes

For example:

  • -e CSS_MEASURE_SCHEMA=general_measure

If you have defined additional CAST Storage Service/PostgreSQL instances, then you MUST define which host the Measurement schema is stored on, as follows:

  • -e CSS_MEASURE_SCHEMA=<css host of measurement schema>:<measurement schema>
-e CSS_CENTRAL_SCHEMA="<schema1>, <schema2>"(error)

This command is optional. Define the name of the Dashboard (central) schema. Only required if you have chosen to deploy the following:

  • deployHDED=yess
  • deployE=yes
  • deployS=yes

For example:

  • -e CSS_CENTRAL_SCHEMA=my_central_schema1

If you have multiple Dashboard (central) schemas on the same CAST Storage Service/PostgreSQL instance, add them as a comma separated list, surrounded by double quote marks

  • -e CSS_CENTRAL_SCHEMA="my_central_schema1, my_central_schema2"

If you have defined additional CAST Storage Service/PostgreSQL instances, then you MUST define which host(s) the Dashboard schema(s) are stored on, as follows:

  • -e CSS_CENTRAL_SCHEMA="<css host of central schema 1>:<schema1>,<schema2>,<schema2> <css host of central schema 2>:<schema1>,<schema2>,<schema3>"
-e castDashboardLicense='<license>'(tick)

Defines your CAST Dashboard license key - ensure it is surrounded with single quote marks. A license key can only be generated by CAST Support. Please open a new ticket and request a license key for your CAST Dashboards.

If you are deploying ONLY a Health Dashboard (i.e. you are using only -e deployH=yes) then you do not need to define a license key since the key is only required to access a dashboard schema, i.e. a xxx_central schema).

-e USERADMIN=<myuser>(error)

This command is optional. Defines a user name and password for the local authentication mechanism. If these options are omitted, local authentication credentials will be automatically set to admin/admin (this user will have the ADMIN role).

Only functions when -e SECURITYMODE is set to default or is omitted entirely.

-e PASSWORDADMIN=<mypassword>
-e SECURITYMODE=default|ldap|saml(error)

This command is optional. Defines the authentication mechanism used to login to the Dashboards. If this option is omitted, default mode will be set:

  • default = simple local user/password combination. Out of the box the username/password is set to admin/admin but this can be changed using the -e USERADMIN and -e PASSWORDADMIN options.
  • ldap = allows you to use your organization's LDAP authentication mechanism. If this option is set, you must include additional options to configure the LDAP connection details. See section below.
  • saml =  allows you to use your organization's SAML authentication mechanism. If this option is set, you must include additional options to configure the SAML connection details. See section below.

LDAP options

Mandatory LDAP options:

  • -e LDAP_URL = LDAP url, in the form ldap://HOST:PORT
  • -e LDAP_BASE = The LDAP base where users and groups can be found, for example -e LDAP_BASE=dc=example,dc=com. You can alternatively configure -e LDAP_USERSEARCH_BASE and -e LDAP_GROUPSEARCH_BASE instead - if you do so, do NOT configure -e LDAP_BASE.
  • -e LDAP_USERSEARCH_BASE = The base for the user search. If you have defined -e LDAP_BASE do NOT configure -e LDAP_USERSEARCH_BASE.
  • -e LDAP_GROUPSEARCH_BASE = The base for the group search. If you have defined -e LDAP_BASE do NOT configure -e LDAP_GROUPSEARCH_BASE.
  • -e LDAP_MANAGER_DN = The DN for accessing the LDAP repository, for example: -e LDAP_MANAGER_DN=CN=serviceaccount,OU=RESOURCES,OU=FR,DC=example,DC=com
  • -e LDAP_MANAGER_PASSWORD = The password associated to the LDAP_MANAGER_DN value.

Optional LDAP options:

  • -e SECURITY_LDAP_MANAGER_KEY  = Enter encrypted credentials (see Encrypt login and password for database and LDAP) and then remove both -e LDAP_MANAGER_DN and -e LDAP_MANAGER_PASSWORD.

  • -e LDAP_USERSEARCH_FILTER = The filter to apply to the user search. The default value (i.e. when the option is not defined) is: (&(objectClass=user)(sAMAccountName={0}))

  • -e LDAP_GROUPSEARCH_ROLE_ATTRIBUTE = The attribute of a group entry to obtain the role name. The default value (i.e. when the option is not defined) is: cn

  • -e LDAP_GROUPSEARCH_BASE_FILTER = The base for the group search. The default value (i.e. when the option is not defined) is: (&(objectClass=group)(cn={0}))

  • -e LDAP_GROUPSEARCH_FILTER = The filter to use for the group search. The default value (i.e. when the option is not defined) is: (&(objectClass=group)(member={0}))

Examples:

  • -e SECURITYMODE=ldap -e LDAP_URL=ldap://192.168.200.2 -e LDAP_BASE=dc=example,dc=com -e LDAP_MANAGER_DN=CN=serviceaccount,OU=SHARED,DC=example,DC=com -e LDAP_MANAGER_PASSWORD=xxxxxxxxxxxxxxxxxxxxxxxxx
  • -e SECURITYMODE=ldap -e LDAP_URL=ldap://192.168.200.2 -e LDAP_BASE=dc=example,dc=com -e SECURITY_LDAP_MANAGER_KEY=6BBC48DB18A708FC140814DA4707817EFF13CD779358603D9DBF6DB1CF6660736F56F39B874DDB6

For more information about LDAP, see User authentication.

SAML options

Mandatory SAML options:

  • -v <some_path>:/metadata_saml = this is the path to the folder where the Federation Metadata xml and SAML/SSL key pairs are stored. This path will be mounted by the dashboard container.
  • -e HOST_NAME=<my_host_name> = the machine's host name - this host name will be passed to the SAML server.
  • -e SAML_METADATA_SOURCE=<myfederationmetadatafile.xml> = the Federation Metadata file must exist in the folder defined in the -v <some_path>:/metadata_saml option.
  • -e SAML_KEYSTORE_FILENAME=samlKeystore.jks = this file must exist in the folder defined in the -v <some_path>:/metadata_saml option.
  • -e SAML_KEYSTORE_DEFAULT_ALIAS=<alias> = the SAML keystore alias that was defined when the key pair was created (corresponds to the -alias option for keytool).
  • -e SAML_KEYSTORE_PASSWORD=<password> = the keystore password that was defined when the key pair was created (corresponds to the -keypass option for keytool).
  • -e SAML_SINGLE_LOGOUT=<true|false> = When SAML authentication is in operation, but no Single Logout service is provided in the IdP, you can force the dashboard to handle this situation gracefully and display a message explaining what to do by setting the option to true (default).
  • -e SAML_SSL_ENABLED=<true|false> - must be set to true since SAML requires that the dashboards are using the HTTPS protocol.
  • -e SAML_SSL_KEY_STORE_TYPE=jks = enter the type of SSL keystore you have used to generate the SSL public/private key pair. If you do not explicitly set this when generating the SSL public/private key pair (i.e. explicitly using the -storetype command), then it will default to JKS which is what you should enter.
  • -e SAML_SSL_KEY_STORE=sslKeystore.jks = this file must exist in the folder defined in the -v <some_path>:/metadata_saml option.
  • -e SAML_SSL_KEY_STORE_PASSWORD=<password> -the SSL keystore password you entered previously when prompted while generating the SSL public/private key pair.
  • -e SAML_SSL_KEY_ALIAS=<alias> - the SSL keystore alias that was defined when the key pair was created (corresponds to the -alias option for keytool).

For more information about the Federation Metadata xml file, the generation of the SAML and SSL key pairs and SAML in general, see User authentication.

Optional SAML options:

  • -e SAML_ATTRIBUTE_USERNAME=
  • -e SAML_ATTRIBUTE_GROUP=

Name of the username and/or group attribute (please discuss with your IT administrators about this option). Note that for group attributes, you should normally use (to be confirmed with your SAML admins): http://schemas.xmlsoap.org/claims/Group, for example:

  • -e SAML_ATTRIBUTE_GROUP=http://schemas.xmlsoap.org/claims/Group

Example:

  • -e SECURITYMODE=saml -v /home/cast/saml:/metadata_saml -e HOST_NAME=my_server -e SAML_METADATA_SOURCE=Federation-metadata.xml -e SAML_KEYSTORE_FILENAME=samlKeystore.jks -e SAML_KEYSTORE_DEFAULT_ALIAS=myalias -e SAML_KEYSTORE_PASSWORD=keypass -e SAML_SINGLE_LOGOUT=true -e SAML_SSL_ENABLED=true -e SAML_SSL_KEY_STORE_TYPE=jks -e SAML_SSL_KEY_STORE=sslKeystore.jks -e SAML_SSL_KEY_STORE_PASSWORD=keypass -e SAML_SSL_KEY_ALIAS=myalias
castimaging/dashboards_linux:<tag>(tick)

This entry determines the name and the release of the image to run. If the image does not exist locally, it will be automatically pulled from the Docker hub. You can see a list of releases here: https://hub.docker.com/r/castimaging/dashboards_linux/tags. For example to take the latest release:

  • castimaging/dashboards_linux:latest

To take release 2.9.1-funcrel:

  • castimaging/dashboards_linux:2.9.1_release_Build1141

Note that you may wish to use the -d flag : this will ensure that the process exists to the cursor. If you do so however, no start up logs are displayed, so you should run the following command to view them and ensure that the dashboard(s) is running:

docker logs --details -f <id|name of your container>

Examples

To deploy the latest release of the combined Health/Engineering dashboard on port 8080 and the Security Dashboard on port 80 using default local authentication and custom user credentials where the Measure and Dashboard schemas are all located on the same instance, run the following:

docker run --name castdashboards -e CSS_HOST=192.168.200.107 -e CSS_USER=operator -e CSS_PASSWORD=CastAIP -e CSS_PORT=2285 -e deployHDED=yes -p 8080:8080 deployS=yes -p 80:8083 -e CSS_MEASURE_SCHEMA=general_measure -e CSS_CENTRAL_SCHEMA="my_central1, my_central2, my_central3" -e USERADMIN=my_custom_user -e PASSWORDADMIN=my_custom_password -e castDashboardLicense='my_license_key' castimaging/dashboards_linux:latest

To deploy the latest release of the combined Health/Engineering dashboard on port 8080 and the Security Dashboard on port 80 using default local authentication and custom user credentials where:

  • the Measurement schema is located on the instance defined with CSS_HOST
  • the three Dashboard schemas (my_central1, my_central2, my_central3) are all located on different instances:
    • my_central1 is stored on CSS_HOST_2 (192.168.200.108)
    • my_central2 and my_central3 are stored on CSS_HOST_3 (192.168.200.109)

run the following:

docker run --name castdashboards -e CSS_HOST=192.168.200.107 -e CSS_USER=operator -e CSS_PASSWORD=CastAIP -e CSS_PORT=2285 -e CSS_HOST_2=192.168.200.108 -e CSS_PORT_2=2284 -e CSS_USER_2=operator -e CSS_PASSWORD_2=CastAIP -e CSS_HOST_3=192.168.200.109 -e CSS_PORT_3=2284 -e CSS_USER_3=operator -e CSS_PASSWORD_3=CastAIP -e deployHDED=yes -p 8080:8080 deployS=yes -p 80:8083-e CSS_MEASURE_SCHEMA=192.168.200.107:general_measure -e CSS_CENTRAL_SCHEMA="192.168.200.108:my_central1 192.168.200.109:my_central2, my_central3" -e USERADMIN=my_custom_user -e PASSWORDADMIN=my_custom_password -e castDashboardLicense='my_license_key' castimaging/dashboards_linux:latest

Success command

When the command is run, the start up logs are displayed and you should ensure that the Dashboards are running correctly - look for the success command:

Step 3 - next steps

Post install configuration steps

See also Standalone dashboard - post install configuration steps.

Check access

You should now ensure that you can access the Dashboard(s) you have chosen to deploy. Check this from an unrelated machine on the network by browsing to the host name/IP address of the dashboard, and the appropriate port number.

Become admin

The first user that logs in will be offered the chance to "become admin": see First login and become admin in the UI, however, unless you are accessing the Dashboards using the URL "localhost", you will not be able to "become admin". For headless deployments you will need to use the command line to "become admin", as described in First login and become admin. In addition, you will need to do this from within the Docker container itself (use docker exec -it <id|name of your container> bash to move into the container).

Tips

Dashboard customization

You can customize the Dashboards just like any other standalone deployment of CAST Dashboards direct on the OS, for example, modifying authentication, customizing tiles or layout, adding additional CAST Storage Service/PostgreSQL instances etc. etc. To do so, you will need to do this from within the Docker container itself (use docker exec -it <id|name of your container> bash to move into the container). Changes are permanent, including following a container restart. Following any changes that you make, you should restart the container using docker restart <id|name of your container>.

Stopping, starting or restarting the dashboards

Use the standard Docker commands to stop, start or restart the dashboards:

Start:
docker start <id|name of your container>

Stop:
docker stop <id|name of your container>

Restart:
docker restart <id|name of your container>

Upgrading to a new release

Using the same port

To upgrade to a new release, you will need to remove the existing container if you want to use the same port for your Dashboard, pull the release you require specifying the appropriate tag, then use the run command to run that image as a container:

docker stop <id|name of your container>
docker container rm <id|name of your container>
docker pull castimaging/dashboards_linux:<tag>
docker run --name castdashboards -e CSS_HOST=192.168.200.107 -e CSS_USER=operator -e CSS_PASSWORD=CastAIP -e CSS_PORT=2285 -e deployHDED=yes -p 8080:8080 -e CSS_MEASURE_SCHEMA=general_measure -e CSS_CENTRAL_SCHEMA="my_central1, my_central2, my_central3" -e USERADMIN=<my_custom_user> -e PASSWORDADMIN=my_custom_password -e castDashboardLicense='my_license_key' castimaging/dashboards_linux:<tag>

Doing the above will mean that you lose all customization you may have made.

Using alternative port (side-by-side)

This method allows you to run old and new dashboards side by side. It involves pulling the release you require, then running the release on a different port - for example, if you have the existing combined Health/Engineering Dashboard running on the public port 8080 (i.e. -p 8080:8080) and you want to run a newer release alongside, then change the first part of the port to a different free port: -p 8081:8080:

docker stop <id|name of your container>
docker container rm <id|name of your container>
docker pull castimaging/dashboards_linux:<tag>
docker run --name castdashboards -e CSS_HOST=192.168.200.107 -e CSS_USER=operator -e CSS_PASSWORD=CastAIP -e CSS_PORT=2285 -e deployHDED=yes -p 8081:8080 -e CSS_MEASURE_SCHEMA=general_measure -e CSS_CENTRAL_SCHEMA="my_central1, my_central2, my_central3" -e USERADMIN=<my_custom_user> -e PASSWORDADMIN=my_custom_password -e castDashboardLicense='my_license_key' castimaging/dashboards_linux:<tag>

Troubleshooting

ERROR [main] c.c.a.w.s.l.LicenseManager: License key has expired

You may see this error when attempting to start up your Dashboard:

Health and Engineering service is reachable.
Log file is: /cast/dashboards/health_engineering/startingDashboard.log
=============================================================
But there are errors in log file:
2023-01-04 14:45:46,254 ERROR [main] c.c.a.w.s.l.LicenseManager               : License key has expired

This can occur for two reasons:

  1. The license key you have defined in the command line may indeed have expired. If so, check the key's validity and if it has expired replace it with a valid key.
  2. The license key you have defined in the command line is entirely valid, but an expired key is referenced in the cast_dashboards schema on the CAST Storage Service/PostgreSQL instance defined in your command line, e.g. you started the dashboards successfully at one time and then the key subsequently expired. If this is the case, you have two choices:
    1. You can drop the cast_dashboards schema from the target CAST Storage Service/PostgreSQL instance - however doing so will also mean that you also lose any other customizations you may have made, for example user authorizations, profiles and roles.

    2. You can run a query against the cast_dashboards schema using PGAdmin to replace the expired key with a valid one as shown below (replace <license_key> with a valid key). Note that you will still need to specify the -e castDashboardLicense command when starting the dashboard(s):

UPDATE cast_dashboards.license
SET license_key = '<licence_key>' 
WHERE guid = 1;