AIP Console and associated services in Docker

Step 1 - ensure deployment requirements are in place

Ensure that all requirements are in place.

Step 2 - download and process the installation files

The AIP Console installation files for Docker are available as an extension published by CAST - see https://extend.castsoftware.com/#/extension?id=com.castsoftware.aip.console&version=latest.

Linux

Download the extension from CAST Extend using curl:

• the command below will download the latest release of AIP Console as a ZIP file. If you need to install a different release, ensure you state the specific extension release number, for example https://extend.castsoftware.com/#/extension?id=com.castsoftware.aip.console/2.0.0-funcrel
• ensure you enter an appropriate CAST Extend API key in <key>. See CAST Extend website or Download an extension using CAST Extend API for more information about this

curl -O -J "https://extend.castsoftware.com/api/package/download/com.castsoftware.aip.console" -H "x-nuget-apikey: <key>" -H "accept: application/octet-stream"

Then unpack the ZIP that has been downloaded:

unzip com.castsoftware.aip.console.2.0.0-beta1.zip

This location is where the installation will be run from. A set of files and folders is produced when the extension is unzipped:

Files:
AIP-Node-<version>.jar
docker-compose.yml

Folders:
postgres

Microsoft Windows

Download the extension from CAST Extend and unzip it to a working folder anywhere on the server - this location is where the installation will be run from. A set of files and folders is produced when the extension is unzipped:

Files:
AIP-Node-<version>.jar
docker-compose.yml

Folders:
postgres

Step 3 - initial customization

Before running the installation, you must customize your deployment to your own environment by editing the following file:

<unpacked zip>/docker-compose.yml

Configure the hostname

You must configure a valid hostname, otherwise, your remote AIP Nodes will not be able to locate the services they require. Locate the following lines in the docker-compose.yml file:

# - HOST_HOSTNAME=${HOSTNAME} # HOSTNAME environment variable on Linux
# - HOST_HOSTNAME=${COMPUTERNAME} # HOSTNAME environment variable on Windows
- HOST_HOSTNAME=host.docker.internal

This section governs the hostname used within Docker. You can either use the hostname defined by your system's environment variable, or you can manually specify it. For example, to use the HOSTNAME variable on your Linux instance, uncomment the first line and comment the third:

- HOST_HOSTNAME=${HOSTNAME} # HOSTNAME environment variable on Linux
# - HOST_HOSTNAME=${COMPUTERNAME} # HOSTNAME environment variable on Windows
# - HOST_HOSTNAME=host.docker.internal

To specify a manual hostname, for example an IP address, change the third line:

# - HOST_HOSTNAME=${HOSTNAME} # HOSTNAME environment variable on Linux
# - HOST_HOSTNAME=${COMPUTERNAME} # HOSTNAME environment variable on Windows
- HOST_HOSTNAME=192.168.200.19

Save the file.

Configure the shared folder paths

You must configure the path to the three shared folders (for source code delivery/deployment/misc) files:

• Where multiple AIP Nodes will be installed, the paths need to point to a mapped network share drive or use a UNC path of the network share, for example:\\shared\console\
• If you are installing AIP Console and only one AIP Node together on one Microsoft Windows server, the paths can point to local paths on the Microsoft Windows server itself, providing enough space is available
• In all circumstances, if you are installing AIP Console on a Linux server, you MUST update the paths, since the default paths provided in the docker-compose.yml file use Microsoft Windows syntax

Locate the following lines in the docker-compose.yml file and make your updates:

- DELIVERY_FOLDER=c:\aip-node-data\delivery
- DEPLOY_FOLDER=c:\aip-node-data\deploy
- SHARED_FOLDER=c:\aip-node-data\common-data

For example:

- DELIVERY_FOLDER=\\shared\console\delivery
- DEPLOY_FOLDER=\\shared\console\deploy
- SHARED_FOLDER=\\shared\console\common-data

Save the file.

Configure the Keycloak login credentials - optional

The AIP Console authentication provider has been totally restructured and now uses the open-source OAuth2 compatible Keycloak system. Keycloak provides local authentication, and can also interact with other enterprise authentication systems such as LDAP and SAML. Keycloak requires a login to administer it, and the default credentials are configured in the docker-compose.yml file in the KEYCLOAK_USER and KEYCLOAK_PASSWORD entries. By default the login credentials are set to admin/admin:

  keycloak:
    image: castbuild/aip-sso
    container_name: keycloak
    ports:
      - 8086:8080
    restart: always
    environment:
      DB_VENDOR: POSTGRES
      DB_ADDR: postgres
      DB_USER: keycloak
      DB_PASSWORD: keycloak
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: admin
      KEYCLOAK_IMPORT: /tmp/aip-realm.json
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - aip-network
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:8080/auth/" ]
      interval: 5s
      timeout: 2s
      retries: 15

