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

Summary: how to perform a 2.x installation using the standalone Java JAR installer for demos and POCs.

Introduction

In  2.1.0-funcrel, CAST provides one single Java JAR installer for a "standalone" deployment, as a separate download media available on CAST Extend (https://extend.castsoftware.com/#/extension?id=com.castsoftware.aip.console.standalone&version=latest):

This installer is targeted at deployments on Microsoft Windows on one single machine, specifically and only for demo or POC requirements. The installer includes all required services in one single Java JAR installer:

  • Console front-end service
  • One single Node back-end service

Note that the instructions below assume that the machine you are using already has:

  • a release of CAST Storage Service/PostgreSQL instance installed on it. See also Storage for CAST AIP. The installer does support the use of a remote CAST Storage Services/PostgreSQL if necessary.
  • a release of AIP Core installed on it. See also AIP Core.

Limitations of the standalone Java JAR installer

  • Only one single Node can be managed in Console - this is the Node service provided in the Java JAR installer with Console front-end service. As such the Nodes panel in the Admin Center is not available.
  • Authentication method is limited to local authentication only - LDAP/Active Directory/SAML/SSO with OAuth are not supported (Keycloak service is not provided). In addition, all logins will always be assigned the ADMIN role (can view all data and configuration options).
  • Integration with embedded Dashboards requires a manual process using the cast-integrated-health-engineering-dashboard-<version>.zip file provided in the installation media.
  • No API key support - integration with automation tools is not possible.
  • Not supported for deployment on Linux instances.

Launching the installer

To start the installation of the standalone 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-Console-Standalone-<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 the installer

The installation wizard will be displayed:

  • If the wizard cannot locate a previous installation of the standalone install in the default installation location or in the Window Registry, then the Install option will be automatically selected.
  • If the wizard locates a previous installation of the standalone install in the default installation location or in the Window Registry, then the Upgrade an existing installation option will be automatically selected.

Click Next to continue:

Choose a location on the local machine that will be used for the standalone installation. The setup will suggest: %PROGRAMFILES%\CAST\AIP-Console-Standalone 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 installation "data" - this location will contain by default items such as logs and properties files and the delivery/deploy/shared folders (although these can be changed post install). The setup will suggest: %PROGRAMDATA%\CAST\AIP-Console-Standalone 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 for your installation with regard to the location of AIP Core on the local machine and connection details for the CAST Storage Service/PostgreSQL instance (this is required to store persistence information). By default, the CAST Storage Service/PostgreSQL instance you define will ALSO be configured as a storage host for all application schemas and the Measurement schema. Click Next to continue.

OptionDescription
CAIP locationEnter the location of the AIP Core installation on the local server. This will normally be: %PROGRAMFILES%\CAST\<version>.
Console Standalone Port

This port will be pre-filled with 8081. This is the port number used to access Console front-end. If the port is already being used by another service, you can choose another custom port (for example port 80). You can modify this port number post installation - see Optional post-installation configuration steps.

Database connectionDatabase Server URLEnter the hostname/IP address and port number of the CAST Storage Service/PostgreSQL instance that this standalone installation will use to store persistence information. The field will be pre-filled with localhost:2282, which assumes a CAST Storage Service is installed on the local server. You can configure a connection to a remote CAST Storage Service/PostgreSQL instance if required.
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. One schema will be created in the database you specify - and the name of this schema is defined in the field "Database Schema Name" (see below).

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

Database Schema Name

This is the name of the schema that will be used to store persistence information. The field will be pre-filled with node_standalone, but you are free to choose a different name if necessary.

  • If the schema does not exist it will be created automatically when Console is started.
  • If the schema already exists (for example from a previous installation of Console standalone) it will be re-used and any settings from the previous installation will be re-used.
Database UserEnter the credentials for the CAST Storage Service/PostgreSQL configured in the Database Server URL field. The login and password fields will be pre-filled with the default credentials: operator/CastAIP.
Database Password

Fill in the information that is required for your installation with regard to the Windows Service. You are not obliged to install the standalone 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 your installation. The installation will start when you click Next:

The installation process will start. Click Next when complete:

The installation process is complete:

Step 2 - Initial configuration

Ensure the service up and running

The next step is to first ensure that the service is up and running.

  • If you installed it as a Windows Service and chose to start the service as well, the service should be up and running correctly.
  • If you installed it as a Windows Service and chose NOT to start the service, you will need to start the service.
  • If you did NOT install it as a Windows Service, you will need to run the following batch files to start the service: %PROGRAMFILES%\CAST\AIP-Console-Standalone\tools\aip-node-app.bat

Connect to Console front-end and complete start-up wizard

Now connect to Console using the following URL - change the port number if you entered a custom port during the installation:

http://localhost:8081/

If the installation and start-up have completed successfully, you will see the following start-up wizard. This displayed the first time you login to Console. The wizard provides a user-friendly method to configure various mandatory settings and options, such as:

  • Entering a license key
  • Configuring access to CAST Extend / use of a proxy caching server

Each step in the wizard is explained in detail in Complete start-up wizard - v. 2.x

When the wizard is complete, the login screen will be displayed:

Login with either of the following credentials - both have the ADMIN role and perform all tasks and view all data:

  • admin/admin
  • cast/cast

Configure your CAST Storage Service or PostgreSQL instances - optional

By default, the CAST Storage Service/PostgreSQL instance you defined during the Java JAR installation process will be configured as a storage host for all application schemas and the Measurement schema:

In the vast majority of cases for a standalone deployment, there is no need to make any further configuration changes, however, you can add in additional CAST Storage Services/PostgreSQL instances should you need to. See Configure your CAST Storage Service or PostgreSQL instances - v. 2.x.

If you need to change the settings of the CAST Storage Service/PostgreSQL instance defined during the installation process, please see Change the default CAST Storage Service/PostgreSQL instance below.

Step 3 - deploy embedded Dashboards

If you would like to use embedded Dashboards with this installation of Console, you can do so, however, the steps are manual as shown below.

Part 1 - CAST RESTAPI deployment and configuration

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) and is partly pre-configured for use with the CAST 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 file - however, CAST recommends not starting the application at this point (it will not start properly). You can also install the RESTAPI as a Windows Service as an alternative to using the startup.bat (see below).

