In-place component update

Overview

This guide provides instructions for running an in-place update to a new release for the following installed items:

• Microsoft Windows deployment of com.castsoftware.imaging.console : on one single machine or via a distributed deployment
• Linux via Docker deployment of com.castsoftware.imaging.all.docker : on one single machine or via a distributed deployment
• Kubernetes via Helm deployment on cloud services as scripted in com.castsoftware.castimaging-v3.kubernetessetup 

This process will update the following installed components and retain all existing data (applications, results, etc.):

• imaging-services
• imaging-viewer
• analysis-node
• dashboards

Supported update paths

Requirements

• Local administrator privileges:
  • Microsoft Windows: ability to Run as administrator
  • Linux via Docker: user in the sudoers list
• For Microsoft Windows, all existing services should be left running during the update.
• For Linux for Docker, CAST recommends stopping the containers before pulling new images.
• In a distributed deployment scenario (for both Microsoft Windows and Linux via Docker) all components MUST be updated to the same new release (i.e. you cannot update just the analysis-node component or just the imaging-services component)
• For both Microsoft Windows and Linux via Docker, it is not possible to change the TCP port number of any service, nor any HOSTNAME_xxx installation variables as part of the update process.

For Microsoft Windows, CAST recommends disabling Quick Edit mode in your command (CMD) window before running the update. This mode (if enabled) will pause the batch script if there is any interaction with the command window (e.g. a mouse click) during the process and will not re-start the script until a key is pressed:

Microsoft Windows deployment

Download the latest release of the installer  and unzip it anywhere on your local disk. You will need to download/unzip the installation media on each machine where a component is to be updated. Locate the relevant *.conf file at the root of the unzipped files and open with a text editor. For example:

• single machine installation: edit the config-all.conf file.
• distributed installation: edit the config-imaging-services.conf, config-imaging-viewer.conf or config-analysis-node.conf file to match the component installed on the current machine

Modify the appropriate configuration file to ensure that all parameters EXACTLY match those that were used in the same file when installing the previous release. You can find an explanation of the parameters in Microsoft Windows installation variables.

To run the in-place update, on the appropriate machine open a CMD window with elevated permissions (right click, Run as administrator) and execute the appropriate command from the root of the unzipped files, depending on the component(s) you are updating:

• Single machine
• Distributed deployment

  cast-imaging-update.bat package=all

  cast-imaging-update.bat package=imaging-services
  cast-imaging-update.bat package=imaging-viewer
  cast-imaging-update.bat package=analysis-node

The update process will then proceed. All existing data will be preserved. On completion you should check that:

• all Microsoft Windows services are up and running (the screenshot below is for a single machine installation):

• all services within the CAST Imaging Services “admin” panel are showing in green:

Finally, you may wish to update your applications to a new release of CAST Imaging Core if one is available - see In-place core and application update.

Linux via Docker deployment

The in-place update process is as follows:

1. Download the new installer
2. Locate Docker image tags in the new installer
3. Update existing .env files with new tags
4. Stop all running CAST Imaging containers
5. Start all CAST Imaging containers and prune unused images
6. Verify container status

Step 1 - Download the new installer

• Download the latest release of the installer 
• Unzip it anywhere on your local disk (see Installation on Linux via Docker for more information about how to use cUrl to download the installer).

Step 2 - Locate Docker image tags in new installer

• Navigate to the unzipped installer directory
• Open the configuration.conf file with a text editor:

vi configuration.conf
# or
nano configuration.conf

• Locate and note the Docker image tags at the end of the file (example below):

#### DO NOT CHANGE ####
IMAGING_SERVICES_VERSION=3.2.3
IMAGING_SERVICES_SSO_VERSION=3.2.3
IMAGING_DASHBOARDS_VERSION=3.2.3
IMAGING_VIEWER_VERSION=3.2.3
IMAGING_NODE_VERSION=3.2.3_core8.4.2
#####################################

Step 3 - Update existing .env file with new tags

For each installed component edit and update the corresponding .env file with the new Docker image tags provided in the 3.2.3-funcrel installer:

Step 4 - Stop all running CAST Imaging containers

Ensure that you perform the stop action in the order listed below:

# 1. imaging-viewer
cd /opt/cast/installation/imaging-viewer
docker compose down

# 2. imaging-dashboards
cd /opt/cast/installation/imaging-dashboards
docker compose down

# 3. imaging-node
cd /opt/cast/installation/imaging-node
docker compose down

# 4. imaging-services
cd /opt/cast/installation/imaging-services
docker compose down

Step 5 - Pull new images and start all CAST imaging containers

Ensure that you perform the actions in the order listed below:

# 1. imaging-services
cd /opt/cast/installation/imaging-services
docker compose pull
docker compose up -d

# 2. imaging-node
cd /opt/cast/installation/imaging-node
docker compose pull
docker compose up -d

# 3. imaging-dashboards
cd /opt/cast/installation/imaging-dashboards
docker compose pull
docker compose up -d

# 4. imaging-viewer
cd /opt/cast/installation/imaging-viewer
docker compose pull
docker compose up -d

Step 6 - Check the status of all running containers

Use the following command to check the status of the containers:

docker ps

Expected output should show all containers with “Up” status. A successful update action will result in a functioning CAST Imaging running the chosen release. All existing data will be preserved.

Step 7 - Update applications

Finally, you may need to update your applications to a new release of CAST Imaging Core (this is supplied in the analysis-node component) - see In-place core and application update.

Kubernetes via Helm

Clone the target release Git repository branch (i.e. matching the release of CAST Imaging you want to update to) of com.castsoftware.castimaging-v3.kubernetessetup . For example to clone the 3.3.0-cloud release branch use:

git clone -b 3.3.0-cloud https://github.com/CAST-Extend/com.castsoftware.castimaging-v3.kubernetessetup

Update any *.yaml file in the newly cloned branch with the exact same values as used in the currently deployed release of CAST Imaging, e.g.:

• values.yaml
• templates/console-authenticationservice-configmap.yaml

Run the Helm update script:

helm upgrade castimaging-v3 --namespace castimaging-v3

Login to CAST Imaging and check that all services within the Services “admin” panel are showing in green:

Finally, you may need to update your applications to a new release of CAST Imaging Core (this is supplied in the analysis-node component) - see In-place core and application update.