Summary: This section describes how to install and configure the standalone CAST RestAPI 1.x and 2.0 - 2.4 in ZIP file format (i.e. web application server required).
From release 2.0 onwards, CAST will deliver a ZIP file for each CAST Dashboard, alongside the traditional WAR file that has always been delivered. The ZIP 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 ZIP itself). The aim of the ZIP 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).
CAST provides the RestAPI in a dedicated ZIP file, however, it is not absolutely necessary to deploy this dedicated ZIP file to use the RestAPI, because the RestAPI is provided with all CAST dashboard ZIP files as standard. Therefore if you have already deployed a CAST dashboard, you can, if you choose, use this for RestAPI needs.
The RestAPI zip can be configured to access a Dashboard schema or a Measure schema, or both, depending on your requirements.
See Standalone dashboard - installation requirements.
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 .ZIP file ready for deployment.
The installation process is divided into various steps:
|Step 1||Unpack the ZIP file|
|Step 2||Configure the connection parameters|
|Step 3||Install the license key|
|Step 4||Install the Microsoft Windows Service to start/stop the application server - optional|
|Step 5||Start the RestAPI and test connection|
|Step 6||Configure user authentication|
|Step 7||First login and become admin - ≥ 2.1 only|
|Step 8||Configure roles|
|Step 9||Generate snapshot data|
|Step 10||Configure data authorization|
Unpack the ZIP file on the server. You can run the dashboard directly from wherever you unpack the ZIP file, however, you may want to move the unpacked files to a more appropriate location.
When the .ZIP has been deployed you now need to configure the application.properties file to tell the web application on which CAST Storage Service/PostgreSQL instance the Dashboard/Measure schemas are stored. This file is located here:
Locate the following section in the file:
If all your Dashboard/Measure schemas are located on one single CAST Storage Service/PostgreSQL instance then you need to modify the
If your Dashboard/Measure schemas are located on multiple CAST Storage Services/PostgreSQL instances, you need to add in the additional servers as shown in the example below:
Save the file before proceeding.
You now need to configure the domains.properties file which provides a link between the CAST Storage Services/PostgreSQL instances defined in the application.properties file and the Dashboard/Measure schemas containing the relevant snapshot data. This file is located here:
This file is delivered empty as shown below:
For each schema that you need to access via the RestAPI, add one line to the file ensuring that there are no empty lines:
For example, for one Dashboard schema called "MEUDON_CENTRAL" and one Measure schema called "MEUDON_MEASURE" stored in the CAST Storage Service/PostgreSQL instance defined in Resource1 in the application.properties file, add the following:
Save the file before proceeding.
Modify application.properties to define connection to CSS/PostgreSQL for the roles/permissions schema - ≥ 2.1 only
In ≥ 2.1 only, an interface exists to manage User roles - 2.x and above and Data authorization - 2.x and above - this interface stores all its records in a dedicated schema on a CAST Storage Service/PostgreSQL instance. This instance does not need to be the same as used for your AIP schemas (Dashboard/Measure schemas), however, the required schema is small and therefore CAST recommends using an existing CAST Storage Service/PostgreSQL instance to host it. The schema is created automatically when you start up your Dashboard deployment if it does not already exist.
The application.properties file contains a section dedicated to this schema - this file is located here:
Locate the following section in the file:
Change the line
Save the file before proceeding. This will ensure that a schema called "cast_dashboards" is created on the target CAST Storage Service/PostgreSQL instance when you start the web application.
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.
If you have deployed the ZIP file on Microsoft Windows and would like to control the application server via a Microsoft Windows Service, CAST provides an installation batch script to do this for you. Locate the following file:
Double click this file to start the service installation. You may be prompted to accept a UAC warning:
On completion the service will be listed as CAST Dashboard Service with a startup type set to Automatic, log on as Local System and will not be running:
To start the RestAPId:
Microsoft Windows <unpacked_zip>\startup.bat Linux <unpacked_zip>\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 RestAPI 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
You should see the Rest Client page as follows - this indicates that the initial setup was successful:
See Modify the user access port for 2.x JAR or ZIP deployments for more information about changing the default port 8080.
This step involves configuring how your users will authenticate with the CAST RestAPI. Most organizations opt for LDAP/Active Directory integration so that users can use their corporate username/password to access the resources they need. The RestAPI also has a built in username/password authentication mechanism which is enabled "out of the box". See User authentication.
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 cofiguration settings. See First login and become admin. This step is not required when using Dashboards 1.x and can be skipped.
This step involves configuring roles for users and groups that are accessing the CAST RestAPI. See User roles.
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.
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.