Page tree
Skip to end of metadata
Go to start of metadata

AIP Console and associated services in Docker

Step 1 - ensure deployment requirements are in place

Ensure that all requirements are in place.

This section assumes that Docker is already up an running on your target host server. Installation of third-party software is out of scope of this documentation, however, some tips can be found in the following third-party documentation:



Microsoft Windows

Step 2 - download and process the installation files

The AIP Console installation files for Docker are available as an extension published by CAST - see


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
  • 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 "" -H "x-nuget-apikey: <key>" -H "accept: application/octet-stream"

Then unpack the ZIP that has been downloaded:


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



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:



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

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:

    image: castbuild/aip-sso
    container_name: keycloak
      - 8086:8080
    restart: always
      DB_ADDR: postgres
      DB_USER: keycloak
      DB_PASSWORD: keycloak
      KEYCLOAK_USER: admin
      KEYCLOAK_IMPORT: /tmp/aip-realm.json
        condition: service_healthy
      - aip-network
      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

If you are facing a permission denied error when executing on Linux, you may need to elevate your user by running the sudo command specific to your Linux distribution (e.g. sudo su on Debian).

This will start the install process and the the containers will be downloaded from -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.

To run the setup, local Administrator privileges are required.

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

You can run the above command in the Command Prompt window (CMD) - ensure you launch the CMD window with elevated permissions (run as administrator).

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:

Instance ID

This is how the AIP Node instance will be identified in AIP Console. The default suggestion produces the following:


For example:

CAIP locationEnter the location of the AIP Core installation on the local server. This will normally be: %PROGRAMFILES%\CAST\<version>.
Config server URL

Enter the URL to the AIP Console server, using the port number 8088 unless you have customized this port. This corresponds to the aip-config-server. You can use a FQDN, hostname or IP address, for example:

  • http://my_aip_console_server:8088/config

Step 5

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

Windows ServiceInstall 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):

  • this option is ineffective when installing the AIP Console package on a Linux server.
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. This is particularly true if:

In both these situations, the user running the Windows Service will be used to access the proxy/shared network resources.

Instead CAST recommends using the login credentials that match the log in used to install AIP Console/AIP Node/AIP Core/set system proxy settings etc. - for example, this could be a specific "service account" that is created specifically for installing and running AIP Console/AIP Nodes/AIP Core/setting system proxy settings. This service account would also therefore have access to the shared network resources and would be able to use the system proxy settings.

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:


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:


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 nameAuto start?
CAST AIP Node Service(tick)

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:
  • You may see a Microsoft Windows firewall popup asking you to make an exclusion for the Java JRE executable (launched by the AIP Node Service) - click Allow access to create the exclusion:

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:

Xmx value1024MBMaximum memory allocation pool for a Java Virtual Machine (JVM).
Xms value256MBInitial 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 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.

  • No labels