2.x - Enterprise mode - Installation of Console front-end via global Windows Installer

This Enterprise mode installer is currently available as a beta.

Introduction

This installer (com.castsoftware.aip.console.windows.setup) is aimed at non-Docker deployments on Microsoft Windows and will, in time, replace the individual Java JAR installers described in 2.x - Enterprise mode - Installation of AIP Console front-end via Java JAR installers. The aim of this installer is to simplify the deployment process: all front-end services (SSO/Keycloak, Service Registry and Gateway) are combined into one installer, which means that it is not necessary to run each installer separately.

Prerequisites and things to know

  • This installer is only to be used for a fresh installation. It is not possible to run the installer to update previous installations of the separate enterprise Java JAR installers, nor a standalone deployment. An "updater" exists for the purpose of updating previous installations to a new release.
  • The Node service is not provided in this installer and must be installed separately - see AIP Node service - back-end installation.
  • The SSO/Keycloak, Service RegistryGateway services must have access to at last one CAST Storage Service/PostgreSQL instance which will be requested in the installer. See also Storage for CAST AIP.
  • The CAST Storage Service/PostgreSQL instance defined in the installer is used for two things:
    • it must contain an empty database called "keycloak" (this must be created before the installer is launched) - this will be populated with various tables in the public schema for use by the SSO/Keycloak service (these tables are created when the service starts for the first time):



    • one schema (aip_config) will be created in a database of your choice on the target CAST Storage Service/PostgreSQL instance. This schema is used to store persistence information and is created when the various Console Windows Services are started for the first time. If the schema exists already it will be re-used. The installer will prompt you for the database name (by default set to postgres) and the schema will be stored under this database. Note that the first Node service to be installed and started (see AIP Node service - back-end installation) will create a schema called aip_node alongside the aip_config schema.

  • You should configure a shared network folder that will be used to store the three default storage folders - these folders should already exist but should be empty:
    • common-data
    • delivery
    • deploy
  • The installer will automatically create Microsoft Windows Services entries for all services provided in the installer. By default the LocalSystem user will always be used (the SSO/Keycloak service will not start if configured with any other user) and the installer does not expose any of the settings.

Current known issues

This installer is currently in beta, therefore some known issues exist as described below:

  • The installer does not create all the necessary uninstallation files therefore it is not possible to run a global uninstall from the Microsoft Windows "add/remove programs" panel. Instead, to remove all items before attempting a new installation:
    • each service should be uninstalled first (marked as "1" in the screenshot below) in any order
    • then finally the the global installer should also be uninstalled (marked as "2" in the screenshot below)

  • Desktop shortcuts to start up each service (via a batch file) are not created. The batch files do exist in the installation folder however.
  • The connection to the PostgreSQL/CAST Storage Service instance cannot be checked by the installer, as such the installation will fail if the configured parameters are incorrect or if the SSO/Keycloak database does not exist in the defined instance.

Step 1 - Run the Windows Installer

Launching the installer

To start the installation, double click the executable file (ConsoleWindowsSetup-<version>.exe) as provided with the installation media:

Select installation path

Choose a location on the local machine that will be used for the installation. The setup will suggest: %PROGRAMFILES%\CAST\CAST-Imaging-Console 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:

Select data path

Choose a location for your service "data" - this location will contain items such as logs. The setup will suggest: %PROGRAMDATA%\CAST\CAST-Imaging-Console 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:

Configure path to shared folders

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:

If you choose locations on the local machine, a warning will be displayed. CAST highly recommends that a shared network resource is always used to separate the data from the services and to allow Nodes to easily access the data:

Customize ports and embedded Dashboards

The installer will then prompt you to select the front-end port numbers for the various services and the integrated Dashboard URL. Click Next to continue:

SSO/Keycloak, Service Registry, Gateway

These ports can be customized if another service is already using the default port number, however, CAST recommends using the default port where possible.

Integrated Dashboard URL

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

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

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

Customize ports and embedded Dashboards

Fill in the target CAST Storage Service/PostgreSQL instance information - this is used by various services for storing persistence information and for access to the database called keycloak. Click Next to continue:

Host

Enter the hostname/IP address and port number of the CAST Storage Service/PostgreSQL instance on which the keycloak database already exists. This instance will also be used to store the aip_config and aip_node schemas (in the database defined in the Database name field) containing persistence information. The field will be pre-filled with current_machine_hostname:2284, which assumes a CAST Storage Service is installed on the local machine: update this if it is not the case.

Database name

The database name on your target CAST Storage Service/PostgreSQL instance in which you want the aip_config and aip_node persistence schemas to be created. The field will be pre-filled with postgres, but you are free to choose a different name if necessary. This database must exist already. CAST highly recommends using the default "postgres" database. The credentials you enter below MUST have full read/write access rights to the database you specify.

User

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

Password

A summary of the chosen options is then displayed. Click Install to start the installation process:

The installation will then proceed:

Step 2 - Ensure all Console services are up and running

The next step is to first ensure that all services are up and running - if any are not running, please start them:

The services can alternatively be started using the following batch files if you do not want to use the Windows Services:

Gateway Service

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

Service Registry

%PROGRAMFILES%\CAST\CAST-Imaging-Console\AIP-Service-Registry\tools\aip-service-registry-app.bat
SSO/Keycloak%PROGRAMFILES%\CAST\CAST-Imaging-Console\AIP-SSO\opt\jboss\tools\start.bat

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

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

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

Step 3 - Install the Node service

You should now run the Node service installer on all Node instances that you want to manage in CAST Console. See AIP Node service - back-end installation.

You must install at least one Node service before performing the initial configuration steps in Console (e.g. entering the license key and configuring CAST Extend details).

Step 4 - Perform the initial configuration steps

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

You DO NOT need to perform step 1 (setting up a redirect in Keycloak) since this will already be done for you.

Step 5 - Deploy dashboards

Embedded dashboards

See Embedded CAST Dashboard deployment process using Java JAR installer.

Standalone dashboards

See Standalone CAST Dashboard deployment process.

What is installed?

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

Services

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

%PROGRAMFILES%\CAST\CAST-Imaging-Console

Data folder

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

%PROGRAMDATA%\CAST\CAST-Imaging-Console

Windows Services

The following Windows Services will be created and started:

The services will run on the following default ports:

Gateway Service

8081 - this is the port used by end users/admins to access Console.

Service Registry

8088
SSO/Keycloak8086

Database items

  • A database schema called aip_config
  • A database called keycloack (must exist already) will be populated with data for SSO/Keycloak service

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:

ValueRAMDetails
Xmx value2048MBMaximum memory allocation pool for a Java Virtual Machine (JVM).
Xms value512MBInitial 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 2GB 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.