Introduction

In ≥ 2.0.0-funcrel, CAST provides a .yml file that is used to install the Console front-end in "enterprise mode" on Docker (Linux) or Docker Desktop (Microsoft Windows) as part of the download media available on CAST Extend (https://extend.castsoftware.com/#/extension?id=com.castsoftware.aip.console&version=latest):

Step 1 - ensure deployment requirements are in place

Ensure that all requirements are in place.

Step 2 - download and process the installation files

Linux

Download the extension from CAST Extend using curl:

• the command below will download the latest release of 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.<version>-funcrel.zip

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 of .yml file

Before running the installation, you must customize your deployment to your own environment by editing the following file - this file is NOT supplied with the installation media and therefore must be created first in the same location as the supplied docker-compose.yml file:

<unpacked_zip>/docker-compose.override.yml

Configure the hostname

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

services:  
  aip-service-registry:
    environment:
      #  - HOST_HOSTNAME=${HOSTNAME} # HOSTNAME environment variable on Linux
      #  - HOST_HOSTNAME=${COMPUTERNAME} # HOSTNAME environment variable on Windows
      - HOST_HOSTNAME=host.docker.internal
      - DELIVERY_FOLDER=c:\aip-node-data\delivery
      - DEPLOY_FOLDER=c:\aip-node-data\deploy
      - SHARED_FOLDER=c:\aip-node-data\common-data

This section governs the hostname used within Docker. By default the hostname will be set to host.docker.internal however CAST recommends defining an appropriate hostname that can be accessed across the network. 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 use the HOSTNAME variable on your Windows instance, uncomment the second 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 to match your requirement:

# - 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 for Node data

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

• Where multiple 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 Console and only one 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 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.override.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 Console authentication provider has been totally restructured in comparison to Console v. 1.x 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

If you would like to change these credentials before deploying the Docker images, add the following lines to the docker-compose.override.yml file under the existing services: entry, update the values for the KEYCLOAK_USER and/or KEYCLOAK_PASSWORD entries and then save the file. For example to change the password to "cast":

services:
...
	keycloak:
    	environment:
			KEYCLOAK_USER: admin
			KEYCLOAK_PASSWORD: cast

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 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

Your Console front-end is now up and running.

What next?

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