- Introduction
- Requirements
- Pre-installation check list
- Installation procedure
- 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 an alternative 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 Engineering Dashboard deployment using WAR file).
How many Engineering Dashboards do I need?
CAST highly recommends that you install one Engineering Dashboard and consolidate all your CAST Dashboard Services schemas into this.
Standalone or combined JAR file?
CAST provides the Engineering Dashboard in two JAR files as follows:
JAR file name | Description |
|---|---|
| com.castsoftware.aip.dashboard.engineering.<version>.jar | Traditional "standalone" JAR file containing only the Engineering Dashboard. This document describes the installation using this JAR file. |
| com.castsoftware.aip.dashboard.<version>.jar | "Combined" JAR file containing both the Engineering Dashboard and the Health Dashboard. |
You are free to use whichever JAR file you prefer to deploy the Engineering Dashboard (the requirements and prerequisites are identical), however if you are using both the Health Dashboard 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) from the Health Dashboard - 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 war 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 Engineering Dashboard will be installed and run from. |
| 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 | Install the license key |
| Step 6 | Configure roles |
| Step 7 | Generate snapshot data for display |
| Step 8 | Configure data authorization |
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. ED for Engineering 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. ED for Engineering 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. ED for Engineering Dashboard or EDHD for a combined installation).
Screen 4
Now fill in the CAST Storage Service/PostgreSQL information to define where you Application schema(s) are located:
Note that the installer will only allow the configuration of one single CAST Storage Service/PostgreSQL instance and one single Dashboard/Central schema. If you need to define additional CAST Storage Service/PostgreSQL instances, e.g. you need to define multiple Dashboard/Central schemas located on multiple CAST Storage Service/PostgreSQL instances, please see Configure additional Dashboard schemas for JAR file deployments.
| 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 Application schemas are 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) | Central schema (Engineering Dashboard) | Enter the name of your target Application's Central (i.e. Dashboard) 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 (and it is not already running)
- 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 - Install the license key
As explained in Dashboard Service license key configuration, when you want to access a Dashboard schema using the CAST RestAPI (i.e. via the Engineering Dashboard, or via the CAST Report Generator), a special license key is required. This license key grants specific access to one or multiple Dashboard schemas for the web application in which it is installed (i.e. the Engineering Dashboard or the CAST RestAPI).
You must therefore install the license key and, if you are using a restricted license key, define data access authorization. These two steps are explained in Dashboard Service license key configuration in the sections How do I install a license key? and How to authorize users when using a RESTRICTED license key.
Step 6 - Configure roles
This step involves configuring roles for users and groups that are accessing the CAST Engineering Dashboard. See User roles.
Step 7 - Generate snapshot data for display
Before your users can "consume" data via the CAST Engineering Dashboard, you need to generate snapshot data.
Step 8 - Configure data authorization
An Authorization defines permission to access and "consume the data" in a specific Application or group of Applications via the CAST Engineering 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.
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 Engineering Dashboard:
Additional advanced configuration options:
