Summary: how to perform a 2.x installation on Docker or Docker Desktop.
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:
- Install Docker Desktop on Windows
- Containers for Linux must be enabled:
Step 2 - download and process the installation files
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 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 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
When you run
docker-compose up to run the install and start the relevant Docker containers, the system will search for a file named
docker-compose.yml and all configured services, networks, volumes etc to create your Docker stack will be read from this file. If you also additionally have a file named
docker-compose.override.yml this will be read as well and used as an override file to complement. It works in the following order:
- All definitions from
docker-compose.ymlwill be used
- All definitions that are also defined in
docker-compose.override.ymlwill automatically overwrite the settings from
- All definitions only available in
docker-compose.override.ymlwill be added additionally.
CAST highly recommends that ALL customization is added to the
docker-compose.override.yml since the existing
docker-compose.yml is overwritten during any future upgrade process of Console front-end.
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
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:
To use the HOSTNAME variable on your Windows instance, uncomment the second line and comment the third:
To specify a manual hostname, for example an IP address, change the third line to match your requirement:
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:
- 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.ymlfile use Microsoft Windows syntax
Locate the following lines in the
docker-compose.override.yml file and make your updates:
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_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, add the following lines to the
docker-compose.override.yml file under the existing
services: entry, update the values for the
KEYCLOAK_PASSWORD entries and then save the file. For example to change the password to "cast":
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 related distros).
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:
Click to enlarge
Your Console front-end is now up and running.
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.