Created by James Hurrell on Jun 05, 2023

Summary: This section describes the upgrade process for the Front-end Console packages.

There is no upgrade path between 1.x and 2.x. Instead see Upgrade path in Upgrade AIP Console.

Pre-upgrade actions

Stop all services

Before starting the upgrade, ensure that you stop all services/Docker containers and any Nodes that are managed by your Console installation.

2.x - Docker install upgrade process

Any Node service must be updated separately.

Upgrading existing images and containers is actioned using built-in Docker commands:

  • Download the new media for the new release of Console and unzip it anywhere on the host server.
  • Stop the existing Docker containers and remove the stopped containers as well as any networks that were created using the following command:
docker-compose down
  • If you have customized the existing docker-compose.yml file provided with the previous release, ensure that any changes you made are transferred to the docker-compose.yml file provided in the new release media. You do NOT need to do this if all your customization has already been added to a docker-compose.override.yml file.
Note that CAST highly recommends that any customization is ALWAYS added to a docker-compose.override.yml file instead of modifying the  docker-compose.yml file directly - see 2.x - Enterprise mode - Installation of AIP Console front-end via Docker or Docker Desktop.
  • Rename the existing docker-compose.yml file to preserve any customization in case of roll-back requirements.
  • Copy the docker-compose.yml file provided in the new media and paste it in the same location that as used to run the previous release (i.e. where the existing docker-compose.yml file is located).
  • Pull images associated with the services defined in the new docker-compose.yml file using the following command:
docker-compose pull
  • Build the images defined in the Docker files - note that this may not result in any changes:
docker-compose build
  • Recreate and start up the containers with the new images:
docker-compose up -d

2.x - Global Windows Installer upgrade process

  • Running an upgrade will overwrite the application.yml file for each service that contains configuration settings. If you have modified any of these files, your customizations should be moved to the service's corresponding application-default.yml file (which is never overwritten) before you start the upgrade.
  • The updater will only update the following Services (the SSO/Keycloak service is never updated):
    • Gateway
    • Service Registry
  • Any Node service must be updated separately.

Download the new media for the new release of Console and unzip it anywhere on the host server. Locate the Updater executable ConsoleWindowsUpdater-<version>.exe:

Double click the exe file to start the upgrade process. If your existing installation is located in any of the locations listed below, then the wizard will detect them - if that is the correct location, click Update to begin the upgrade process:

The upgrade process will then proceed:

The upgrade process is complete and you can continue with your work.

2.x - Java JAR installers upgrade process

  • Running an upgrade will overwrite the application.yml file for each service that contains configuration settings. If you have modified any of these files, your customizations should be moved to the service's corresponding application-default.yml file (which is never overwritten) before you start the upgrade.
  • It is NOT necessary to run an upgrade for the AIP-SSO-<version>.jar since this service never changes. If you do run an upgrade, all settings added in Keycloak (users/authentications/redirects etc.) will be lost and will need to be reconfigured.
  • Any Node service must be updated separately.

Download the new media for the new release of Console and unzip it anywhere on the host server. Each individual service needs to be upgraded separately: to do so, you need to run each installer in turn:

  • AIP-Service-Registry-<version>.jar
  • AIP-Gateway-<version>.jar

Double click each executable .JAR file as provided with the new installation media. If you are using OpenJDK or you are using a Linux environment, 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-Console-<version>.jar
  • In a Microsoft Windows environment, you can run the above command in the Command Prompt window (CMD) - ensure you launch the CMD window with elevated permissions (run as administrator).
  • In a Linux environment, you can run the above command in terminal.

The installation wizard will be displayed. If your existing installation is located in any of the locations listed below, then the wizard will detect them and the Upgrade an existing installation option will be selected automatically:

  • C:\%PROGRAMFILES%\CAST (Windows)
  • $HOME\CAST (Linux)

The Existing installation directory field will be auto populated with the existing installation location (you should ensure that this is the correct location). If the Install option is selected by default, this means that the installer is not able to detect an existing installation on the server - for example you installed it to a custom location. In this situation, you will need to manually select the Upgrade an existing installation option and enter the path to the existing installation in the Existing installation directory field.  Click Next to continue:

The upgrade process will start. Click Next when complete:

The upgrade process is complete:

2.x - Standalone upgrade process

  • Running an upgrade will overwrite the application.yml file that contains configuration settings. If you have modified this file, your customizations should be moved to the application-standalone.yml file (which is never overwritten) before you start the upgrade.

  • Any Node service must be updated separately.

Double click the executable .JAR file as provided with the new 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-Console-Standalone-<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 installation wizard will be displayed. If your existing installation is located in any of the locations listed below, then the wizard will detect them and the Upgrade an existing installation option will be selected automatically:

  • C:\%PROGRAMFILES%\CAST (Windows)
  • $HOME\CAST (Linux)

The Existing installation directory field will be auto populated with the existing installation location (you should ensure that this is the correct location). If the Install option is selected by default, this means that the installer is not able to detect an existing installation on the server - for example you installed it to a custom location. In this situation, you will need to manually select the Upgrade an existing installation option and enter the path to the existing installation in the Existing installation directory field.  Click Next to continue:

The upgrade process will start. Click Next when complete:

The upgrade process is complete:

1.x - Upgrade process

Perform a backup

CAST highly recommends that you backup the Console data folder before proceeding - this is so that a roll back can be actioned if necessary. This is achieved simply by copying the folder to another unrelated location.

Run the JAR installer

Double click the executable .JAR file as provided with the installation media. If you are using OpenJDK or you are using a Linux environment, 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-Console-<version>.jar
  • In a Microsoft Windows environment, you can run the above command in the Command Prompt window (CMD) - ensure you launch the CMD window with elevated permissions (run as administrator).
  • In a Linux environment, you can run the above command in terminal.

The installation wizard will be displayed. If your existing installation is located in any of the locations listed below, then the wizard will detect them and the Upgrade an existing installation option will be selected automatically:

  • C:\Users\%USER_NAME%\CAST (Windows)
  • C:\%PROGRAMFILES%\CAST (Windows)
  • $HOME\CAST (Linux)

The Existing installation directory field will be auto populated with the existing installation location (you should ensure that this is the correct location). If the Install option is selected by default, this means that the installer is not able to detect an existing installation on the server - for example you installed it to a custom location. In this situation, you will need to manually select the Upgrade an existing installation option and enter the path to the existing installation in the Existing installation directory field.  Click Next to continue.

If the Console package is installed on a Microsoft Windows operating system, the following screen will then be displayed offering you the option to start up the relevant Windows Service when the upgrade is complete. Click Next to continue:

The update process will start. Click Next when complete:

The update process is complete. If Console is installed as a Windows Service and you chose to start it on completion of the upgrade, the message Open Console in browser will be ticked. Click Done to close the wizard:

Post upgrade actions

Restart Console

If you did not choose to restart Console during the upgrade, re-run the start shortcut or restart the the Windows service(s) to restart Console.

Check access to Console

Browse to your Console URL http://<server>:8081, login to Console as you did previously and check:

  • that your configuration settings are correct (they should not have changed). New settings may also be visible.
  • that you are running the correct release of Console using the login > About option:

Note that at this point no Application data will be visible in Console since your Nodes are currently stopped (unless you are using the Console Standalone release which incorporates Console and one single node in one service).

What next?

Now move on to the next step in the update process: AIP Node package upgrade.