In-place component update for Linux via Docker

Overview

This guide provides instructions for running an in-place update to a new release of CAST Imaging, i.e. using com.castsoftware.imaging.all.docker  installed on Linux via Docker:

• on one single machine
• or via a distributed deployment (multiple machines)

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

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

In addition, the guide covers the update of your existing applications to a new Core release (the analysis engine installed on each of your analysis-node instances).

Supported update paths

Requirements

• Local administrator privileges (user in the sudoers list)
• All existing containers should be left running during the update (the update script will stop and restart them automatically)
• Sufficient local disk space for the new images
• A previous CAST Imaging installation should exist on the target machines
• In a distributed deployment scenario 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)
• It is not possible to change the TCP port number of any service, nor any HOSTNAME_xxx type installation variable as part of the update process.

Update process

Step 1 - Download and extract the installer

Download the release of the CAST Imaging installer  you want to update to and then extract the resulting ZIP file to any location on your local disk. For distributed deployments, repeat this download and extraction on each machine that requires updating. For example use curl and unzip:

curl -# -O -J "https://extend.castsoftware.com/api/package/download/com.castsoftware.imaging.all.docker/<release>?platform=linux_x64" -H "x-nuget-apikey: <api-key>" -H "accept: application/octet-stream"
unzip <zip_file> -d /home/my_user/CAST

Where:

• <release> is set to the target release you want to update to, for example 3.3.0-funcrel or 3.4.0-funcrel as listed in the Target release column in the Supported update paths table above
• <api-key> is set to your CAST Extend API key which can be obtained from https://extend.castsoftware.com/#/profile/settings 
• <zip_file> is the name of the file downloaded from CAST Extend: this will take the form com.castsoftware.imaging.all.docker.<release>.zip

Step 2 - Configure the installation directory

• Locate the configuration.conf file in the root of the extracted files
• Open it with a text editor (e.g., vi or nano)
• Verify that the INSTALL_DIR variable points to your existing CAST Imaging installation:

###################################################################################################
# Folder Contains CAST folders including shared, installation & castms folders 
###################################################################################################

INSTALL_DIR=/opt/cast

Step 3 - Make files executable

Make the update script executable on each machine where you’ll run it:

chmod +x cast-imaging-update.sh

If updating to CAST Imaging 3.4.x-funcrel or earlier (not necessary in 3.5.x-funcrel or later), on the machine where the imaging-viewer component is installed (either via the all or imaging-viewer commands), make the imagingsetup file (located in the cast-imaging-viewer folder at the root of the unzipped installation media) executable:

chmod +x cast-imaging-viewer/imagingsetup

Step 4 - Handle customized settings

Due to structural changes to the installer introduced in 3.5.0-funcrel (described in the Overview section), if you have customized any imaging-viewer related settings in files such as neo4j.conf, nginx.conf provided in /opt/cast/installation/imaging-viewer then you will need to re-apply these settings in specific way when updating to 3.5.0-funcrel or later from 3.4.x-funcrel or earlier. Any customizations in files stored in /opt/cast/installation/imaging-viewer will be lost post update (the physical files are removed during the update).

• First locate all custom settings in any files stored in /opt/cast/installation/imaging-viewer - this is important since the method of re-applying a setting differs depending on the file.
• Now re-apply the custom settings as described below.

Neo4j heap and transaction memory settings (neo4j.conf)

The following Neo4j options have been relocated in 3.5.0-funcrel and later. If you previously customized these in /opt/cast/installation/imaging-viewer/neo4j/configuration/neo4j.conf, they must now be configured in the /opt/cast/installation/imaging-viewer/.env file.

Previous location (neo4j.conf file):

server.memory.heap.initial_size
server.memory.heap.max_size
dbms.memory.transaction.total.max

New location (.env file):

NEO4J_HEAP_SIZE=           # Equivalent to both the "server.memory.heap.initial_size" and "server.memory.heap.max_size" options (sets the same value for both)
NEO4J_TRANSACTION_MEMORY=  # equivalent to "dbms.memory.transaction.total.max"

To re-apply these changes BEFORE proceeding with the update use the following

$ cd cast-imaging-viewer                      # navigate to folder at the root of the unpacked installer 
$ sudo nano .env                              # edit the .env file with your favourite editor and apply your customization, then exit editor

All other neo4j.conf customizations and any other configuration files

Any other options you customized in /opt/cast/installation/imaging-viewer/neo4j/configuration/neo4j.conf (beyond the three listed above) and any other options in other configuration files such as nginx.conf must be re-applied POST UPDATE (see Step 9 below) using the volume mapping method described in Managing config files.

Step 5 - Run the update

Navigate to the root of the extracted files and run the appropriate command based on your deployment type:

For a single machine deployment

./cast-imaging-update.sh all

For a distributed deployment

Run the appropriate command on each respective machine:

./cast-imaging-update.sh imaging-services
./cast-imaging-update.sh imaging-viewer
./cast-imaging-update.sh analysis-node
./cast-imaging-update.sh dashboards

Step 6 - Verify update success

• Check container status, all containers should show an “Up” status.

docker ps

• Verify services in the CAST Imaging admin panel:
  • Navigate to the Services settings page
  • Confirm all services show green status indicators:

Step 7 - Check Core release

CAST regularly publishes new releases to CAST Imaging Core - the analysis engine used by your analysis-node(s). These releases provide new features and updates which improve the value of the platform.

In a Linux via Docker/Kubernetes installation, CAST Imaging Core is provided as a Docker image as part of the analysis-node service, therefore it cannot be downloaded and installed manually (as is the case for a Microsoft Windows installation). Instead, when you update to a new release of CAST Imaging, you may also receive an updated release of the CAST Imaging Core image for your analysis-node component(s). The following table lists CAST Imaging installer releases and the release of CAST Imaging Core they include:

You should therefore always check the release of CAST Imaging Core installed in your analysis-node components after performing an in-place update to a new release of CAST Imaging. To do so, login to CAST Imaging with a user that has the default Admin profile or a custom profile with the Administrator role (see User Permissions) - then use the CAST Imaging Services settings UI. In the image below, the analysis-node is using CAST Imaging Core 8.4.3:

Then check the Applications settings UI. In the image below, we can see that the application “JEE” was most recently analyzed with Core 8.4.2 - this means that this application needs updating (see the next step below) before it can be re-analyzed. The other application has already been updated (or was created after the update):

Step 8 - Update application to new Core release

Following an update to CAST Imaging Core on your analysis-node(s) (see previous step) the next step is to perform an application update to ensure the new release of CAST Imaging Core will be used. This update process is performed in the CAST Imaging UI, using the Applications panel - see also Update.

All actions listed below are performed in the UI of your CAST Imaging instance:

• Login to CAST Imaging with a user that has the default Admin profile or a custom profile with the Administrator role - see User Permissions.
• Determine the Assessment Model upgrade strategy - in the majority of scenarios leave the setting at the default Preserve Assessment Model but enable new rules.
• Browse to the Applications panel - the Core upgrade available column will indicate all applications that need to be updated (those whose results were originally imported into CAST Imaging from CSV will not be eligible). Perform the application update by selecting an application then clicking the icon highlighted below:

• When the update is complete, check the Core version column to ensure that it is showing the new release:

• Finally, run a new analysis on the freshly upgraded application - this will also generate and make available new results (structural flaws and views):

What actions does CAST Imaging perform during an application update?

• An automatic backup of the Application’s Management, Analysis and Dashboard database schemas and its Delivery folder is performed automatically - see Backups for details.
• An update of the application schemas and the Delivery folder to the new CAST Imaging Core release.

What happens if the update fails?

If the update fails for any reason, an automatic roll back of the application update (schemas and delivery folder) will be performed using the backup taken automatically at the start of the update process.

What about extensions?

As a general rule, any extensions installed during the most recent analysis will NOT be automatically updated, even if a more recent version of an extension is available on CAST Extend  or in Extend Local Server.

Step 9 - Re-apply any customizations

As described in Step 4, when updating to 3.5.0-funcrel or later from 3.4.x-funcrel or earlier, you must re-apply any customizations previously made to files in /opt/cast/installation/imaging-viewer (see Step 4 - Backup customized settings).

The method for re-applying customizations depends on which options you modified.

Neo4j heap and transaction memory settings (neo4j.conf)

The following Neo4j options have been relocated in 3.5.0-funcrel and later. If you previously customized these in /opt/cast/installation/imaging-viewer/neo4j/configuration/neo4j.conf, they must now be configured in the /opt/cast/installation/imaging-viewer/.env file:

Previous location (neo4j.conf file):

server.memory.heap.initial_size
server.memory.heap.max_size
dbms.memory.transaction.total.max

New location (.env file):

NEO4J_HEAP_SIZE=           # Equivalent to both the "server.memory.heap.initial_size" and "server.memory.heap.max_size" options (sets the same value for both)
NEO4J_TRANSACTION_MEMORY=  # equivalent to "dbms.memory.transaction.total.max"

To apply these changes:

$ cd /opt/cast/installation/imaging-viewer    # navigate to installation folder    
$ sudo nano .env                              # edit the .env file with your favourite editor and apply your customization, then exit editor
$ sudo docker compose down                    # stop containers
$ sudo docker compose up -d                   # restart containers in detached mode
$ sudo docker ps                              # verify imaging-viewer containers are running

All other neo4j.conf customizations

Any other options you customized in /opt/cast/installation/imaging-viewer/neo4j/configuration/neo4j.conf (beyond the three listed above) must be re-applied using the volume mapping method described in Managing config files.

Other configuration files

If you modified other configuration files such as nginx.conf, re-apply those customizations as explained in Managing config files, which covers creating volume mappings to expose configuration files.

Done…

That’s it you’re done and your installation and applications are now up-to-date.