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:
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.
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 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
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:
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:
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
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:
To specify a manual hostname, for example an IP address, change the third line:
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:
- 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.ymlfile use Microsoft Windows syntax
Locate the following lines in the
docker-compose.yml file and make your updates:
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_PASSWORD entries. By default the login credentials are set to admin/admin:
If you would like to change these credentials before deploying the Docker images, update the
KEYCLOAK_PASSWORD entries and save the file.
Step 4 - run the install
Run the following command from the unpacked ZIP folder:
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 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:
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.
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:
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:
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":
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:
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:
Fill in the information as suggested in the table below:
This is how the AIP Node instance will be identified in AIP Console. The default suggestion produces the following:
|CAIP location||Enter 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:
Fill in the information that is required by the AIP Node package with regard to the Windows Service. Click Next to continue:
|Windows Service||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.
|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.
Choose whether to create shortcut icons and Start menu entries for the AIP Node package. The installation will start when you click Next:
The installation process will start. Click Next when complete:
The installation process is complete:
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:
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:
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:
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:
- 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:
- See AIP Node Service - RAM considerations for Windows Services and startup batch scripts below for more information about the RAM assigned to the AIP Node Service by default.
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 value||1024MB||Maximum memory allocation pool for a Java Virtual Machine (JVM).|
|Xms value||256MB||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 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.