<unpacked_zip>\startup.bat

Install as Microsoft Windows service - optional

 Click here to expand...

If you have would like to control the application server via a Microsoft Windows Service, CAST provides an installation batch script to do this for you:

<unpacked_zip>\dashboard-service-install.bat

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:

  • The installer requires:
    • Java JDK or JRE ≥ 8
    • a JAVA_HOME system environment variable pointing to the installation location of the Java JDK
  • The .bat installer will configure the service to use the <unpacked_zip>\amd64\dashboard-service.exe. You may want to ensure that the unpacked zip file is in an appropriate location.
  • 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:

Configure application.properties for connection details

When the ZIP has been unpacked you now need to configure the application.properties file to tell the CAST RESTAPI on which CAST Storage Service/PostgreSQL instance the Dashboard schemas are stored. This file is located here:

<unpacked_zip>\configurations\application.properties

Locate the following section in the file:

## DATASOURCE (DataSourceAutoConfiguration & DataSourceProperties)
# properties which will be considered by spring-boot automatically to create the bean for datasource at run time
# Connection to PostgreSQL database
restapi.datasource[0].url=jdbc:postgresql://localhost:2282/postgres
restapi.datasource[0].username=operator
restapi.datasource[0].password=CastAIP
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

One single CAST Storage Service / PostgreSQL instance

If all your Dashboard schemas are located on one single CAST Storage Service/PostgreSQL instance then you need to modify the url, username and password entries to match your target CAST Storage Service/PostgreSQL. Save the file before proceeding.

## DATASOURCE (DataSourceAutoConfiguration & DataSourceProperties)
# properties which will be considered by spring-boot automatically to create the bean for datasource at run time
# Connection to PostgreSQL database
restapi.datasource[0].url=jdbc:postgresql://localhost:2282/postgres
restapi.datasource[0].username=operator
restapi.datasource[0].password=CastAIP
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

Multiple CAST Storage Services  / PostgreSQL instances

If your Dashboard schemas are located on multiple CAST Storage Services/PostgreSQL instances, you need to add in the additional servers as shown in the example below:

  • Ensure that you modify the url, usernamepassword and resource entries to match your target CAST Storage Service/PostgreSQL. In particular, the resource entry must be unique within the application.properties file.
  • The [0] must also be incremented for additional CAST Storage Service/PostgreSQL instances, for example, use restapi.datasource[1]restapi.datasource[2] etc.
  • Save the file before proceeding.
## DATASOURCE
# Resource1 is the datasource name used in domains.properties
# Adapt server name (localhost) and port (2282) if required
# You can add multiple datasources if you want to connect to multiple CSS Servers. Datasource name must be unique
# You have to configure your domains names and relative schema names in domains.properties
restapi.datasource[0].url=jdbc:postgresql://localhost:2282/postgres
restapi.datasource[0].username=operator
restapi.datasource[0].password=CastAIP
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

