Created by James Hurrell, last modified on Apr 28, 2022

Summary: describes how to deploy and configure CAST Dashboards embedded in the AIP Console package using a WAR file (AIP Console ≤ 1.24). For more recent releases, see Embedded CAST Dashboard deployment process using ZIP file.

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 - optional

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

Apache Tomcat installed as a Windows Service

If you have installed Apache Tomcat as a service, the process "Tomcat<version>.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 Tomcat<version>w.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 deployment and configuration

Step 1 - Deploy the CAST RESTAPI

You must always use the CAST-RESTAPI-integrated.war file provided with the current release of AIP Console.

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

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 UNRESTRICTED 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 RESTRICTED license.key files are NOT supported.

Step 3 - Configure connection details

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.

initialSize, maxTotal, maxIdle and  maxWaitMillis

The following options are used to govern the connections from the web application to the target CAST Storage Service/PostgreSQL instance:

initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1"

CAST recommends using the default options unless you are experiencing performance issues. The options are used as follows:

initialSize

(int) The initial number of connections that are created when the pool is started. Default value is 5.

maxTotal(int) The maximum number of active connections that can be allocated from this pool at the same time. The default value is 20.  
maxIdle

(int) The maximum number of connections that should be kept in the pool at all times. Default value is 10.  Idle connections are checked periodically (if enabled).

maxWaitMillis

(int) The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception. Default value is -1 (i.e. the pool will wait indefinitely).

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

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 previous step 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. Do not change this.
  • 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 AIP Console (this is the default name for this schema as defined in Administration Center - Settings - Measurement). If you are using a different name, then please update it here.

Step 5 - Restart/start the CAST RESTAPI

Restart or start up (if it is not already running) either the web application or Apache Tomcat to ensure that the changes are taken into account. The access port number required by AIP Console will be determined by the port used by your Apache Tomcat instance - by default this is 8080.

Phase 3 - AIP Console configuration

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.