Page tree
Skip to end of metadata
Go to start of metadata

Summary: describes how to deploy and configure CAST Dashboards embedded in the Console package using a JAR installer file. This documentation is only valid for those using the following:

  • Console ≥ 2.3.0 in Enterprise mode via Java JAR installers
  • Console ≥ 2.4.0 in Standalone mode
  • Console ≥ 1.29

If you are using:

On which host should I run the installer?

Console is preconfigured to expect that the embedded Dashboard service will be installed on the same host as your front-end Console services - as such CAST highly recommends that you follow this recommendation. If you need to install the embedded Dashboard service on another host, there are some additional manual steps that need to be actioned - see the section below Step 3 - Additional actions where the embedded Dashboards are installed on a remote host - optional.

Install process

Step 1 - Run the integrated RestAPI Java JAR installer

You must always use the following file provided with the current release of Console:

  • Console ≥ 2.3.0 in Enterprise mode via Java JAR installers use cast-integrated-health-engineering-dashboard-for-console-ee<version>-installer.jar
  • Console ≥ 2.4.0 in Standalone mode use cast-integrated-health-engineering-dashboard-for-console-se-<version>-installer.jar
  • Console ≥ 1.29 use cast-integrated-health-engineering-dashboard-for-console-ee-<version>-installer.jar

Unpack the media and locate the executable jar file. Now execute the JAR to start the interactive installer, as follows depending on your environment:

UI modeDouble click the file to start the installer.
CLI mode

Run the following command:

java -jar <name_of_jar_file>.jar -console

To run the installer local Administrator privileges are required on Microsoft Windows and elevated privileges are required on Linux.

UI mode

You may be prompted to accept a UAC warning, if so, click Yes:

The installation wizard will be displayed:

  • If the wizard cannot locate a previous installation in the default installation location, or in the Window Registry (if installing on Windows), then the Install option will be automatically selected.
  • If the wizard locates a previous installation of the package in the default installation location then the Upgrade an existing installation option will be automatically selected. In this case:
    • If you do not want to update the existing installation, ensure you choose the Install option and proceed with a "clean installation" in a different installation location.

Choose a location on the local machine that will be used for the CAST Dashboard installation. The setup will suggest: %PROGRAMFILES%\CAST\Dashboards\Console-HDED or %PROGRAMFILES%\CAST\Dashboards\Console-EE-HDED (Windows) and /root/CAST/Dashboards/Console-HDED or  /root/CAST/Dashboards/Console-EE-HDED (Linux) but you are free to choose a different location. If the folder does not already exist, the installation wizard will create it.

Choose a location for your CAST Dashboard "data" - this location will contain items such as logs and other items such as .properties and configuration files:

  • On a Microsoft Windows operating system, the installer will suggest: %PROGRAMDATA%\CAST\Dashboards\<folder but you are free to choose a different location.
  • On a Linux operating system, the installer will suggest: /root/ProgramData/CAST/Dashboards/folder but you are free to choose a different location.

Now fill in your CAST Storage Service/PostgreSQL information to ensure that Console knows where your application schemas and Measurement schema are located:

  • If you have only one single CAST Storage Service/PostgreSQL instance defined in Console, enter this here.
  • If you have multiple CAST Storage Service/PostgreSQL instances defined in Console you must enter one of them here - you can enter the connection details for any of the instances configured in Console, it doesn't matter which one. When you use the Synchronize action in Console (see below), any additional instances you have configured will be automatically added.

CSS/PostgreSQL configuration



Database host and portEnter the hostname/IP address and port number of the CAST Storage Service/PostgreSQL instanceThe field will be pre-filled with localhost:2282, which assumes a CAST Storage Service 3 installed on the local server - change this if necessary.
Database nameThe database name on your target CAST Storage Service/PostgreSQL instance. By default, postgres will be pre-filled, however, if you are using AIP Core ≥ 8.3.40 and you are storing your application schemas in a custom database (i.e. not the postgres database) enter the name of the custom database.
Database usernameEnter the credentials for the CAST Storage Service/PostgreSQL configured in the Database host and port field. The login and password fields will be pre-filled with the default credentials: operator/CastAIPThese credentials will be encrypted before being stored.
Database password

Now fill in the server port and config server URL:

