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

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:

(tick)

Ensure you have read all Release Notes accompanying CAST products for any last-minute information.

(tick)

Decide where the CAST RestAPI will be installed.

(tick)

Ensure that your user login on the target machine has sufficient user privileges to install applications.

(tick)

Make sure you have the required .JAR file ready for deployment.

Installation procedure

The installation process is divided into various steps:

Step 1Start the installer
Step 2Work through the installer steps
Step 3Start the dashboard and test connection
Step 4First login and become admin
Step 5Install the license key
Step 6Configure roles
Step 7Generate snapshot data
Step 8Configure 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 modeDouble 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 portEnter 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 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 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:

OptionDescription
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.

ModeDescription
Authentication using local configuration

This mode relies on simple username/password authentication defined in a local configuration file within the web application:

By default the credentials admin/admin will be pre-filled. This is to create one initial user with which you can login to the web interface and then create additional users. You are free to change the credentials if you require.

Authentication using LDAP

This mode allows authentication with a standard LDAP server. All fields are mandatory:

Example configuration:

LDAP server url

ldap://directory.example.com/

Ensure that you use a URL starting with ldap:// or ldaps://.
Account dn

cn=serviceaccount,dc=example,dc=com

Account passwordpassword
User search base

dc=example,dc=com

User search filter

(&(objectClass=user)(sAMAccountName={0}))

Group search base

dc=example,dc=com

Group search filter(&(objectClass=group)(member={0}))
Authentication using SAML

This mode allows authentication with a SAML login:

Please see User authentication for more information.

  • CAST recommends using LDAP / SAML because this avoids having to manually manage individual usernames and passwords.
  • Only one mode can be active at a time.

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 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. 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"
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.

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:

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"
  • No labels