S3 - Viewer + Analysis, Multi-Machine (Docker)

Overview

This guide covers installing CAST Imaging with Viewer and Analysis capability across multiple machines using Docker. Users can run analysis and browse results through the Viewer interface.

What is installed:

When to use: Environments that require analysis and result viewing but do not need CAST Dashboards.

Requirements

Read and understand the following before starting:

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

Before you start

1. Air-gapped / offline environments: If your target machine does not have internet access, you must pre-download all required Docker images on an internet-connected machine and transfer them before running the installer. See the Air-gapped installation section below.

2. Extend Local Server: If your environment does not permit access to CAST Extend  over the internet, you will need to install the Extend Local Server separately before completing this guide.

3. Network connectivity: All machines must be able to communicate with each other over the network. Before starting, confirm:

   • The imaging-services machine is reachable from all other component machines
   • The database instance is reachable from all component machines
   • All required ports listed in Hardware requirements are open inbound on each machine

4. Shared folder: The /opt/cast/shared sub-folder (under your INSTALL_DIR variable) must be accessible in read/write mode from:

   • All analysis-node machines
   • The imaging-services machine (required from 3.6.0-funcrel)
   • Options for sharing (do not share the parent /opt/cast folder - share only /opt/cast/shared):
     • Mount the same network share (NAS or SAN) on all relevant machines
     • Share /opt/cast/shared from one machine and mount it on all others - see Setting up an NFS share on Linux for step-by-step instructions.

Step 1 - Download the installation media on each machine

Perform the following on each machine where you will install a component.

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:

• <version>: use latest for the most recent release, or a specific version such as 3.6.0-funcrel
• <api-key>: your CAST Extend API key (obtain 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 and 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
• cast-imaging-install-podman.sh
• cast-imaging-update.sh
• configuration.conf

Air-gapped installation

If the target machine(s) has no internet access, pull and export all required images on an internet-connected machine, then transfer and load them on the target machine(s) before running the installer.

On an internet-connected machine - pull and export each image:

$ docker pull <image>:<version>
$ docker save <image>:<version> -o <filename>.tar

Transfer all .tar archives to the target machine (secure copy or removable media).

On the target machine - load each image:

$ docker load -i <filename>.tar

Verify all images are available:

$ docker image ls

Required images:

After loading all images, open configuration.conf in a text editor and set:

OFFLINE_MODE=true

Step 2 - Configure the installation on each machine

Perform the following on each machine. All machines must use consistent values for shared variables (hostnames, database settings, install directory).

Locate configuration.conf at the root of the unzipped files and open it in a text editor (nano or vi). See Installation variables for a full reference.

General rules:

• Use forward slashes for all paths
• Do not use localhost, 127.0.0.1, or simple hostnames for _HOSTNAME variables
• Ensure the same variable values are used consistently across all machines*
• CAST recommends leaving port numbers at default values where possible

Note in particular:

Hostname variables

Configure the appropriate xxx_HOSTNAME variable on each machine to the FQDN or static IP of the machine hosting that component:

# Find the FQDN of the current machine
$ hostname -f

# Or find the IP address
$ hostname -I

INSTALL_DIR and shared folder

The INSTALL_DIR variable defines where configuration and data files are stored (default: /opt/cast).

You must ensure that /opt/cast/shared (or <INSTALL_DIR>/shared) is mounted and accessible in read/write mode on:

• All analysis-node machines
• The imaging-services machine (required from 3.6.0-funcrel)

See Setting up an NFS share on Linux for configuration steps.

DB_MODE

Use DB_MODE (on the machine running imaging-services for multi-machine mode) to control whether the embedded PostgreSQL Docker container is used or an external PostgreSQL instance:

• DB_MODE=embedded (default) - deploys a postgres container as part of the installation
• DB_MODE=external - uses an existing external PostgreSQL instance (configure the relevant DB_* variables)

See Installation variables and Database requirements for details.

Neo4j memory settings (optional, imaging-viewer machine only)

If you need to reduce Neo4j memory usage before installation (e.g. for a test deployment), edit the cast-imaging-viewer/.env file (on the imaging-viewer machine) and modify:

NEO4J_server_memory_heap_initial__size=<size>
NEO4J_server_memory_heap_max__size=<size>
NEO4J_dbms_memory_transaction_total_max=<size>

Default values are 12 GB each. See Customizing Neo4j for details.

Domain mapping (optional, imaging-services machine)

To isolate imaging-viewer results per domain in dedicated Neo4j databases, you can enable the domain/tenant mapping feature. CAST strongly recommends enabling this now, before any applications are onboarded - enabling it later in an existing installation causes irreversible loss of customizations (tags, saved views, post-it notes, custom objects).

Update the following variable in configuration.conf (on the imaging-services machine for multi-machine deployments):

IMAGING_DOMAIN_SYNCHRO_ENABLED=true

See Domain/tenant mapping feature for full details and prerequisites.

Firewall ports

Open all ports listed in Hardware requirements inbound on each machine to ensure:

• Users can access all CAST Imaging resources in their browser
• CAST Imaging components can communicate with each other correctly

Step 3 - Make the install script executable on each machine

On each machine:

Ensure the installation script is set to executable:

$ chmod +x cast-imaging-install.sh

Step 4 - Run the installation (in order)

Install components in the following sequence. Wait for each step to complete fully before proceeding to the next.

On the imaging-services machine - install first:

$ ./cast-imaging-install.sh imaging-services

On each analysis-node machine:

$ ./cast-imaging-install.sh analysis-node

On the Imaging-viewer machine:

$ ./cast-imaging-install.sh imaging-viewer

Step 5 - Verify the installation

On each machine, check that all containers are running:

$ docker ps

You should see 12 containers (or 11 if using an external PostgreSQL instance):

Full list:

Set permissions on each analysis-node machine

On each machine where you installed analysis-node, run:

$ chown -R 0:0 /opt/cast/shared

Replace /opt/cast/shared with the shared sub-folder of your INSTALL_DIR if you changed the default.

If a container fails to start, check its logs:

$ docker logs <container_name>

Data storage

All analysis data is stored under the INSTALL_DIR path (/opt/cast by default).

Database data for the embedded PostgreSQL instance is stored in Docker volume v3-db-data (view with docker volume ls). If you reinstall imaging-services and this volume already exists, it will be reused and existing applications will remain visible.

Step 6 - Initial startup configuration

Browse to:

http://<IMAGING_SERVICES_HOSTNAME>:8090

Log in using the default credentials: admin / admin

Configure the Licensing strategy. Choose one of:

• Named Application - each onboarded application requires its own dedicated license key
• Contributing Developers - a global license key based on the number of contributing developers

Configure CAST Extend settings and Proxy settings:

Verify that all components are available:

http://<IMAGING_SERVICES_HOSTNAME>:8090/admin/services

Step 7 - Configure authentication

Out-of-the-box, CAST Imaging uses Local Authentication (admin/admin) managed by Keycloak.

CAST recommends switching to your enterprise authentication system (LDAP or SAML) before onboarding applications. Access the Keycloak UI using the kcadmin account (or the value of KEYCLOAK_LOGIN_ADMIN_USER if customized during installation). See Authentication for full instructions.

Next steps

• Configure HTTPS access
• Configure a reverse proxy