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.
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:
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:
Where the following is true:
This command is optional. Assigns a name to the container.
Define the host name or IP address of your CAST Storage Service/PostgreSQL instance. This instance will be used for two things:
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.
|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.
Define the credentials for the CAST Storage Service/PostgreSQL configured in the CSS_HOST field. Default credentials are:
|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>]]
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:
|-e deployHDED=yes|no -p <HDED_host_port>:8080
|(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:
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:
The internal ports MUST be defined as follows:
For example to deploy only the combined Health/Engineering dashboard on public port 80, use the following:
To deploy the combined Health Dashboard on port 8080 and the Security Dashboard on public port 80:
|-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
This command is optional. Defines the name of the Measurement schema. Only required if you have chosen to deploy the following:
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_CENTRAL_SCHEMA="<schema1>, <schema2>"
This command is optional. Define the name of the Dashboard (central) schema. Only required if you have chosen to deploy the following:
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
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:
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
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.
This command is optional. Defines the authentication mechanism used to login to the Dashboards. If this option is omitted,
Mandatory LDAP options:
Optional LDAP options:
For more information about LDAP, see User authentication.
Mandatory SAML options:
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:
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):
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:
To take release 2.9.1-funcrel:
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>
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:
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:
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
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.
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).
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:
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:
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:
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:
This can occur for two reasons:
- 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.
- 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:
- 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.
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 castDashboardLicensecommand when starting the dashboard(s):