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

Summary: describes how to deploy and configure CAST Dashboards embedded in the AIP Console package.

Introduction

The CAST dashboards (CAST Engineering Dashboard and CAST Health Dashboard) that are provided in the AIP Console install can be linked directly to the AIP Console, so that analysis/snapshot result data can be made immediately available to end users. In addition, icons will be available in the AIP Console to provide one-click access to the dashboards - no login will be required either:

Technical information

Dashboards provided with AIP Console

The dashboards are provided in the AIP Console installation. All that is required is:

  • to deploy and configure a CAST RESTAPI war on a compliant web application host such as Apache Tomcat. The CAST-RESTAPI-integrated.war is provided in the installation media .ZIP file (alongside the .JAR installer for the AIP Console) and is partly pre-configured for use with the CAST AIP Console.
  • this RESTAPI will act as an intermediary between the AIP Console/Dashboards and the CAST Storage Service/PostgreSQL instance where the data is stored

Please ensure you are familiar with the advantages and disadvantages of using embedded dashboards:

Use standalone dashboards

Advantages
  • Can be fully customized as required
Disadvantages
  • No seamless login with AIP Console credentials - users will need to login separately with dashboard authentication
  • No dedicated icons in the AIP Console for directly accessing the required dashboards
  • Need to wait until an Application has been created in AIP Console (and therefore associated database schemas) before being able to complete the configuration process
Use dashboards embedded in the AIP Console packageAdvantages
  • Seamless login with Console credentials
  • Roles assigned in Console are active in embedded dashboards to restrict access to Application data
  • Dedicated icons in the AIP Console to directly access the required dashboard
  • Fully embedded in AIP Console processes
Disadvantages
  • Dashboard customization not currently possible
  • Dashboards cannot be manually updated to a new dashboard version independently: since the dashboards are embedded in AIP Console, updating to a new dashboard version requires updating AIP Console and all AIP Nodes to a new release which contains the required version of the dashboard

Single Sign On

The configuration process effectively creates an SSO (Single Sign On) between the AIP Console and the Engineering and Health Dashboards, therefore when logged into the AIP Console, a user can click through to either of the dashboards and no login prompt will be shown. Users are logged into the dashboards with their AIP Console user, therefore the same user rights apply in the dashboards:

  • If your user login has the global Admin role, you can see all Applications in the dashboards
  • If your user has the global Application Owner role you can see all the Applications in the dashboards that you have created in the AIP Console
  • If your user has any other role, i.e resource level Application Owner / Analysis Manager roles, then it is not currently possible to view Applications in the dashboards

Process

The deployment and configuration process is completed in various phases, each is described below:

  1. Install Apache Tomcat
  2. CAST-RESTAPI.war deployment and configuration

  3. AIP Console configuration

Phase 1 - Install Apache Tomcat

Please see http://tomcat.apache.org/ for more specific installation instructions for your specific release of Apache Tomcat.

Memory tuning

Describes how to modify the default memory settings for Apache Tomcat where Low Memory/Recovered Memory/Out of Memory errors or exceptions are seen.

 Click here to expand...

It may be necessary to modify the default memory settings for Apache Tomcat to improve the performance of the deployed RESTAPI and integrated Dashboards. For example, you may receive Low Memory/Recovered Memory/Out of Memory errors or exceptions as follows:

[WARNING]: [MEM] Low Memory: 24052448
[WARNING]: [MEM] Recovered Memory: 18348800

These errors and exceptions are displayed by the Java Virtual Machine (JVM) and they indicate that the Java Garbage Collector is in operation. As a result, you may see a slow down in performance. You can ignore these errors, however, if they persist, it is possible to modify the JVM memory configuration settings on the machine hosting the Apache Tomcat server to resolve the problem.

The procedure for modifying the JVM memory settings is dependent on how you have installed Apache Tomcat - either as a service or standalone (launched via the command line).

Installed as a Windows Service

If you have installed Apache Tomcat as a service, the process "Tomcat7.exe" or "Tomcat8.exe" will be visible in the Processes tab in Windows Task Manager. To modify the JVM memory configuration:

  • Stop the Apache Tomcat service
  • Execute the Tomcat7w.exe or Tomcat8w.exe file located at %PROGRAMFILES%\Apache Software Foundation\bin or your equivalent installation location
  • Select the Java tab as shown below:

  • Alter (or add) memory configuration settings as follows: Initial memory pool = 512MB, Maximum memory pool = 512MB (these are the absolute minimum values that CAST recommends - you should increase these values until your low memory/out of memory exceptions have been resolved).
  • Click Apply and then OK to confirm the modification to the JVM memory settings
  • Restart Tomcat to use the new settings

Installed as a standalone program

If Apache Tomcat is installed as a standalone program and is launched from the command line, CAST recommends using a wrapper script file with the following parameter line:

set CATALINA_OPTS=-Xms512m -Xmx512m

This will set the JVM memory configuration settings as follows: - Initial memory pool = 512MB, - Maximum memory pool = 512MB (these are the absolute minimum values that CAST recommends - you should increase these values until your low memory/out of memory exceptions have been resolved). An example wrapper script for Microsoft Windows to launch Apache Tomcat with the above configuration is shown below (modify to suit your own environment):

@echo off
if "%OS%" == "Windows_NT" setlocal
set JAVA_HOME=C:\Java\jdk1.8.0_06
set PATH=C:\Java\jdk1.8.0_06\bin;%PATH%
set CATALINA_HOME=C:\apache-tomcat-8.5.38
set CATALINA_OPTS=-Xms512m -Xmx512m
rem launch Tomcat standard startup.bat
call startup.bat
:end