restapi.datasource[1].url=jdbc:postgresql://192.168.200.105:2282/postgres
restapi.datasource[1].username=operator
restapi.datasource[1].password=CastAIP
restapi.datasource[1].poolname=Resource2
restapi.datasource[1].minimumIdle=10
restapi.datasource[1].maximumPoolSize=20

Configure minimumIdle and maximumPoolSize - optional

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

restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

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

minimumIdle

The minimum number of connections that should be kept in the pool at all times (even if there is no traffic). Default value is 10.  Idle connections are checked periodically.

maximumPoolSizeThe maximum number of active connections that can be allocated from this pool at the same time. The default value is 20.

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:

<unpacked_zip>\configurations\domains.properties

One uncommented line will exist as follows:

AAD=Resource1,general_measure

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 - CSS and Measurement settings), then you do not need to make any changes here:

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 Console (this is the default name for this schema as defined in Administration Center - Settings - CSS and Measurement settings). If you are using a different name, then please update it here.

Start the CAST RESTAPI

Start up the web application to ensure that the changes are taken into account. The bootable ZIP is set to run on port 8087 by default - you can also change the port number in the following file:

<unpacked_zip>\configurations\application.properties

in the following line:

server.port=8087

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:

Using startup batch scripts

If you are using the startup.bat or startup.sh scripts 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:

Microsoft Windows - startup.bat
java -jar -Xmx1024m -Xms256m cast-integrated-health-engineering-dashboard-<version>.jar

Linux - startup.sh
JAVA_OPTS="-Xmx1024m -Xms256m"
Using Microsoft Windows Service

The Microsoft Windows service installer batch script will set the service to use the following RAM memory - you may find that this is not sufficient if you experience out of memory Java errors and these values can be increased. After making changes, restart the Microsoft Windows service to ensure the changes are taken into account:

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

Part 2 - Console configuration

Move to the System Settings panel:

Open the Dashboard Integration settings panel and click the Synchronize button

Finally click either of the dashboard icons to check that you can access the dashboards - login with the default admin/admin credentials:

Note that it is not possible to log out of either Dashboard - closing the browser tab is the only way to close the connection.

Optional post-installation configuration steps

All options listed below are exposed in the following text file:

%PROGRAMDATA%\CAST\AIP-Console-Standalone\application-standalone.yml

When changes are made, save the file and then restart the service to ensure the changes are taken into account.

Configure data paths

Out of the box, Console will be configured to use the following paths to fetch and store data required and generated during an analysis:

Delivery folder%PROGRAMDATA%\CAST\AIP-Console-Standalone\delivery
Deploy folder%PROGRAMDATA%\CAST\AIP-Console-Standalone\deploy
Shared data folder%PROGRAMDATA%\CAST\AIP-Console-Standalone\shared

These paths can be modified post install if required, however, CAST does not recommend changing them once Applications have been delivered and analyzed. To change the paths, edit the application-standalone.yml file, locate the following lines and modify them as necessary:

application:
	paths:
		...
		delivery-folder: C:/ProgramData/CAST/AIP-Console-Standalone/delivery
		deploy-folder: C:/ProgramData/CAST/AIP-Console-Standalone/deploy
		shared-folder: C:/ProgramData/CAST/AIP-Console-Standalone/shared

Save the file and then restart the service.

Configure Console user logins

Console Standalone uses local authentication with logins declared in the application-standalone.yml file. Out of the box, the following logins are available

LoginPasswordRole
adminadminADMIN (can view all data and configuration options)
castcast

To edit these logins (change the password for example), or to add additional logins, locate the following lines and modify them as necessary:

# Standalone users  
users:
    - username: admin
      password: CRYPTED2:0352F19CC37A1694DF51131A05A350FC
    - username: cast
      password: CRYPTED2:3FE5B3676B861218F6C339CFEFC9367B

Note that the passwords are encrypted and although plain text passwords are accepted, CAST highly recommends that when changing the password for an existing user or adding a new user that you also encrypt the password using the aip-encryption-tool.bat file (located in the admin folder in the installation location) to run the encryption tool:

For example to add an additional login called corp, with the password corp (encrypted), add the following:

# Standalone users  
users:
    - username: admin
      password: CRYPTED2:0352F19CC37A1694DF51131A05A350FC
    - username: cast
      password: CRYPTED2:3FE5B3676B861218F6C339CFEFC9367B
	- username: corp
	  password: CRYPTED2:B5E4BDDEEE58E67BCD4085D8AFF590A7

Save the file and then restart the service.

All logins (new or existing) will always be assigned the ADMIN role (can view all data and configuration options).

Change the Console front-end port

If you want to change the port on which Console is running (which is determined during the initial installation), locate the following lines in the application-standalone.yml file and modify them as necessary:

server:
  port: 8081

Save the file and then restart the service.

Change location of AIP Core

If you have changed the installation location of AIP Core, you will need to update Console. To do so, locate the following lines in the application-standalone.yml file and modify them as necessary:

application:
  paths:
    ...
    data-folder: C:/Program Files/CAST/8.3

Save the file and then restart the service.

Change the default CAST Storage Service/PostgreSQL instance

If you need to change the default CAST Storage Service/PostgreSQL instance defined during the installation process, locate the following lines in the application-standalone.yml file and modify them as necessary:

  datasource:
    url: jdbc:postgresql://localhost:2282/postgres?currentSchema=node_standalone
    username: operator
    password: CRYPTED2:90B1A6EC1618661401B724DB5AC34595

Save the file and then restart the service.

  • If you change the name of the persistence schema node_standalone, a new schema will be created when you restart the service containing no existing records (e.g. you will lose any configuration settings that you may have changed).
  • Note that the default password for the operator user is encrypted and although a plain text password is accepted, CAST highly recommends that when changing the password that you also encrypt the password using the aip-encryption-tool.bat file (located in the admin folder in the installation location) to run the encryption tool:

Automated (unattended) installation

It is possible to run the installer in unattended mode using predefined settings stored in a specific file - see the instructions below.

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). This file contains the settings and options that you want to use for your unattended installation. An example is 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:

# AIP Console Standalone installer config values
# Installation folder for executables
INSTALL_PATH=C:/Program Files/CAST/AIP-Console-Standalone/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-Console-Standalone/data
# CAIP folder path
caipFolder=C:/Program Files/CAST/8.3
# Port for the standalone server
serverPort=8081
# Postgres DB URL to use for AIP Node and as initial CSS server
dbServerUrl=localhost:2284
# Database Name
dbName=postgres
# Schema Name
dbSchemaName=node_standalone
# Username
dbUser=operator
# Password
dbPassword=CastAIP

# 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)
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-Console-Standalone-<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:

  • "Invalid CAIP folder location": please check that the caipFolder property points to an existing installation of AIP Core
  • "Unable to access database": please make sure the information to access the database is properly set.
  • "Unable to start service": after installation, the service may not be started properly. Please check in the Windows Services that the service details were set correctly and check that the service can be started.

What is installed?

When the installation process is complete, the following will have been installed:

Service

The service will be installed to the location specified in the installer:

%PROGRAMFILES%\CAST\AIP-Console-Standalone

Data folder

The service will be installed to the location specified in the installer:

%PROGRAMDATA%\CAST\AIP-Console-Standalone

Shortcuts

If you chose to create a shortcut during the installation it will be created. This can be used to start up the service (the shortcut points to a batch file):

The service will run on port 8081.

Windows Service

The following Windows Service will be created if you enabled the relevant option - and started if you also enabled that option:

The service will run on port 8081.

Database schema

A database schema called node_standalone (or equivalent custom name) will be automatically created on the configured CAST Storage Service/PostgreSQL instance when the service is started for the first time.

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.

Uninstall process

A dedicated uninstaller is available which can be accessed via the Microsoft Windows Add or remove programs control panel:

Clicking Uninstall will launch the Java uninstaller:

This uninstaller is configured to remove:

  • the contents of the %PROGRAMFILES%\CAST\AIP-Console-Standalone installation folder (or the equivalent custom location)
  • the %PROGRAMFILES%\CAST\AIP-Console-Standalone folder itself if required (tick the Force the deletion of option)
  • any shortcuts on the desktop
  • any Start menu entries
  • the Windows service

This uninstaller will not remove the following items:

  • the folder and content of the %PROGRAMDATA%\CAST\AIP-Console-Standalone data folder (or the equivalent custom location)
  • the deployed cast-integrated-health-engineering-dashboard-<version>.zip file, used for access to CAST dashboards
  • any CAST Storage Service/PostgreSQL schemas:
    • associated with the Applications you have created through Console
    • the persistence schema node_standalone (or the equivalent custom schema)
  • any instances of AIP Core
  • No labels