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 - however you can alternatively configure the installer to function in “offline mode”.
Warning
CAST does not support cross-platform installations, i.e. some CAST Imaging components on Linux/Docker and other components on Microsoft Windows, except where a PostgreSQL instance installed on Linux/Docker is being used with CAST Imaging installed on Microsoft Windows.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)Available in ≥ 3.3.x-funcrel
Installation methods, scenarios and options
The installation is actioned via a script (.sh
file) which supports various deployment approaches and provides flexibility:
- Single machine mode, all components
- All components on one machine in a single Docker instance
- Ideal for POCs or testing purposes, or small production deployments
- Distributed mode, all components (multiple machines)
- All components distributed across multiple machines
- Recommended for production environments
- Read-only/standalone modes
Available in ≥ 3.4.x-funcrel
- Read-only deployments providing end-user access to CAST Dashboards or to “viewer” results
- No analysis capability
- Two available deployment options, either all components on one single machine or across two machines:
- CAST Dashboards:
imaging-services
anddashboards
components - Viewer
imaging-services
andimaging-viewer
components
- CAST Dashboards:
Single machine mode, all components
All components on one single machine:
Install Command | Components installed | Containers created |
---|---|---|
all |
All components. If you choose this option, you must ensure that your machine has sufficient resources to run all components: see Requirements. |
|
Distributed mode, all components
All components distributed across multiple machines:
Install Command | Components installed | Containers created |
---|---|---|
imaging-services |
|
|
imaging-viewer |
Requires:
|
|
analysis-node |
Requires:
|
|
dashboards |
Available in ≥ 3.3.x-funcrel
Requires:
|
|
Note
- CAST Imaging Core ≥ 8.4 is included in the
all
andanalysis-node
commands as a Docker image and therefore does not need downloading or installing manually. Release Notes for this component are provided in com.castsoftware.imaging.core. - CAST's on premises Extend Local Server (used where it is not possible to access CAST Extend over the internet) is not included and must be installed separately if needed.
Read-only/standalone modes
For end-user results consultation without analysis capabilities, you can deploy CAST Imaging in “read-only” mode specifically for the following two use cases:
- CAST Dashboards (Engineering/Management/Security) only
- “viewer” only
This type of deployment is designed for environments where:
- No analysis is performed locally
- Users only need to view results through CAST Dashboards or the “viewer”
- Application analysis occurs on a separate, dedicated CAST Imaging installation
This can be achieved by installing only the following components either on two separate dedicated machines or one single machine:
For CAST Dashboards:
imaging-services
(must always be installed first)dashboards
(requires access to theimaging-services
component)
For “viewer”:
imaging-services
(must always be installed first)imaging-viewer
(requires access to theimaging-services
component)
- Both components require access to any additional database components used for results storage.
- You can find out more about the workflow involved in managing read-only/standalone mode in Standalone deployment workflow.
- It is not possible to add additional components (e.g. an
analysis-node
) to an existing Read only/Standalone deployment - i.e. once installed, the deployment cannot be changed. - Certain settings and options in the CAST Imaging UI will not be available when using read-only/standalone mode.
Requirements
Installation process
Step 1 - Determine your installation method
- Single machine mode, all components or read-only 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, all components or read-only 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 - Obtain 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>
: uselatest
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)
Running the installer without an internet connection
The installer automatically downloads all required Docker images from Docker Hub during installation. For air-gapped environments without internet access, you can manually download and transfer the images to target machines using the URLs listed below and then set the installer to use local images rather than fetching them from Docker Hub.
CAST Imaging component | Image name | URL |
---|---|---|
imaging-services |
Gateway | https://hub.docker.com/r/castimaging/gateway |
imaging-services |
Control Panel | https://hub.docker.com/r/castimaging/admin-center |
imaging-services |
SSO Service | https://hub.docker.com/r/castimaging/sso-service |
imaging-services |
Auth Service | https://hub.docker.com/r/castimaging/auth-service |
imaging-services |
Console | https://hub.docker.com/r/castimaging/console |
dashboards |
Dashboards | https://hub.docker.com/r/castimaging/dashboards |
analysis-node |
Analysis Node | https://hub.docker.com/r/castimaging/analysis-node |
imaging-viewer |
ETL | https://hub.docker.com/r/castimaging/etl-service |
imaging-viewer |
AI Service | https://hub.docker.com/r/castimaging/ai-service |
imaging-viewer |
API Service | https://hub.docker.com/r/castimaging/imaging-apis |
imaging-viewer |
Viewer Server | https://hub.docker.com/r/castimaging/viewer |
imaging-viewer |
Neo4j | https://hub.docker.com/r/castimaging/neo4j |
- Download (i.e. using
docker pull
) the correct image release for your installation by using the appropriate tag. Thelatest
tag fetches the most recent release and is recommended. - Convert the images to
.tar
file using docker image save and then transfer the images to the relevant air-gapped machine(s). - Convert the
.tar
files back to images using docker image load on the relavant machine(s). - Locate the
configuration.conf
file at the root of the unzipped files (on each relevant machine) and open it in a text editor such asnano
orvi
and setOFFLINE_MODE=true
to ensure that offline mode is enabled. - Proceed with the installation process detailed below.
Step 3 - Configure your installation
configuration.conf file
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.
- 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):
- Single machine mode, all components: configure only the
IMAGING_SERVICES_HOSTNAME
using the FQDN/IP address of the host machine on which you are running the installation. All otherxxx_HOSTNAME
variables can be left blank. - Read-only mode, single machine: configure only the
IMAGING_SERVICES_HOSTNAME
variable and then either theIMAGING_VIEWER_HOSTNAME
or theIMAGING_DASHBOARDS_HOSTNAME
(depending on your deployment scenario) using the FQDN/IP address of the host machine on which you are running the installation. - Distributed mode, multiple machines / Read-only mode, multiple machines: configure the appropriate
xxx_HOSTNAME
variable using the FQDN/IP address of the machine that will host that particular component. Ensure that machines can communicate with each other over the network.
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
:
- 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 ALLanalysis-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 oneanalysis-node
machine and then mount this on all otheranalysis-node
machines
- mount the same network share (e.g. on a NAS or SAN) on all
- where you will install multiple
- All other deployment modes: there is nothing further to change. All relevant files will be available in this path.
Open firewall ports
- Distributed mode, multiple machines / Read-only mode, multiple machines - you should ensure that all ports listed in Hardware requirements are opened inbound on the relevant machine to ensure that:
- your users will be able to access all CAST Imaging resources in their browser
- CAST Imaging components can communicate correctly with each other correctly
- Single machine mode, all components / Read-only mode, single machine - only port
8090
(TCP) should be opened inbound if you or your users need to access CAST Imaging from another machine on the network.
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 - Single machine mode, all components
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
cast-imaging-install.sh
andimagingsetup
file ares executable as appropriate - run the appropriate installation command on each machine for the component you would like to install, ensuring that the
imaging-services
component is always installed first
./cast-imaging-install.sh imaging-services
./cast-imaging-install.sh imaging-viewer
./cast-imaging-install.sh analysis-node
./cast-imaging-install.sh dashboards
Note
- You can install any number of
analysis-node
components on dedicated machines to load balance your analysis requirements - You must only install
imaging-services
,imaging-viewer
anddashboards
once in your network
Scenario 3 - Read only modes
The installation process is similar to that described in Scenario 2 - Distributed mode (multiple machines):
- download and unzip the installation media on each machine on which you want to install a component (you can use two dedicated machines or one single machine)
- ensure the relevant
*.conf
file on each machine is correctly configured for the component(s) you want to install - if you are installing the “CAST Dashboards” read-only mode, modify the
cast-imaging-services/.env
file and set theDASHBOARD_STANDALONE_ENABLED
variable totrue
- if you are installing the “viewer” read-only mode, ensure the
cast-imaging-install.sh
andimagingsetup
file are executable - run the following commands ensuring that the
imaging-services
component is always installed first:
For CAST Dashboards:
./cast-imaging-install.sh imaging-services
./cast-imaging-install.sh dashboards
For “viewer”:
./cast-imaging-install.sh imaging-services
./cast-imaging-install.sh imaging-viewer
Step 6 - Post installation tasks
Verify containers
Verify the installation by checking Docker containers on each machine:
docker ps
Expected container counts:
Command | No. of containers |
---|---|
imaging-services |
6 |
imaging-viewer |
5 |
analysis-node |
1 |
dashboards |
1 |
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.
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 - not available for a “read-only” deployment), or aContributing Developers
strategy (a global license key based on the number of users):
- Configure CAST Extend settings / Proxy settings (not required when installing a “read-only” deployment):
- Verify component availability via the following URL and ensure that you see at least one
analysis-node
,dashboards
andimaging-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:
Command | Container (Port) / Base OS |
---|---|
imaging-services |
|
imaging-viewer |
|
analysis-node |
|
dashboards |
|
sso-service
container (part of the imaging-services
) is set by default to use 70% of the available container memory. See sso-service memory management for more information about adjusting this.
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