OptionDescription
PortDefines the port on which the integrated RestAPI will listen for connections from Console. CAST recommends using the default 8087 port unless you have another service running on this port.
Config server URL

Enter the URL to the Console Service Registry service, using the port number 8088 unless you have customized this port. In most circumstances your Service Registry will be on the same host as the integrated RestAPI, therefore, you should use the default http://localhost:8088/config URL that is prefilled.

Note that when using the embedded Dashboards with a 2.x Standalone Console installation, this field is not visible.

Fill in the information that is required if you would like to install the integrated RestAPI with a Windows Service - this is optional. If you choose not to install as a Windows Service, you can alternatively use a predefined script file to start the service. This step is NOT displayed when running the installation wizard on a Linux operating system:

Windows ServiceInstall as a Windows Service

When unticked (default position), this option will NOT install the package as a Windows Service. If you want to install a Windows Service so that you can more easily stop and start the package, tick the option.

Start the service after installation

When ticked (default position) the Windows Service will be started after it is installed (recommended).

Note that the service will be set to start automatically and will be running unless you have specifically disabled this option.

Log on as

By default, this option is unticked and the Local System account will be used to run the service, however, CAST does not recommend this and a warning will be displayed when you click Next:

If you would like to use a Service User account to run the service, tick the option and fill in the credentials:

  • The installer requires a JAVA_HOME system environment variable pointing to the installation location of the Java JDK on the host machine.
  • You can change the log on as, after the install has completed by right clicking the service and changing the options in the Log On tab:

  • The installer will set the service to use the following RAM memory - you may find that this is not sufficient.
    • Initial memory pool = 256MB
    • Maximum memory pool = 1024MB

Choose whether to create shortcut icons and Start menu entries for the Dashboard package:

The installation process will start. Click Next when complete:

The installation process is complete:

CLI mode

The interactive console installer will then start. The steps for the installation process are similar to the GUI installation. Please refer to the GUI installation above for the list of required steps, parameters, default values, etc. Default values are indicated in square brackets ([like this]) and will be used if the input is not filled with a different value.

Step 2 - Start the RestAPI

Start up (if it is not already running) the RestAPI. The service will run on port 8087 by default - as defined during the installation:

  • either start the Windows Service if you are using Microsoft Windows and have chosen to install the Windows Service
  • or run the following file:
Microsoft Windows
%PROGRAMFILES%\CAST\Dashboards\<folder>\startup.bat

Linux
/root/CAST/Dashboards/<folder>/startup.sh
Note that you may need to run "chmod +x startup.sh" to grant execution permission to the script before running it.
You may also need to run this file with elevated permissions (e.g. sudo) using the following syntax "./startup.sh"
If you need to start the service automatically on Linux, you should consider creating a Linux service using systemd (available by default in the majority of main stream Linux distributions such as CentOS, Debian, Fedora, RHEL, SUSE and Ubuntu). This is beyond the scope of this document, however you may wish to read the following third party informationhttps://linuxconfig.org/how-to-automatically-execute-shell-script-at-startup-boot-on-systemd-linux.

Step 3 - Additional actions where the embedded Dashboards are installed on a remote host - optional

As explained above, Console is preconfigured to expect that the embedded Dashboard service will be installed on the same host as your front-end Console services, however if you need to install the embedded Dashboard service on a different host, there are additional manual steps that need to be actioned to ensure that Console can correctly locate it as explained below/

Enterprise mode - Java JAR installers/Windows Installer - "aip_config" schema update

Using pgAdmin, connect to the CAST Storage Service/PostgreSQL instance on which the aip_config schema has been installed (as described in Step 2 - Run Service Registry installer). Locate the properties table in the aip_config schema and then locate the dashboards.url entry as highlighted below:

Click to enlarge

The existing entry for the value column (http://${eureka.host}:8087) assumes that the embedded Dashboard service is installed on the same host as Console. As this is not the case, update the value entry URL to match the host/port on which the embedded Dashboard service has been installed, for example:

Now restart all front-end Console services and the embedded Dashboard service to ensure that the changes are taken into account.

Standalone mode - application-standalone.yml update

Locate and edit the following file:

 %PROGRAMDATA%\CAST\AIP-Console-Standalone\application-standalone.yml

In this file locate the following entries:

# Dashboard integration configuration
dashboards:
	url: http://localhost:8087
	integrationKey: CRYPTED2:0352F19CC37A1694DF51131A05A350FC
	userName: admin

The existing url entry (http://localhost:8087) assumes that the embedded Dashboard service is installed on the same host as Console. As this is not the case, update the URL to match the host/port on which the embedded Dashboard service has been installed, for example:

# Dashboard integration configuration
dashboards:
	url: http://my_dashboard_host:8087
	integrationKey: CRYPTED2:0352F19CC37A1694DF51131A05A350FC
	userName: admin

Now restart all front-end Console services and the embedded Dashboard service to ensure that the changes are taken into account.

Step 4 - Console configuration

Login to Console with a user account that already has the Admin role and switch to the Admin Center:

Now move to the System Settings panel:

Open the Dashboard Integration settings panel (Administration Center - Settings - Dashboard Integration) and click the Synchronize button - this will ensure that all settings are correct and that any additional CAST Storage Service/PostgreSQL instances (in addition to the instance configured in the installer) are correctly referenced:

It is not necessary to click this button when a new CAST Storage Service/PostgreSQL instance is added into Console via the Administration Center - Settings - CSS and Measurement settings panel after the installation of the integrated RestAPI is complete. Details of applications stored on new CAST Storage Service/PostgreSQL instances will be automatically added when a snapshot is completed.

Step 5 - Test the configuration

In Console, click either of the dashboard icons to check that you can access the dashboards:

Note that the Health Dashboard and Engineering Dashboard options will be disabled if no Measurement schema exists and no application schemas exist.

What is installed?

Files

All files are installed to the following locations unless you choose custom installation folders:

%PROGRAMFILES%\CAST\Dashboards\Console-HDED
%PROGRAMDATA%\CAST\Dashboards\Console-HDED
or
%PROGRAMDATA%\CAST\Dashboards\Console-EE-HDED
%PROGRAMFILES%\CAST\Dashboards\Console-EE-HDED

/root/CAST/Dashboards/Console-HDED
/root/ProgramData/CAST/Dashboards/Console-HDED
or
/root/CAST/Dashboards/Console-EE-HDED
/root/ProgramData/CAST/Dashboards/Console-EE-HDED

Microsoft Windows service

On Microsoft Windows, an optional service can be created during the installation to allow you to stop/start the service as required. This service will be available in the services control panel:

Startup/shutdown scripts

Startup and shutdown scripts are available if you do not want to use a Windows Service or systemd (or equivalent) on Linux:

%PROGRAMFILES%\CAST\Dashboards\<folder\startup.bat
%PROGRAMFILES%\CAST\Dashboards\<folder\shutdown.bat

/root/ProgramData/CAST/Dashboards/Console-HDED\startup.sh
/root/ProgramData/CAST/Dashboards/Console-HDED\shutdown.sh
Note that you may need to run "chmod +x <file>.sh" to grant execution permission to the scripts before running them.
You may also need to run this file with elevated permissions (e.g. sudo) using the following syntax "./<file>.sh"

Uninstaller

An uninstaller is provided:

Via the Add/remove programs entry - Microsoft Windows only

The executable JAR file will create an entry in the Microsoft Windows registry. This entry means that the install will be listed in the Microsoft Windows Add/remove programs control panel:

Click the entry and choose Uninstall:

The uninstaller will then launch - choose the "Force deletion" option if you want to fully remove the install folders, then click Uninstall.

This uninstaller will not remove the data folder specified in %PROGRAMDATA%\CAST\Dashboards\Console-HDED / %PROGRAMDATA%\CAST\Dashboards\Console-EE-HDED or in /root/ProgramData/CAST/Dashboards/Console-HDED /  /root/ProgramData/CAST/Dashboards/Console-EE-HDED.

Executing the uninstaller.jar file

Another method is to execute the uninstaller directly. You can find the uninstaller in the following location:

%PROGRAMFILES%\CAST\Dashboards\Console-HDED\uninstaller.jar
or
%PROGRAMFILES%\CAST\Dashboards\Console-EE-HDED\uninstaller.jar

/root/CAST/Dashboards/Console-HDED/uninstaller.jar
or
/root/CAST/Dashboards/Console-EE-HDED/uninstaller.jar

You can either double click the file (in UI mode) or run it from the command line:

java -jar uninstaller.jar -c
  • No labels