Summary: how to perform a 2.x installation on Docker or Docker Desktop.
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.
This section assumes that Docker/Docker Desktop 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:
Ubuntu
CentOS
Microsoft Windows
- Install Docker Desktop on Windows
- Containers for Linux must be enabled:
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:
<unpacked_zip>/docker-compose.yml
Configure the hostname
You must configure a valid hostname, otherwise your remote 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. 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.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, 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 related distros).
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
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.