- Introduction
- Requirements
- Pre-installation check list
- Installation procedure
- What is installed?
Summary: This section describes how to install and configure the standalone CAST RestAPI ≥ 2.5 in JAR file format (i.e. no web application server required).
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 RestAPI deployment using WAR file).
Dedicated JAR file or re-use a CAST dashboard?
CAST provides the RestAPI in a dedicated JAR file, however, it is not absolutely necessary to deploy this dedicated JAR file to use the RestAPI, because the RestAPI is provided with all CAST dashboard JAR files as standard. Therefore if you have already deployed a CAST dashboard, you can, if you choose, use this for RestAPI needs.
Dashboard or Measure schema?
The RestAPI JAR can be configured to access a Dashboard schema or a Measure schema, or both, depending on your requirements.
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 CAST RestAPI 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 | Install the license key |
| Step 6 | Configure roles |
| Step 7 | Generate snapshot data |
| 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 upgrade 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 installation. The setup will suggest: %PROGRAMFILES%\CAST\Dashboards\API (Windows) and /root/CAST/Dashboards/API (Linux) but you are free to choose a different location. If the folder does not already exist, the installation wizard will create it.
Screen 3
Choose a location for your "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\API but you are free to choose a different location.
- On a Linux operating system, the installer will suggest: /root/ProgramData/CAST/Dashboards/API but you are free to choose a different location.
Screen 4
Now fill in the CAST Storage Service/PostgreSQL information to define where you Measurement / Dashboard (central) schemas 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 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:
|
| Cental 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 RestAPI 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 for 2.x JAR or ZIP deployments. | |||||||||||||||||||||||
| Dashboard security configuration | In order for end-users to connect to the RestAPI, they must authenticate first. The 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 if you would like to install the RestAPI 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 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\API\startup.bat Linux /root/CAST/Dashboards/API/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 RestAPI. If you are testing on the server itself, you can use http://localhost:8080:
http://<server_name>:8080
You should see the Rest Client page as follows - this indicates that the initial setup was successful:
- Error messages are documented in Error Messages.
- See Modify the user access port for 2.x JAR or ZIP deployments for more information about changing the default port 8080.
Step 4 - First login and become admin
By default, the CAST RestAPI 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 RestAPI 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 RestAPI. See User roles.
Step 7 - Generate snapshot data
Before your users can exploit data via the CAST RestAPI, you need to generate snapshot data and (if accessing a Measurement Service) ensure the snapshot data is uploaded to the Measurement schema.
Step 8 - Configure data authorization
This step involves configuring data Authorization. An authorization defines permission to a user or group of users to access and "consume the data" in a specific Application via the RestAPI. If permission is not granted 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"
