Installation on Linux via Docker

Overview

This guide covers the installation of CAST Imaging on Linux using Docker. It’s intended for:

• Docker running on Linux operating systems
• new installations (for updates to existing installations, see In-place component update)

The installation package com.castsoftware.imaging.all.docker  includes an installation script and configuration files. All Docker images are pulled direct from https://hub.docker.com  during the installation.

Components and installation options

Available components

The following components are provided as Docker images:

• imaging-services including:
  • Database instance (additional remote database instances can be added post install)
• imaging-viewer
• analysis-node includes CAST Imaging Core ≥ 8.4
• dashboards (optional - not mandatory)

Installation methods

The installation is actioned via a script (.sh file) which supports two deployment approaches and provides flexibility:

• Standalone mode (single machine)
  • All components on one machine in a single Docker instance
  • Ideal for POCs or testing purposes, or small production deployments
• Distributed mode (multiple machines)
  • Components distributed across multiple machines
  • Recommended for production environments

Installation commands and components

The installation script can be run with different options to achieve the configuration you require:

Requirements

• Hardware requirements
• Software requirements
• Database requirements
• Disk space requirements

Installation process

Step 1 - Determine your installation method

• Standalone mode (Single machine) - connect to the machine and proceed to Step 2. Ensure that your machine has sufficient resources to run all components: see Requirements.
• Distributed mode (Multiple machines) - identify which machine will run the imaging-services component (this must be installed first). Connect to this machine and then proceed to Step 2.

Step 2 - Download the installation media

Download the installer using curl:

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

Where:

• -#: enables a download progress bar.
• -O: (--remote-name) ensures the file is downloaded and saved to the current folder using the same name as the remote file.
• -J: (--remote-header-name) ensures the -O option uses the server-specified Content-Disposition filename instead of extracting a filename from the URL. If the server-provided filename contains a path, that is stripped off before the filename is used.
• <version>: use latest to download the most recent release, or specify the specific release, e.g., 3.2.0-funcrel.
• -H: (--header) defines the additional header to include in information sent.
• <api-key>: your CAST Extend API key (obtain this from https://extend.castsoftware.com/#/profile/settings )

Example for latest release:

curl -# -O -J "https://extend.castsoftware.com/api/package/download/com.castsoftware.imaging.all.docker/latest?platform=linux_x64" -H "x-nuget-apikey: a9999a9a-c999-999d-999b" -H "accept: application/octet-stream"

Unzip the resulting ZIP file anywhere on your local disk. The following files/folders will be created:

• cast-imaging-dashboards (folder)
• cast-imaging-node (folder)
• cast-imaging-services (folder)
• cast-imaging-viewer (folder)
• tools (folder)
• cast-imaging-install.sh (file)
• configuration.conf (file)
• image_infos.txt (file)

Step 3 - Configure your installation

First locate the configuration.conf file at the root of the unzipped files and open it in a text editor such as nano or vi and prepare to modify the configuration variables within it.

Important configuration guidelines

• Use forward slashes for all paths
• Do not use localhost, 127.0.0.1, or simple hostnames for _HOSTNAME variables
• CAST recommends leaving port numbers at default values where possible
• See Configuration examples for more information about how to configure your installation in distributed mode

xxx_HOSTNAME variables

Locate the following variables in the configuration.conf file (they determine the hostname for each CAST Imaging component):

• IMAGING_SERVICES_HOSTNAME
• IMAGING_VIEWER_HOSTNAME
• IMAGING_NODE_HOSTNAME
• IMAGING_DASHBOARDS_HOSTNAME

For each variable, configure the appropriate FQDN (fully qualified domain name) or static IP address (use hostname -f (FQDN) or hostname -I (IP address) to determine this):

• Standalone mode (Single machine): all variables must be identical - i.e. the FQDN/IP address of the host machine on which you are running the installation.
• Distributed mode (Multiple machines): enter the FQDN/IP address of the machine that will host that particular component. Ensure that machines can communicate with each other over the network, whichever option you use (FQDN/IP address).

INSTALL_DIR variable

Locate the INSTALL_DIR variable in the configuration.conf file: this defines where the various properties/yaml files for each component will be stored (default: /opt/cast). During the installation process, this path will be populated with three sub folders, core, installation and shared:

• Standalone mode (single machine): there is nothing further to change. All relevant files will be available in this path.
• Distributed mode (multiple machines):
  • where you will install multiple analysis-node components, you must ensure that the /opt/cast/shared sub-folder is accessible (in read/write mode) to ALL analysis-node components
  • DO NOT “share” the parent folder /opt/cast
  • Options for sharing:
    • mount the same network share (e.g. on a NAS or SAN) on all analysis-node machines
    • share /opt/cast/shared from one analysis-node machine and then mount this on all other analysis-node machines

Step 4 - Make files executable

Make the installation script (cast-imaging-install.sh) executable on each machine where you’ll run it:

chmod +x cast-imaging-install.sh

If installing the imaging-viewer component (via all or imaging-viewer commands), also 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 5 - Run the installation

Scenario 1 - Standalone mode (Single machine)

Run the following command:

./cast-imaging-install.sh all

Verify the installation by checking Docker containers (you should see 12 containers):

docker ps

Scenario 2 - Distributed mode (Multiple machines)

On each machine:

• download and unzip the installation media
• ensure the configuration.conf file is correctly configured for the component(s) you want to install
• ensure the installation script file is executable
• run the appropriate installation command on each machine for the component you would like to install.

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

Verify the installation by checking Docker containers on each machine:

docker ps

Expected container counts:

Step 6 - Post installation tasks

Set permissions on persistent volumes

For each analysis-node you have installed (including via the all command) you must execute the following command to ensure that the root user has access to the persistent volumes shared with the analysis-node container:

chown -R 0:0 <root_data_folder>

Where:

• <root_data_folder> points to the root of the “shared” data folder. By default this is set to /opt/cast/shared.
• 0:0 is equivalent to the “root” user.

Open firewall ports

Ensure port 8090 (TCP) is open inbound on the machine hosting the imaging-services component to:

• Allow users to access CAST Imaging in their browsers
• Enable communication between CAST Imaging components in distributed installations

Step 7 - Initial start up configuration

• When the install is complete, browse to the URL:

http://IMAGING_SERVICES_HOSTNAME:8090

• Login using the default local admin/admin credentials
• Configure the Licensing strategy. Choose either a Named Application strategy (where each application you onboard requires a dedicated license key entered when you perform the onboarding), or a Contributing Developers strategy (a global license key based on the number of users):

• Configure CAST Extend settings / Proxy settings:

• Verify component availability via the following URL and ensure that you see at least one analysis-node, dashboards and imaging-viewer:

http://IMAGING_SERVICES_HOSTNAME:8090/admin/services

Step 8 - Configure authentication

By default, CAST Imaging is configured to use Local Authentication via a simple username/password system. Default login credentials are provided (admin/admin) with the global ADMIN profile so that installation can be set up initially.

CAST recommends configuring CAST Imaging to use your on-premises enterprise authentication system such as LDAP or SAML Single Sign-on instead before you start to onboard applications. See Authentication for more information.

What is installed?

Containers

The following Docker containers will be created and are set to start automatically:

Data storage

All analysis data will be stored in the path you defined in the configuration.conf file for the INSTALL_DIR variable (/opt/cast by default).

In addition, database data for the PostgreSQL instance provided with the imaging-services component is stored in a Docker volume called v3-db-data - this can be viewed using the docker volume ls command. Note that if you re-install the imaging-services component and this volume exists it will be reused, therefore any existing applications may be visible in CAST Imaging.

Troubleshooting

If a container fails to start, check the logs:

docker logs <container_name>

Uninstall process

Complete Docker clean-up

To action a full clean-up:

• run the following Docker commands
• delete the installer ZIP file
• delete the unzipped installation files/folder
• delete all files/folders in /opt/cast/ (default install path) - this will also delete all analysis data.

# Stop all containers
docker stop $(docker ps -a -q)

# Remove all containers
docker rm $(docker ps -a -q)

# Remove all images
docker rmi $(docker images -a -q)

# Remove all build cache
docker builder prune -a

# Remove unused networks
docker network prune

# Check remaining data
docker system df -v

# Remove data volumes for analyses and the database instance (CAUTION: cannot be reversed)
docker volume prune -a

Selective CAST Imaging clean-up

To remove only CAST Imaging related items:

• run the following Docker commands
• delete the installer ZIP file
• delete the unzipped installation files/folder
• delete all files/folders in /opt/cast/ (default install path) - this will also delete all analysis data.

# Stop imaging-services containers
cd /opt/cast/installation/imaging-services
docker compose down

# Stop analysis-node container
cd /opt/cast/installation/imaging-node
docker compose down

# Stop imaging-viewer containers
cd /opt/cast/installation/imaging-viewer
docker compose down

# Stop dashboards containers
cd /opt/cast/installation/imaging-dashboards
docker compose down

# Remove images
docker images | grep $servicename | awk '{print $3}' | xargs -I {} docker rmi -f {}
docker image prune