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.
Option | Description | |
---|---|---|
CAIP location | Enter 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 connection | Database Server URL | Enter 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.
| |
Database User | Enter 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:
Option | Description | |
---|---|---|
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
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
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
,username,
password
andresource
entries to match your target CAST Storage Service/PostgreSQL. In particular, theresource
entry must be unique within the application.properties file. - The
[0]
must also be incremented for additional CAST Storage Service/PostgreSQL instances, for example, userestapi.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. |
maximumPoolSize | The 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:
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:
|
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
Login | Password | Role |
---|---|---|
admin | admin | ADMIN (can view all data and configuration options) |
cast | cast |
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:
Value | Console ≤ 2.2.0 | Console ≥ 2.2.1 | Details |
---|---|---|---|
Xmx value | 1024MB | 2048MB | Maximum memory allocation pool for a Java Virtual Machine (JVM). |
Xms value | 256MB | 512MB | Initial 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