2.x - Enterprise mode - Installation of AIP Console front-end via Java JAR installers

Created by James Hurrell on Sep 26, 2023


Summary: how to perform a 2.x installation using the Java JAR installers.

Introduction

In ≥ 2.0.0-funcrel, CAST provides Java JAR installers for each required service, as part of the download media available on CAST Extend (https://extend.castsoftware.com/#/extension?id=com.castsoftware.aip.console&version=latest):

These installers are an alternative to a deployment on Docker, however, they contain some limitations/constraints and require some additional manual configuration post installation. Therefore CAST highly recommends that Docker is used for an enterprise deployment scenario wherever possible - see AIP Console - front-end installation. If you do need to use the Java JAR installers, follow the steps below.

Note that:

Limitations of the Java JAR installers

  • In the "out of the box" configuration, it is not possible to access the Console front-end remotely (i.e. from another machine on the network). It is possible to make a manual change (see Optional post-installation configuration steps below) to allow remote access, however, as already mentioned, CAST highly recommends that Docker is used for an enterprise deployment scenario wherever possible.
  • The Java JAR installers will automatically configure the required shared storage folders to use sub folders of the C:\aip-node-data path on the local machine. Therefore adding additional remote Nodes to this installation of Console will require that you share this folder path over the network, or make a manual change (see Optional post-installation configuration steps below) to change the paths to use a shared folder on the local network, however, as already mentioned, CAST highly recommends that Docker is used for an enterprise deployment scenario wherever possible.
  • The deployment steps for using embedded CAST Dashboards are complex for Console v 2.0 - 2.2 and require manual intervention as described below. For Console ≥ 2.3 a Java JAR installer exists which configures the embedded Dashboard without manual intervention - see Embedded CAST Dashboard deployment process using Java JAR installer. Note that CAST highly recommends that Docker is used for an enterprise deployment scenario wherever possible where embedded Dashboard deployment is entirely automatic.
  • The installation path for the "program data location" for the AIP-SSO service must not include any white space. The service may fail to start if the path contains any white space.

Launching the installers

The installers should all be run on one single host (although it is possible to install each service on different hosts, this is not recommended due to the additional complexity this creates). To start the installation of each Java JAR installers, double click the executable JAR file as provided with the installation media. If you are unable to execute the .JAR file, use the following command to open the JAR in GUI mode:

java -jar AIP-<component>-<version>.jar

You can run the above command in the Command Prompt window (CMD) - ensure you launch the CMD window with elevated permissions (run as administrator).

Step 1 - Run SSO/Keycloak installer - AIP-SSO-<version>.jar

This step installs the OAuth2 server (Keycloak) which provides authentication services for Console. Keycloak is a fully integrated authentication and identity management solution within CAST Console 2 Enterprise Edition, with no intermediary interface between the Enterprise Console and Keycloak. It serves as the primary authentication provider, managing user credentials, access control policies, and identity federation. Keycloak enables federated authentication by seamlessly integrating with external Identity Providers (IDPs) via industry-standard protocols such as SAML 2.0 and LDAP, ensuring compatibility with enterprise authentication infrastructures. Additionally, custom Keycloak extensions have been developed to enhance its capabilities within CAST Console 2, including API Key Management and Audit Trail Logging. Due to its deep integration and extended functionality, Keycloak cannot be replaced with alternative authentication solutions.

The installation wizard will be displayed:

Click Next to continue:

Choose a location on the local machine that will be used for the SSO service installation. The setup will suggest: %PROGRAMFILES%\CAST\AIP-SSO but you are free to choose a different location. If the folder does not already exist, the installation wizard will create it. Click Next to continue:

Choose a location for your SSO service "data" - this location will contain items such as logs. The setup will suggest: %PROGRAMDATA%\CAST\AIP-SSO but you are free to choose a different location (note that this path must not include any white space - services may fail to start if the path contains any white space). The installation wizard will set Full Access permissions on these folders to all authenticated users. Click Next to continue:

Fill in the information that is required by the AIP SSO service with regard to the port used for the service, admin user and CAST Storage Service/PostgreSQL options. A CAST Storage Service/PostgreSQL instance is required to store the SSO/Keycloak authentication data. Click Next to continue.

OptionDescription
Server port

The port will be pre-filled with 8086. If the port is already being used by another service, you can choose another custom port.

Admin userThe user to login to the SSO administration console - by default, this will be prefilled with admin. These credentials are specific to SSO/Keycloak and not Console.
Admin passwordAdmin user password to login to the SSO administration console - by default, this will be prefilled with admin. These credentials are specific to SSO/Keycloak and not Console.
Database connection


Host

Enter the hostname/IP address and port number of the CAST Storage Service/PostgreSQL instance that this SSO will use. The field will be pre-filled with localhost:2282, which assumes a CAST Storage Service is installed on the local server.

User

Enter the credentials for the CAST Storage Service/PostgreSQL configured in the Database host field. The login and password fields will be pre-filled with the default credentials: operator/CastAIP.

Password
Database name

The database name on your target CAST Storage Service/PostgreSQL instance. The field will be pre-filled with "keycloak" and this database must exist already. CAST highly recommends using a dedicated database instead of the default "postgres" database specifically for the SSO/Keycloak service - this is because the tables required by the SSO/Keycloak service are created by default in the system default "public" schema.

The credentials you specify MUST have full read/write access rights to the database you specify.

Fill in the information that is required by the SSO service with regard to the Windows Service. You are not obliged to install the service as a Windows Service: if you choose not to, you will need to start the service using a provided batch file (shortcuts to this batch file can be created in the following step). Click Next to continue:

OptionDescription
Install as a Windows Service

When ticked (default position), this option will install the package as a Windows Service so that you can more easily stop and start the package.

Note that the service will be set to start automatically and will be running unless you have specifically disabled this option (see below).

Start the service after installation

When ticked (default position) the Windows Service will be started after it is installed (recommended).

Log on as

By default, this option is ticked, therefore you should fill in Service User account credentials that will be used to run the service:

If you untick the option, 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:

CAST highly recommends that the Local System account is not used to run the Windows Service. For example, you can use a specific "service account" that is created specifically for this purpose.

Choose whether to create shortcut icons and Start menu entries for the SSO service. The installation will start when you click Next:

The installation process will start. Click Next when complete:

The installation process is complete:

Step 2 - Run Service Registry installer - AIP-Service-Registry-<version>.jar

This step installs the Service Registry - this service registers the Nodes (and other required services) and monitors their health.

The installation wizard will be displayed:

Click Next to continue:

Choose a location on the local machine that will be used for the Service Registry service installation. The setup will suggest: %PROGRAMFILES%\CAST\AIP-Service-Registry but you are free to choose a different location. If the folder does not already exist, the installation wizard will create it. Click Next to continue:

Choose a location for your Service Registry service "data" - this location will contain items such as logs. The setup will suggest: %PROGRAMDATA%\CAST\AIP-Service-Registry but you are free to choose a different location. The installation wizard will set Full Access permissions on these folders to all authenticated users. Click Next to continue:

Configure the path to the shared network folders - CAST highly recommends that you use a shared network folder with appropriate read/write permissions, rather than a location on the local machine:

Click Next to continue:

Fill in the information that is required by the Service Registry service with regard to the port used for the service and the CAST Storage Service/PostgreSQL options. A CAST Storage Service/PostgreSQL instance is required to store two schemas:

These schemas store persistence information about the Node(s) and Console front end itself. Click Next to continue.

OptionDescription
Server port

The port will be pre-filled with 8088. If the port is already being used by another service, you can choose another custom port.

AIP SSO urlThis field will pre-filled using http://<hostname>:8086, which assumes that the AIP SSO (Keycloak) service (installed previously) is installed on the current server. In the vast majority of circumstances, you should leave this field as is.
Dashboards url

If you intend to deploy embedded Dashboards (see Embedded CAST Dashboard deployment process using Java JAR installer) you can enter the expected embedded Dashboard URL and port number here:

  • If you intend to install the embedded Dashboards on the same host as the front-end Console services, do not modify this field.
  • If you intend to install the embedded Dashboards on a different host than the front-end Console services, enter the expected URL/port here. Note that if you subsequently install the embedded Dashboards on an entirely different host or on the same host as the Console front-end service, then you can use the instructions in Embedded CAST Dashboard deployment process using Java JAR installer to manually modify the URL (see Step 3 - Additional actions where the embedded Dashboards are installed on a remote host - optional).

If you do not intend to install the embedded Dashboards or are not sure, do not modify this field.

Database connection


Host

Enter the hostname/IP address and port number of the CAST Storage Service/PostgreSQL instance that this Service Registry will use. The field will be pre-filled with hostname:2284, which assumes a CAST Storage Service installed on the current server.

User

Enter the credentials for the CAST Storage Service/PostgreSQL configured in the Database host field. The login and password fields will be pre-filled with the default credentials: operator/CastAIP.

Password
Database name

The database name on your target CAST Storage Service/PostgreSQL instance. The field will be pre-filled with postgres, but you are free to choose a different name if necessary. This database must exist already. Two schemas will be created in the database you specify:

  • aip_node
  • aip_config

The credentials you specify MUST have full read/write access rights to the database you specify.

Fill in the information that is required by the Service Registry service with regard to the Windows Service. You are not obliged to install the service as a Windows Service: if you choose not to, you will need to start the service using a provided batch file (shortcuts to this batch file can be created in the following step). Click Next to continue:

OptionDescription
Install as a Windows Service

When ticked (default position), this option will install the package as a Windows Service so that you can more easily stop and start the package.

Note that the service will be set to start automatically and will be running unless you have specifically disabled this option (see below).

Start the service after installation

When ticked (default position) the Windows Service will be started after it is installed (recommended).

Log on as

By default, this option is ticked, therefore you should fill in Service User account credentials that will be used to run the service:

If you untick the option, 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:

CAST highly recommends that the Local System account is not used to run the Windows Service. For example, you can use a specific "service account" that is created specifically for this purpose.

Choose whether to create shortcut icons and Start menu entries for the Service Registry service. The installation will start when you click Next:

The installation process will start. Click Next when complete:

The installation process is complete:

Step 3 - Run Gateway installer - AIP-Gateway-<version>.jar

This step installs the Gateway - this is the entry point to Console. It receives registered services from the Service Registry and forwards incoming requests to the required services. It also acts as a load balancer, so it can transparently handle multiple registered service instances, based on the chosen load balancing strategy.

The installation wizard will be displayed:

Click Next to continue:

Choose a location on the local machine that will be used for the Gateway service installation. The setup will suggest: %PROGRAMFILES%\CAST\AIP-Gateway but you are free to choose a different location. If the folder does not already exist, the installation wizard will create it. Click Next to continue:

Choose a location for your Gateway service "data" - this location will contain items such as logs. The setup will suggest: %PROGRAMDATA%\CAST\AIP-Gateway but you are free to choose a different location. The installation wizard will set Full Access permissions on these folders to all authenticated users. Click Next to continue:

Fill in the information that is required by the Gateway service with regard to the port used for the service. Click Next to continue:

OptionDescription
Server port

The port will be pre-filled with 8081. This is the port that the front-end Console service will run on - and which will be used by users for access. If the port is already being used by another service, you can choose another custom port.

Config server URL

Enter the URL to the Service Registry service, using the port number 8088 unless you have customized this port. In most circumstances your Service Registry will be on the same host as the gateway, therefore, you should use the default http://localhost:8088/config URL that is prefilled.

Fill in the information that is required by the Gateway service with regard to the Windows Service. You are not obliged to install the service as a Windows Service: if you choose not to, you will need to start the service using a provided batch file (shortcuts to this batch file can be created in the following step). Click Next to continue:

OptionDescription
Install as a Windows Service

When ticked (default position), this option will install the package as a Windows Service so that you can more easily stop and start the package.

Note that the service will be set to start automatically and will be running unless you have specifically disabled this option (see below).

Start the service after installation

When ticked (default position) the Windows Service will be started after it is installed (recommended).

Log on as

By default, this option is ticked, therefore you should fill in Service User account credentials that will be used to run the service:

If you untick the option, 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:

CAST highly recommends that the Local System account is not used to run the Windows Service. For example, you can use a specific "service account" that is created specifically for this purpose.

Choose whether to create shortcut icons and Start menu entries for the Gateway service. The installation will start when you click Next:

The installation process will start. Click Next when complete:

The installation process is complete:

Step 4 - Install the Node service

You should now run the Node service installer, as is the case with a standard deployment. See AIP Node service - back-end installation.

Step 5 - Initial configuration

Ensure all services are up and running

The next step is to first ensure that all services are up and running.

SSO/Keycloak%PROGRAMFILES%\CAST\AIP-SSO\opt\jboss\tools\start.bat

Service Registry

%PROGRAMFILES%\CAST\AIP-Service-Registry\tools\aip-service-registry-app.bat

Gateway

%PROGRAMFILES%\CAST\AIP-Gateway\tools\aip-gateway-app.bat

Node

%PROGRAMFILES%\CAST\AIP-Node\tools\aip-node-app.bat

All Microsoft Windows services (if you chose to install them during the installation) will be set to "Automatic" start. This means that they will automatically start up whenever the host server is started or rebooted. Note however that some services are dependent on other services, this means that it is possible that some services may fail to start if the dependent service has not yet completed its start up routine. Dependencies exist as follows:

  • SSO/Keycloak and Service Registry service require that the CAST Storage Service/PostgreSQL instance (on which the Keycloak database and the aip_config schema exists) is available
  • Gateway and Node services require that the Service Registry service is available

Assuming that all these services are installed on the same server, CAST recommends changing the "Automatic" start to "Automatic (Delayed Start)" for the Gateway and Node services. "Automatic (Delayed Start)" ensures that these services are only started 120 seconds following the start up of the server. This should give time for the SSO/Keycloak and CAST Storage Service/PostgreSQL instance to complete their start up routine:

Perform the initial configuration steps

See Initial configuration steps - v. 2.x for more information.

Step 6 - deploy Dashboards

Embedded dashboards

≥ 2.3.x

Please see the information in Embedded CAST Dashboard deployment process using Java JAR installer.

2.0.x - 2.2.x

Click here to expand...

Deploy the CAST RESTAPI

You must always use the cast-integrated-health-engineering-dashboard-<version>.zip file provided with the current release of Console.

The cast-integrated-health-engineering-dashboard-<version>.zip is provided in the installation media .ZIP file (alongside the .JAR installer for the Console). Locate the file and move it to a suitable location - it can be run from anywhere. The CAST RESTAPI is started using the following files - however, CAST recommends not starting the application at this point (it will not start properly):

<unpacked_zip>\startup.bat

Currently using a Microsoft Windows service to start/stop the RestAPI service is not currently supported.

Memory tuning - optional

If you experience Low Memory/Recovered Memory/Out of Memory errors or exceptions then you may need to tune the RAM memory allocated to the web application. When using the startup.bat script to start the web application, these scripts set the RAM memory allocated to the web application in the script itself using the Java -Xmx and -Xms parameters:

  • Initial memory pool = 256MB
  • Maximum memory pool = 1024MB

If you would like to change these values, they are located on the following lines. Save the files after making the changes. Changes are only taken into account when the web application is started/restarted:

java -jar -Xmx1024m -Xms256m cast-integrated-health-engineering-dashboard-<version>.jar

Configure the .properties files

application.properties

Locate the application.properties file and delete it:

<unpacked_zip>\configurations\application.properties

Rename the application-integratedv2.properties file to application.properties:

<unpacked_zip>\configurations\application-integratedv2.properties

Edit the application.properties file and modify the value of the configserverURL entry to match the config server URL installed previous (as described in Step 2 - Run Service Registry installer above):

configServerUrl=http://localhost:8088/config
roles.xml

Locate the roles.xml file and delete it:

<unpacked_zip>\configurations\roles.xml

Rename the roles-v2.xml file to roles.xml:

<unpacked_zip>\configurations\roles-v2.xml
datasource.properties

Finally, create a blank file called datasource.properties in the following location:

<unpacked_zip>\configurations\datasource.properties

Modify the aip_config schema

Using pgAdmin, connect to the CAST Storage Service/PostgreSQL instance on which the aip_config schema has been installed (as described in Step 2 - Run Service Registry installer above). Locate the properties table in the aip_config schema and then locate the following entries:

Click to enlarge

The Value column for each entry must be verified:

restapi.datasource[0].url

This entry should contain a jdbc URL to the CAST Storage Service/PostgreSQL instance that will be used to store the application schemas (for analysis and snapshot requirements). For example, to connect to a CAST Storage Service 4 (using port 2284) on the same machine as all the other services, use the following URL (${db.host} refers to localhost):

jdbc:postgresql://${db.host}:2284/postgres

Or to specify a remote CAST Storage Service/PostgreSQL instance running on port 2282:

jdbc:postgresql://$192.168.200.104:2282/postgres
restapi.datasource[0].usernameEnter the credentials used to connect to the CAST Storage Service/PostgreSQL instance defined in the previous row. By default this will be set to operator/CastAIP.
restapi.datasource[0].password
restapi.datasource[0].poolnameThis entry can be left as is.
domainspropertiesThis entry should be edited to state only domains.properties
datasource.file.pathThis entry should be edited to state only configurations/datasource.properties (note that by default the entry may contain configuration/datasource.properties, which will need changing).

Modify startup.bat

Edit the startup.bat file:

<unpacked_zip>\startup.bat

Locate the following line:

java -Dloader.path="${UserPathPanelVariable}" -jar -Xmx1024m -Xms256m cast-integrated-health-engineering-dashboard-<version>.jar

Change it to the following:

java -Dloader.path="${UserPathPanelVariable}" -jar -Xmx1024m -Xms256m cast-integrated-health-engineering-dashboard-<version>.jar --spring.config.import=optional:file:configurations/datasource.properties

Save the file.

Restart all services

After making the changes:

  • restart all Console related services
  • start the CAST RESTAPI using the startup.bat:
<unpacked_zip>\startup.bat

Standalone dashboards

See Standalone CAST Dashboard deployment process.

Step 7 - Configuration steps to allow remote access to Console and for the installation of remote Nodes

Only required for Console ≤ 2.5.

Click here to expand...

Out of the box, the Java JAR installers will not allow access to the Console front-end remotely (i.e. from another machine on the network) whether for those wanting to access Console to pilot it, or for those wanting to install remote Nodes. It is possible to allow this by making an update in a SQL schema using pgAdmin:

  • Connect to the CAST Storage Service/PostgreSQL instance on which the aip_config schema is located (this schema is installed by the Service Registry when it is first started up - see Step 2 - Run Service Registry installer above).
  • Locate the properties table in the aip_config schema and then locate the keycloak.uri and the eureka.host entries:

Click to enlarge

The Value column contains the URI used to access the SSO/Keycloak service and the Service Registry service - by default these values will be entered using localhost, i.e.:

Replace BOTH instances of localhost with the IP address or the host name of the machine on which the SSO/Keycloak service and the Service Registry service are installed (this will normally by the same machine), which will be accessible over the network, for example:

After making the change:

  • ensure that the firewall on the front-end host machine is open on TCP ports 8081, 8086 and 8088 to allow remote access to both SSO/Keycloak and Console front-end services.
  • restart all services.

Automated (unattended) installation

It is possible to run the Service Registry and Gateway installers in unattended mode using predefined settings stored in a specific file - see the instructions below (it is not possible to do this for the SSO installer).

Create and configure .defaults files

The first step is to create a .defaults file (you can name this however you want, for example unattended.defaults) for each installer. This file contains the settings and options that you want to use for your unattended installation. Examples are provided below containing all available options. Please refer to the GUI installation above for an explanation of the available options. Fill in the options to suit your own deployment scenario:

.

Registry installer .defaults file example
# AIP Service Registry installer config values
# Installation folder for executables
INSTALL_PATH=C:/Program Files/CAST/AIP-Service-Registry/bin
# Type of installation
# Automatically detected by the installer, but you can overwrite it using this parameter
# setup.mode=install
# Data folder
dataFolder=C:/Program Files/CAST/AIP-Service-Registry/data
# Port for the standalone server
server.port=8088

# Database configuration for service registry
db.host=localhost:2282
db.user=operator
db.password=CastAIP
db.database=postgres

# Install as a service
windows.service.install=false
# Start service after installation
windows.service.startAfterInstall=false
# Use a user account for the service
windows.service.isUserAccount=false
# User account name/password (don't forget the domain in the username; should be like DOMAIN\\USER - double backslashes)
windows.service.user=
windows.service.password=

# Create shortcuts on desktop
DesktopShortcutCheckboxEnabled=true
Gateway installer .defaults file example
# AIP Gateway installer config values
# Installation folder for executables
INSTALL_PATH=C:/Program Files/CAST/AIP-Gateway/bin
# Type of installation
# Automatically detected by the installer, but you can overwrite it using this parameter
# setup.mode=install
# Data folder
dataFolder=C:/Program Files/CAST/AIP-Gateway/data
# Port for the gateway server
server.port=8081
# Configuration server URL
configServerUrl=http://localhost:8088/config

# Install as a service
windows.service.install=false
# Start service after installation
windows.service.startAfterInstall=false
# Use a user account for the service
windows.service.isUserAccount=false
# User account name/password (don't forget the domain in the username; DOMAIN\\USER - double backslashes)
windows.service.user=
windows.service.password=

# Create shortcuts on desktop
DesktopShortcutCheckboxEnabled=true


Note that paths require the following syntax for path separators:

  • '/'
  • '\\\\'

The single backslash '\' will be considered an escape character and will cause errors during the installation.

Run the installer with the .defaults file

To run the installer in unattended mode, run the following command, changing the .default filename to the one you wish to use and updating the name of the .jar file:

java -jar AIP-<component>-<version>.jar -defaults-file unattended.defaults -auto

Troubleshooting

During the unattended installation, some elements will be checked automatically and may result in an installation failure:

Optional - Configuration steps to change data folder storage

To change the paths to the data storage folders defined in the Service Registry installer you will need to run an SQL query: using pgAdmin, connect to the CAST Storage Service/PostgreSQL instance on which the aip_config schema has been installed (as described in Step 2 - Run Service Registry installer above). Locate the properties table in the aip_config schema and then locate the following entries:

Click to enlarge

The Value column contains the paths used - change all three paths to use your preferred shared network folder, for example:

After making the change restart all services.

You should perform this action BEFORE you add any applications/perform any analyses/snapshots.

RAM considerations for Windows Services and startup batch scripts

 "Out of the box", the Windows Services and batch scripts made available to run the services are configured to run with conservative RAM memory allocations as shown in the table below:

ValueConsole ≤ 2.2.0Console ≥ 2.2.1Details
Xmx value1024MB2048MBMaximum memory allocation pool for a Java Virtual Machine (JVM).
Xms value256MB512MBInitial memory allocation pool for a Java Virtual Machine (JVM).

This means that even though the host server may have 64GB RAM available (for example), it will only give a maximum of 1GB to the JVM in which each service runs. You may therefore find that this is not sufficient and you may receive low memory/out of memory errors when running analyses or snapshots. If this is the case, CAST recommends increasing the Xmx and Xms values until your low memory/out of memory exceptions have been resolved as explained below.

See Configuring RAM for AIP Console front-end and AIP Nodes for more information about changing the RAM allocations.