Summary: how to perform a 2.x installation using the standalone Java JAR installer.
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. 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:
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 (note that in ≥ 2.4, this limitation has been removed with the provision of an interactive Java JAR installer).
- There is no migration path to enterprise releases of Console - in other words, if you have analyzed applications using the standalone release, and you then decide you require more than one Node for analysis purposes or you require enterprise authentication (integration with LDAP/Active Directory) it is not possible to migrate your existing applications to an enterprise release installation.
- Not supported for deployment on Linux instances.
- No ability to generate an API key for automated tools.
- No ability to receive email notifications for job actions.
Using standalone mode with automation tools
When using Console ≥ 2.3 in standalone mode with automation tools such as the Console RestAPI (AIP Console - Interactive API documentation) or the Console automation tools (https://extend.castsoftware.com/#/extension?id=com.castsoftware.aip.console.tools&version=latest), you should ensure that you authenticate in basic mode (i.e. no need to use an API Key - just use your password). For example, when using the Console automation tools, pass your login using the --user parameter and your password using the --apikey parameter (see https://github.com/CAST-Extend/com.castsoftware.aip.console.tools/blob/master/aip-console-tools-cli/README.md):
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:
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.
|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 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.|
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 / Database Password||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.|
|Install Log Service||See Log Service installation.|
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:
|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:
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:
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 Dashboards
Please see the information in Embedded CAST Dashboard deployment process using Java JAR installer.
2.0.x - 2.3.x
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).
Install as Microsoft Windows service - optional
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:
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:
Locate the following section in the file:
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
password entries to match your target CAST Storage Service/PostgreSQL. Save the file before proceeding.
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
resourceentries to match your target CAST Storage Service/PostgreSQL. In particular, the
resourceentry must be unique within the application.properties file.
must also be incremented for additional CAST Storage Service/PostgreSQL instances, for example, use
- Save the file before proceeding.
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:
CAST recommends using the default options unless you are experiencing performance issues. The options are used as follows:
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:
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 - 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:
in the following line:
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:
|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:
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
Most options listed below are exposed in the following configuration file:
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:
|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:
Save the file and then restart the service.
Changing folder locations with onboarded Applications
Whilst it is technically possible to change the folder locations once an Application has been onboarded, please be aware of the following if you choose to do so:
- Changing the Delivery folder location is NOT supported and will break your existing Applications
- Changing the Deploy folder will cause added/deleted objects to be recorded in subsequent snapshots
- Changing the Shared data folder requires that you copy the content from the previous location to the new location
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
|admin||admin||ADMIN (can view all data and configuration options)|
To edit these logins (change the password for example), or to add additional logins, locate the following lines and modify them as necessary:
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:
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:
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:
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:
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:
Configure SSO (single sign-on) for CAST Imaging installed on Microsoft Windows
- This step is only available for Console ≥ 2.5.1 when using CAST Imaging ≥ 2.13 installed on Microsoft Windows
- SSO is only supported when CAST Console and CAST Imaging are installed on the same machine
If you would like to access CAST Imaging using your CAST Console credentials, you can configure a SSO (single sign-on) mechanism in CAST Imaging that will allow this. When you click through to CAST Imaging directly from the icons available in CAST Console, you will be redirected to the CAST Console login page the first time you do so and you should then enter you CAST Console credentials - if the credentials are correct you will then be redirected back into CAST Imaging without needing to enter separate CAST Imaging login credentials. Subsequent sessions in the same browser will not require a login.
To do so, edit the following file on the machine on which CAST Imaging is installed:
Find the following line:
and change it to:
Then ensure that the following line is present in the file (it is usually located at the very end of the file). This line tells CAST Imaging where CAST Console is located and on what port it is running (by default it assumes that CAST Console is on the same machine as CAST Imaging and is using the default port number):
- if this line is not present in the application.properties file, add it.
- then, ensure that there is no white space at the very end of the line - if there is, delete the extra white space
You should then modify the URL to match your environment. The URL should match exactly how you routinely access Console. Therefore:
- if you use to access Console, you can leave the URL as it is.
- if you use a hostname or IP address ( or http://<ip_address>:8081) to access Console, you must modify the line to match this.
- if CAST Console is running on the default port 8081, you can leave the port number as it is.
- if CAST Console is using a custom port (i.e. not 8081), change the port number in the URL to match the custom port
Finally, save the .properties file and then finally restart the CAST Imaging - Imaging Login Microsoft Windows Service to ensure the changes are taken into account.
Login Service is not accessible
If the login service starts but isn't accessible, check that the file
application-security-standalone.xml is properly installed in
%APPDATA%\CAST\ImagingSystem\login\security. If you cannot find the XML file there, check if the file exists in
%PROGRAMFILES%\CAST\ImagingSystem\login\security. If that is the case, copy the XML file to
%APPDATA%\CAST\ImagingSystem\login\security and restart the CAST Imaging - Imaging Login Microsoft Windows Service.
Configure SSO (single sign-on) for embedded CAST Dashboards installed on Microsoft Windows
- This step is only available for Console ≥ 2.5 when using CAST Dashboards ≥ 2.9.1 installed on Microsoft Windows
- Currently SSO is only supported when CAST Console and the embedded CAST Dashboards RESTAPI are installed on the same machine
If you would like to access the embedded CAST Dashboards using your CAST Console credentials, you can configure a SSO (single sign-on) mechanism in the embedded CAST Dashboards that will allow this. When you click through to CAST Dashboards directly from the icons available in CAST Console, you will be given the choice to login via CAST Console, in which case you will be redirected to the CAST Console login page and you should then enter you CAST Console credentials - if the credentials are correct you will then be redirected back into the embedded CAST Dashboards without needing to enter separate embedded CAST Dashboards login credentials. Subsequent sessions in the same browser will not require a login.
To do so, edit the following file on the machine on which the embedded CAST Dashboards RESTAPI is installed:
Firstly, ensure that the following line is set to "integrated":
Now, update (or add) the
security.standalone.enabled line and set it to
Next, update (or add) the key
security.standalone.console.url and set it to the URL and port of your CAST Console installation - this should be http://localhost:8081. This line tells the embedded CAST Dashboard where CAST Console is located and on what port it is running. If CAST Console is running on a custom port, ensure you enter the correct port:
Save the .properties file and then finally restart the embedded CAST Dashboard service to ensure the changes are taken into account. When accessing either the Health Dashboars or Engineering Dashboard direct from CAST Console, you will have the option to login using your CAST Console credentials:
Clicking on the "Login with Imaging Console Standalone" will open the CAST Console login form. After providing credentials, you will be redirected to either the Health or Engineering Dashboards with access to the specific application.
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:
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:
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:
The service will be installed to the location specified in the installer:
The service will be installed to the location specified in the installer:
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.
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.
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.
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-Standaloneinstallation folder (or the equivalent custom location)
%PROGRAMFILES%\CAST\AIP-Console-Standalonefolder 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-Standalonedata 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