If you would like to change these credentials before deploying the Docker images, update the KEYCLOAK_USER and KEYCLOAK_PASSWORD entries and save the file.

Step 4 - run the install

Run the following command from the unpacked ZIP folder:

docker-compose up -d

This will start the install process and the the containers will be downloaded from https://hub.docker.com/. The -d flag causes the containers to be run in the background (see docker compose CLI reference for more information).

You should see the following when all containers have been pulled and started:

You can also check that the containers are up and running using the following command - see the "status" column:

docker ps

Click to enlarge

Before proceeding with any further configuration, you should now create at least one AIP Node instance (AIP Core + AIP Node service), see below.

AIP Node service

You will need to run the AIP Node service installer on each AIP Node instance (i.e. a server on which AIP Core is already installed) that you want to register with AIP Console.

GUI installation

To start the installation, double click the executable JAR file as provided with the installation media. If you are using OpenJDK, you may not be able to execute the .JAR file, instead use the following command to open the JAR in GUI mode:

java -jar AIP-Node-<version>.jar

The next steps are detailed below:

Step 1

The installation wizard will be displayed:

• If the wizard cannot locate a previous installation of the AIP Node package in the default installation location %USERPROFILE%\CAST (Windows),%PROGRAMFILES%\CAST\AipNode (Windows) or in the Window Registry, then the Install option will be automatically selected.
• If the wizard locates a previous installation of the AIP Node package in the default installation location %USERPROFILE%\CAST (Windows),%PROGRAMFILES%\CAST\AipNode (Windows), or in the Window Registry (if installing on Windows), then the Upgrade an existing installation option will be automatically selected.

Since upgrading from 1.x is not currently possible, please ensure that you choose the Install option to proceed with a "clean installation":

Step 2

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

Step 3

Choose a location for your AIP Node "data" - this location will contain items such as AIP Node logs/ExtendCLI configuration items and other non-user specific items such as .properties files. The setup will suggest: %PROGRAMDATA%\CAST\AipNode but you are free to choose a different location. The installation wizard will set Full Access permissions on the these folders to all authenticated users:

Step 4

Fill in the information as suggested in the table below:

HOSTNAME:PORT

Step 5

Fill in the information that is required by the AIP Node package with regard to the Windows Service. Click Next to continue:

Step 6

Choose whether to create shortcut icons and Start menu entries for the AIP Node package. The installation will start when you click Next:

Step 7

The installation process will start. Click Next when complete:

Step 8

The installation process is complete:

CLI installation

Open a command prompt (for example CMD with elevated permissions (run as administrator)) and move to the location where the executable JAR file as provided with the installation media is stored. Start the installer in console mode by launching the following command:

java -jar AIP-Node-<version>.jar -console

The interactive console installer will then start. The steps for the installation process are similar to the GUI installation. Please refer to the GUI installation above for the list of required steps, parameters, default values, etc.

Default values are indicated in square brackets ([like this]) and will be used if the input is not filled with a different value.

AIP Node Service - What is installed?

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

Packages

The package will be installed to the location specified in Step 1:

Data folder

The package will be installed to the location specified in Step 3:

Shortcuts

If you chose to create a shortcut during the installation it will be visible on the desktop, for example:

Windows Service

The following Windows Services will be created if you enabled the relevant option:

Windows Service name	Auto start?
CAST AIP Node Service

AIP Node Service - first start up

When the AIP Node Service installation is complete, you now need to ensure the service is started. When the AIP Node Service is started for the first time, it will register itself in AIP Console. To ensure the service is started:

• If you have chosen to install the service as a Microsoft Windows Service, the service is configured to auto-start after installation:

• If you have not installed the service as a Microsoft Windows Service, then you will need to manually start the service using the batch file here:

%PROGRAMFILES%\CAST\AipNode\tools\aip-node-app.bat

AIP Node 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 AIP Nodes - which is a Java application - are configured to run with conservative RAM memory allocations as shown in the table below:

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 the AIP Nodes run. 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.

What next?

See AIP Console - 2.x - Initial configuration.