- Introduction
- Requirements
- Pre-installation check list
- Installation procedure
- Step 1 - Start the installer
- Step 2 - Work through the installer steps
- Step 3 - Start the dashboard and test connection
- Step 4 - First login and become admin
- Step 5 - Configure roles
- Step 6 - Upload snapshot data for display in Health Dashboard
- Step 7 - Configure data authorization
- Step 8 - Configure access to the Engineering Dashboard and from the Health Dashboard
- What is installed?
- Additional information
Introduction
What is the JAR file format?
From release 2.5 onwards, CAST will deliver an executable JAR file for each CAST Dashboard, alongside the traditional WAR file that has always been delivered. The executable JAR file is a new method of deploying the CAST Dashboards based on Spring Boot and does not require a web application server (the application server is embedded in the JAR itself). In addition, the JAR file contains an interactive installer which will guide you through some of the deployment requirements. The aim of the JAR file releases is to simplify and speed up the deployment of the CAST Dashboards. The deployment and configuration of the Spring Boot based dashboards differs slightly to the steps required for traditional WAR files (see Standalone Health Dashboard deployment using WAR file).
How many Health Dashboards do I need?
CAST highly recommends that you install one Health Dashboard to display snapshot data from all your Applications whether they are stored in one or multiple Dashboard schemas. When configuring the Health Dashboard, you should therefore:
- Configure a connection to one single Measurement schema
- Consolidate data from all your Dashboard schemas in this single Measurement schema
Note that:
- the Health Dashboard can officially support the upload of a maximum of 200 applications. CAST recommends that you choose only the most critical applications from the business view point - i.e the applications that need to be monitored with high visibility by CIOs and managers. If you need to upload more than 200 applications, please see Configure the Health Dashboard for large numbers of Applications (this information is equally valid for uploading below 200 Applications).
- "authorizations" can help separate Application data if you have users that are only authorised to access data from specific Applications - Data authorization.
Standalone or combined JAR file?
CAST provides the Health Dashboard in a JAR as follows:
| JAR file name | Description |
|---|---|
| com.castsoftware.aip.dashboard.health.<version>.JAR | Traditional "standalone" JAR file containing only the Health Dashboard. This document describes the installation using this JAR file. |
| com.castsoftware.aip.dashboard.<version>.JAR | "Combined" JAR file containing both the Health Dashboard and the Engineering Dashboard. |
You are free to use whichever JAR file you prefer to deploy the Health Dashboard (the requirements and prerequisites are identical for both JAR files), however if you are using both the CAST Health and Engineering Dashboard, to fulfil (for example) a "risk and quality" use case, then it would make sense to take advantage of the combined com.castsoftware.aip.dashboard.<version>.JAR file and deploy both dashboards from the same JAR file. If you do so, please note the following about using the "combined" JAR file:
- There is no need to specifically configure a URL for your Engineering Dashboard drilldown (via the "microscope" icon) - when using the combined "JAR" file, access to the Engineering Dashboard from the Health Dashboard is pre-configured.
- Security access and authentication is common to both Dashboards. Therefore, if you setup Active Directory authentication, then this must be used to access both Dashboards - you cannot use "Default Authentication" for one Dashboard and "Active Directory" for the other.
- Role configuration is common to both Dashboards. Therefore "UserA" that has been granted the "admin" role, will have the "admin" role in both Dashboards.
- Data authorization is common to both Dashboards. Therefore if you authorize "UserA" to view Application "B" only via the authorizations.xml file, then this is true for both Dashboards. Note that authorizations based only on Tags and Categories created for the Health Dashboard (Tags and Categories are a feature that is not available in the Engineering Dashboard) WILL be applied in the Engineering Dashboard when using the combined JAR file.
- Group configuration is common to both Dashboards, regardless of the authentication mode in use. Therefore if you authorize "GroupD" to view Application "E" only, then this is true for both Dashboards.
- On login, the user will be presented with a choice of Dashboard as shown below (Image 1) in a "Welcome" page. Clicking Access will take the user to the custom login screen for the chosen Dashboard where a "Return to welcome page" URL is available if the user wishes to login to the other Dashboard (Image 2):
Image 1 - Welcome page
Image 2 - Return to welcome page URL
Requirements
See Standalone dashboard - installation requirements.
Pre-installation check list
Before beginning the installation process, please ensure that you have carried out all of the following tasks and that the following requirements have been met:
| Ensure you have read all Release Notes accompanying CAST products for any last-minute information. |
| Decide where the Health Dashboard will be installed. |
| Ensure that your user login on the target machine has sufficient user privileges to install applications. |
| Make sure you have the required .JAR file ready for deployment |
Installation procedure
The installation process is divided into various steps:
| Step 1 | Start the installer |
|---|---|
| Step 2 | Work through the installer steps |
| Step 3 | Start the dashboard and test connection |
| Step 4 | First login and become admin |
| Step 5 | Configure roles |
| Step 6 | Upload snapshot data for display in Health Dashboard |
| Step 7 | Configure data authorization |
| Step 8 | Configure access to the Engineering Dashboard and from the Health Dashboard |
Step 1 - Start the installer
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 mode | Double click the file to start the installer. |
|---|---|
| CLI mode | Run the following command (change <cast_dashboard> to the name of the JAR file you are executing): java -jar <cast_dashboard>.jar -console |
To run the installer local Administrator privileges are required on Microsoft Windows and elevated privileges are required on Linux.
Step 2 - Work through the installer steps
UI mode
You may be prompted to accept a UAC warning, if so, click Yes:
Screen 1
The installation wizard will be displayed:
- If the wizard cannot locate a previous installation in the default installation location, %PROGRAMFILES%\CAST\Dashboards (Windows), /root/CAST/Dashboards (Linux) 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.
Screen 2
Choose a location on the local machine that will be used for the CAST Dashboard installation. The setup will suggest: %PROGRAMFILES%\CAST\Dashboards (Windows) and /root/CAST/Dashboards (Linux) but you are free to choose a different location. The package will be installed in a sub-folder (e.g. HD for Health Dashboard or EDHD for a combined installation). If the folder does not already exist, the installation wizard will create it.
Screen 3
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 but you are free to choose a different location. The data will be installed in a sub-folder (e.g. HD for Health Dashboard or EDHD for a combined installation).
- On a Linux operating system, the installer will suggest: /root/ProgramData/CAST/Dashboards but you are free to choose a different location. The data will be installed in a sub-folder (e.g. HD for Health Dashboard or EDHD for a combined installation).
Screen 4
Now fill in the CAST Storage Service/PostgreSQL information to define where you Measurement schema is located:
| CSS/PostgreSQL configuration | Database host and port | Enter the hostname/IP address and port number of the CAST Storage Service/PostgreSQL instance on which your Measurement schema is stored. The field will be pre-filled with localhost:2282, which assumes a CAST Storage Service 3 installed on the local server. |
|---|---|---|
| Database name | The 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 username | Enter 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/CastAIP. These credentials will be encrypted before being stored in the application.properties file. | |
| Database password | ||
| Schema name(s) | Measurement schema (Health Dashboard) | Enter the name of your target Application's Measurement schema. You can find this using AIP Console:
|
Screen 5
Now fill in the server port and choose your authentication mode:
| Option | Description | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Server configuration - port | This port will be pre-filled with 8080. This is the port number which end-users will use to communicate with the Dashboard in their browsers. If the port is already being used by another service, you can choose another custom port (for example port 80). If you would like to use a secure https port, please choose a non-secure port for the initial installation process and then change it post installation - see Modify the user access port or set up secure HTTPS dashboard access. | |||||||||||||||||||||||
| Dashboard security configuration | In order for end-users to connect to the Dashboard, they must authenticate first. The Dashboard package therefore offers various authentication methods, each of which can be configured in this screen. You can change the authentication method at any time - see User authentication.
| |||||||||||||||||||||||
Screen 6
Fill in the information that is required by the Dashboard package if you would like to install the Dashboard with a Windows Service. This step is NOT displayed when running the installation wizard on a Linux operating system. Click Next to continue:
| Windows Service | Install 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. See Apache Tomcat performance considerations for information about memory requirements.
- Initial memory pool = 256MB
- Maximum memory pool = 1024MB
Screen 7
Choose whether to create shortcut icons and Start menu entries for the Dashboard package:
Screen 8
The installation process will start. Click Next when complete:
Screen 9
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 3 - Start the dashboard and test connection
To start the dashboard:
- 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\<dashboard>\startup.bat Linux /root/CAST/Dashboards/<dashboard>/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"
By default the dashboard is configured to run on port 8080. Use the following URL - where <server_name> is equal to the host name of the current server to access the dashboard. If you are testing on the server itself, you can use http://localhost:8080:
http://<server_name>:8080
You should see the login page as follows - this indicates that the initial setup was successful:
- Error messages are documented in Error Messages.
- See Modify the user access port or set up secure HTTPS dashboard access for more information about changing the default port 8080.
Step 4 - First login and become admin
By default, the CAST Dashboard requires that at least one user is granted the ADMIN role following the first login after the User authentication configuration. This ensures that one user can access all data and configuration settings. See First login and become admin.
This action must be completed from the same machine where the Dashboard is deployed, i.e. using the URL http://localhost. This is a security mechanism and attempting this action from another host on the network will fail. Note that when using SAML authentication mode, the requirement to perform this action using the URL http://localhost is removed and can be performed from any machine.
Step 5 - Configure roles
This step involves configuring roles for users and groups that are accessing the CAST Health Dashboard. See User roles.
Step 6 - Upload snapshot data for display in Health Dashboard
Before your users can view any data in the Health Dashboard, you need to upload your snapshot data to the Measurement schema once it has been generated. The snapshot upload is achieved using AIP Console.
- The Health Dashboard can officially support the upload of a maximum of 200 applications. CAST recommends that you choose only the most critical applications from the business view point - i.e the applications that need to be monitored with high visibility by CIOs and managers.
- The Health Dashboard features a server cache to improve the speed of data display. This does mean, however, that very recent changes in data (i.e. a new snapshot generation) may not instantly appear in the dashboard. If this is the case, the server cache needs to be manually reloaded. See Reload the cache.
When using AIP Console, the Measurement schema is automatically activated for all your Application analyses on all AIP Nodes (only one Measurement schema can be managed per AIP Console instance). When you run an analysis or snapshot, you can choose to upload the results immediately to the Measurement schema:
You can also manually upload snapshots using the Application - Snapshots interface:
Step 7 - Configure data authorization
An Authorization defines permission to access and "consume the data" in a specific Application or group of Applications via the CAST Health Dashboard. If permission is not granted, or a "restriction" is used, then any information related to this Application will be not accessible: application properties such as name, technologies or grades and measures, etc. Therefore, an Authorization must be defined before a user/group of users can access a specific application. See Data authorization.
Step 8 - Configure access to the Engineering Dashboard and from the Health Dashboard
The Health Dashboard enables users (via the "microscope" icon) to access directly the underlying data in the Dashboard schema via the Engineering Dashboard. The Engineering Dashboard provides detailed information about the top level data displayed in the Health Dashboard. This configuration is license dependent.
Access to the underlying data is provided via a URL (pointing to the required dashboard) that is stored in the Measurement schema.
Combined JAR file
If you have deployed the Health Dashboard and Engineering Dashboard from the combined Health/Engineering .JAR file, access to the Engineering Dashboard is implemented automatically. You do not need to do anything further.
- automatic access is only implemented for each Dashboard schema that is configured for viewing in the Engineering Dashboard. So if you have consolidated data from a Dashboard schema into a Measurement schema for viewing in the Health Dashboard, but you have not declared this Dashboard schema in the Engineering Dashboard configuration, then the automatic access will not function and users will be notified that access is not yet configured.
- automatic access cannot be overridden to point to a separate Engineering Dashboard deployment.
Standalone JAR files
If you have deployed the Health Dashboard and Engineering Dashboard using the standalone Health / Engineering .JAR files, then access to the Engineering Dashboard (ED) is not implemented automatically and you will need to proceed as follows:
Note that:
- you will need to repeat this action for EACH Dashboard schema (the CAST AIP schema used by the Engineering Dashboard) that you want your users to be able to drill down to.
- you may need a specific license that enables access to the Engineering Dashboard before this feature will function in the Health Dashboard.
- you must have already generated a snapshot and uploaded snapshot data to the Measurement schema before you attempt this
- the separate standalone JAR files must all originate from the SAME release. Using JAR files from different releases is not supported.
- For each Dashboard schema that you want to drill down into, you must first determine the context "name" of the Dashboard schema as defined in the context.xml file for the Engineering Dashboard.
- First locate and open the following file in an editor:
%PROGRAMDATA%\CAST\Dashboards\<dashboard>\domains.properties
Locate the domain name (the first entry in each row) that corresponds to the Dashboard schema you need your users to drill down into and take note of it. In this example we want users to drill down to V80_CENTRAL_APP1 which corresponds to the domain APP1:
# Domains for ED # empty lines in this file lead to connection error, remove all empty lines # - You have to align [Resource1] with the resource name configured in application.properties # - You have to replace [Central Schema1] by the central schema name # - Domains names must be unique # AED1=Resource1,[Central Schema1] # AED2=Resource1,[Central Schema2] APP1=Resource1,V80_CENTRAL_APP1 APP2=Resource1,SEVRES_CENTRAL APP3=Resource2,PARIS_CENTRAL
Open the CAST Management Studio and move to the Services view. Double click the corresponding Dashboard Service to open its editor (i.e the V80_CENTRAL_APP1 in this example):
- Enter the URL to your Engineering Dashboard. This will take the following form http://<server>:<port>/engineering/index.html#<context-name> - you should tailor the <server> and <port> entries to your environment. The <context-name> value refers the value we determined earlier, in this example APP1. So we will add the following URL: http://TOMCAT:8080/engineering/index.html#APP1
- Click the Add URL to Measurement Service
- Restart your application server so that the changes are taken into account.
- Now users can drill down into the Engineering Dashboard.
What is installed?
Files
All files are installed to the following locations unless you choose custom installation folders:
%PROGRAMFILES%\CAST\Dashboards\<dashboard> %PROGRAMDATA%\CAST\Dashboards\<dashboard> /root/CAST/Dashboards/<dashboard> /root/ProgramData/CAST/Dashboards/<dashboard>
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\<dashboard>\startup.bat /root/ProgramData/CAST/Dashboards/<dashboard>\startup.sh /root/ProgramData/CAST/Dashboards/<dashboard>\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 - see Standalone dashboard - uninstaller for JAR deployments.
Additional information
Advanced configuration specific to the CAST Health Dashboard:
Additional advanced configuration options:
