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:
- the instructions below assume that the machine hosting the installed services has access to a CAST Storage Service/PostgreSQL instance. See also Storage for CAST AIP.
- starting Console 2.6.1, a "global" Windows Installer is provided - this packages all the Java JAR installers described in this current page into one single installer and should be used wherever possible - see 2.x - Enterprise mode - Installation of Console front-end via global Windows Installer
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.
The installation wizard will be displayed:
- If the wizard cannot locate a previous 2.x installation of the SSO service in the default installation location or in the Window Registry, then the Install option will be automatically selected.
- If the wizard locates a previous 2.x installation of the SSO service 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 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.
Option | Description | |
---|---|---|
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 user | The 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 password | Admin 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:
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 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:
- If the wizard cannot locate a previous 2.x installation of the Service Registry service in the default installation location or in the Window Registry, then the Install option will be automatically selected.
- If the wizard locates a previous 2.x installation of the Service Registry service 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 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:
- common-data
- delivery
- deploy
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:
- aip_node
- aip_config
These schemas store persistence information about the Node(s) and Console front end itself. Click Next to continue.
Option | Description | |
---|---|---|
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 url | This 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 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:
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:
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 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:
- If the wizard cannot locate a previous 2.x installation of the Gateway service in the default installation location or in the Window Registry, then the Install option will be automatically selected.
- If the wizard locates a previous 2.x installation of the Gateway service 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 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:
Option | Description | |
---|---|---|
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:
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 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.
- If you installed them as Windows Services and chose to start the service as well, all services should be up and running correctly.
- If you installed them as Windows Service and chose NOT to start the service, you will need to start the services in the following order:
- SSO/Keycloak
- Service Registry
- Gateway
- Node
- If you did NOT install them as Windows Services, you will need to run the following batch files to start the services in the order listed below - wait until each service is fully started before starting the next one.
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 |
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
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.
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:
.
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:
- "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.
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:
- application.paths.delivery-folder
- application.paths.deploy-folder
- application.paths.shared-folder
Click to enlarge
The Value column contains the paths used - change all three paths to use your preferred shared network folder, for example:
- \\server\share\delivery
- \\server\share\deploy
- \\server\share\common-data
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:
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.