Phase 2 - CAST-RESTAPI-integrated.war deployment and configuration

Step 1 - Deploy the WAR file

 Click here to expand...

The CAST-RESTAPI-integrated.war file is provided in the installation media .ZIP file (alongside the .JAR installer for the AIP Console) and is partly pre-configured for use with the CAST AIP Console. Locate the CAST-RESTAPI-integrated.war file and move it to the web application installation location. By default on Apache Tomcat this is set to:

CATALINA_HOME\webapps

If the Apache Tomcat server is running, the .WAR file will then be unpacked and deployed in a folder called "CAST-RESTAPI-integrated". If the Apache Tomcat server is not running then you can manually deploy the war file by unzipping it and copying the contents into the location shown above.

Step 2 - Ensure license.key is in place

 Click here to expand...

Access to data in the CAST Dashboard Service schema  (i.e. for use by the CAST Engineering Dashboard) is governed by a license key - see Dashboard Service license key configuration. You must have a valid license key in your possession before you begin. The license key should be deployed here:

CATALINA_HOME\webapps\CAST-RESTAPI-integrated\WEB-INF\license.key
Note that if you are using a RESTRICTED license.key file, then you must configure Data authorization for any user defined in AIP Console that wishes to consult an embedded dashboard. See Dashboard Service license key configuration.

Step 3 - Configure connection details in context.xml

 Click here to expand...

Open the following file with a text editor - this file defines the connection between the CAST-RESTAPI and the CAST Storage Service / PostgreSQL instance on which the required CAST AIP schemas are stored:

CATALINA_HOME\webapps\CAST-RESTAPI-integrated\META-INF\context.xml

Find the uncommented section for a "resource" entry as shown in the example below:

<Resource name="jdbc/domains/Resource1" url="jdbc:postgresql://localhost:2282/postgres"
	username="operator" password="CastAIP"

	auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
	validationQuery="select 1"
	initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>

One single CAST Storage Service / PostgreSQL instance

If you are using one single CAST Storage Service / PostgreSQL instance for ALL AIP Nodes and for the Measurement Service schema, enter the configuration details for the CAST Storage Service / PostgreSQL instance, for example, change jdbc:postgresql://localhost:2282/postgres to jdbc:postgresql://MY_SERVER:2282/postgres (to suit your environment). Save the file when complete.

<Resource name="jdbc/domains/Resource1" url="jdbc:postgresql://MY_SERVER:2282/postgres"
	username="operator" password="CastAIP"

	auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
	validationQuery="select 1"
	initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>


Multiple CAST Storage Services  / PostgreSQL instances

If you are using multiple CAST Storage Services  / PostgreSQL instances (for example one for the Measurement Service schema and one for the all AIP Nodes - see Measurement Settings in Administration Center - Settings - Measurement), then you will need to add two unique "resource" elements, one for each CAST Storage Service / PostgreSQL instance. For example, create <Resource1> and <Resource2> entries. Save the file when complete.

<Resource name="jdbc/domains/Resource1" url="jdbc:postgresql://MY_SERVER_1:2282/postgres"
	username="operator" password="CastAIP"

	auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
	validationQuery="select 1"
	initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>

<Resource name="jdbc/domains/Resource2" url="jdbc:postgresql://MY_SERVER_2:2282/postgres"
	username="operator" password="CastAIP"

	auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
	validationQuery="select 1"
	initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>
Note that in the case of multiple CAST Storage Service/PostgreSQL instances, the AIP Console will dynamically discover the correct resource entry for the CAST Storage Service/PostgreSQL instance hosting the Dashboard schemas.

Step 4 - Configure domains.properties for the Measurement Service schema

 Click here to expand...

Open the following file with a text editor - this file defines the connection between the RESTAPI and the CAST Storage Service/PostgreSQL on which the Measurement Service schema is stored:

CATALINA_HOME\webapps\CAST-RESTAPI-integrated\WEB-INF\domains.properties

One uncommented line will exist as follows - if you have defined one single CAST Storage Service/PostgreSQL instance in the context.xml file and you are using the default settings for the Measurement Service schema (see Administration Center - Settings - Measurement), then you do not need to make any changes here:

AAD=Resource1,general_measure

Otherwise make changes as follows:

  • AAD refers to the Measurement Service schema. This entry must always start with AAD.
  • Resource1 refers to the name attribute used in the <resource> tag in the context.xml file - see Step 3 above. This identifies the CAST Storage Service/PostgreSQL connection parameters (as defined in the context.xml file) specifically for the Measurement Service schema.
  • general_measure is the name of the Measurement Service schema you are using with the CAST AIP Console (this is the default name for this schema as defined in Administration Center - Settings - Measurement).

Step 5 - Restart the CAST-RESTAPI

 Click here to expand...

Restart either the CAST-RESTAPI-integrated web application or Apache Tomcat to ensure that the changes are taken into account.

Phase 3 - AIP Console configuration

 Click here to expand...

Login to the AIP Console with a user account that already has the Admin role and switch to the Admin Center:

Now move to the System Settings panel:

Open the Dashboard Integration settings panel and fill in as explained in Administration Center - Settings - Dashboard Integration:

Save the file and then restart the AIP Console to ensure that the changes are taken into account.

Test the configuration

In the CAST AIP Console, click either of the dashboard icons to check that you can access the dashboards:

Notes

Declaring a new AIP Node in AIP Console when the embedded Dashboards have already been configured requires that you save the Dashboard Integration settings to ensure any snapshots generated with the AIP Node before it was declared are made available in the dashboards.

  • No labels