Installation prechecks

Understand the environment checks the CAST Imaging installer runs before an installation starts, and how to resolve a blocked installation

Overview

Available in ≥ 3.6.6-funcrel

Before it makes any change to your machine, the CAST Imaging installer validates the environment it is about to install into: the operating system, the software it depends on, the hardware resources available, the ports it needs, and the endpoints it must reach.

These checks run automatically every time you launch the installer and cannot be skipped. The results are grouped by area and reported in the installer output.

An example report can be found here and a snippet is shown below:

+-- PRECHECK REPORT - CAST IMAGING 3.x.x --------------------------------------+
| Host: ubuntu-2404-testing  |  Component: all  |  Mode: install  |  Rules: pr |
| Platform: LINUX | Date: 2026-08-25 15:28:00                                  |
| Runtime config: /home/cast/configuration.conf                       |
| Engine: docker                                                               |
+------------------------------------------------------------------------------+

+-- SYSTEM --------------------------------------------------------------------+
| WARN | Java JDK 17-25 present (Linux) | Java not found (PATH or JAVA_HOME)   |
|   -> Optional on Linux: only to decrypt encrypted (CRYPTED2) passwords.      |
|      Plain-text install works without Java.                                  |
+------------------------------------------------------------------------------+
| OK   | CPU architecture x86_64                  | x86_64                     |
|   -> ARM64 / aarch64 is not supported: CAST Imaging ships no ARM64 images.   |
+------------------------------------------------------------------------------+
| OK   | Supported Linux OS                       | ubuntu24.04                |
|   -> Validated only on RHEL/Rocky/Alma 8-9, Debian 11-12, Ubuntu             |
|      22.04/24.04.                                                            |
+------------------------------------------------------------------------------+
| OK   | glibc >= 2.28                            | 2.39                       |
|   -> Required by CAST containers. An older glibc means an OS too old         |
|      (RHEL/CentOS 7).                                                        |
+------------------------------------------------------------------------------+

The checks are scoped to the components you are installing, so a dashboards installation is not blocked by a requirement that only applies to imaging-viewer.
Where a check reads a value from your own configuration - a port, for example - the configured value is tested rather than the default.
Some groups are reported only where they apply to your configuration. The Database checks, for example, are run only where you have configured your own external PostgreSQL instance.

How results are reported

Updated in ≥ 3.6.7-funcrel

Each result is a single line, split into three columns by a | delimiter:

STATUS | Check name | Result detail

For example:

FAIL | Deploy folder readiness | cannot determine location (DEPLOY_FOLDER not set)
OK   | Deploy folder readiness | ready

For the literal message of every check that can fail, what it means and what you need to do about it, see the Precheck message reference.

Blocking failures and warnings

Each check reports one of two outcomes when it does not pass:

Outcome	Effect on the installation
Blocking failure	The installation does not start. Nothing on the machine has been changed, so resolve the reported condition and launch the installer again.
Warning	The installation continues. The capability associated with the check may not work, so review the message and decide whether to act before or after installing.

What is validated

System

The operating system and its edition, the CPU architecture, and the runtime prerequisites:

Only the x86_64 architecture is supported. ARM64/AArch64 hosts are rejected - no ARM64 images are shipped.
On Linux, glibc must be recent enough. A glibc older than the supported level indicates an operating system release that is too old.
On Microsoft Windows, a 64-bit JDK with JAVA_HOME set is mandatory, because CAST Imaging uses it to encrypt and decrypt passwords. On Linux the same JDK is optional and produces only a warning - it is needed there solely to decrypt encrypted passwords, and an installation using plain-text passwords does not require it.
Windows Server Core is not supported.

For the supported operating system releases and Java versions, see Software requirements.

Kernel

On Linux, the kernel file descriptor limit fs.file-max must be 65536 or above, because Neo4j and PostgreSQL each open a large number of file descriptors. A lower value produces a warning: raise it with $ sysctl -w fs.file-max=65536 and persist the change in /etc/sysctl.conf.

Software

The tools the installer depends on:

On Linux, the container engine you have chosen - Docker or Podman - must be installed, running and usable by the current user. Docker requires the Compose v2 plugin; the standalone docker-compose v1 command is not supported. Podman must be able to reach a compose provider.
The command-line tools the installer calls: curl is required on both platforms, while tar, unzip and ss produce warnings on Linux when missing.

For the supported engine releases, see Software requirements.

Filesystem and rights

On Linux, the installer verifies that it can write and execute where it needs to:

Check	Outcome if it fails
`INSTALL_DIR` is writable, directly or through `sudo`	Blocking
`INSTALL_DIR` is not mounted `noexec` - the installer runs helper binaries from it	Blocking
`/etc/cast-imaging` is writable - it holds the installation state and secrets	Warning, because it is created during installation where it does not exist
The installation package itself is complete	Blocking

Shared storage

Available in ≥ 3.6.7-funcrel

The shared, delivery and deploy folders hold the data that every analysis node works from, so the installer validates them before it installs any component that uses them. Where the paths come from depends on the component:

For an all or imaging-services installation, they are read from your installer configuration.
For an analysis-node, they are read from the configuration API of the Control Panel. The shared storage must therefore already exist: install imaging-services first, which creates it, then install the node.

The folders are reported as Shared folder (common-data), Delivery folder and Deploy folder, each with a matching free space check. Alongside the path, the report shows where it was resolved from - local (INSTALL_DIR), for example.

Check	Outcome if it fails
The path resolves from your configuration	Blocking
Where the path already exists, it is a directory rather than a file	Blocking
The account running the installer can browse, create, read, modify, rename and delete files there, and create and remove directories	Blocking
Free space meets the minimum for the folder	Blocking
Free space meets the size CAST recommends	Warning

For an all or imaging-services installation the folder does not have to exist yet: it is created during the installation, so permission to create and write in its parent is enough. Where that is the case, the check passes and reports not created yet, write access confirmed.

Two conditions are reported as warnings rather than failures, because the installation can still complete:

The folder is on local disk rather than shared storage. For a distributed deployment, point it at storage that every node can reach. This is not reported for a single machine all installation, where it does not apply.
On Linux, the path is not itself a mount point, so the installer cannot confirm that shared storage is behind it. Confirm the path is on a shared filesystem, an NFS mount for example, rather than a local directory carrying the same name.

On Microsoft Windows, use a UNC path such as \\server\share\imaging\deploy rather than a mapped drive letter such as Z:. A drive mapping exists only inside the logon session that created it, so a Microsoft Windows service running under a different session cannot see it. Where the installer cannot resolve a mapped drive letter at all the check is blocking; where it can, the check passes with a warning.

Where you keep a mapped drive, the mapping must be made available to the service account - see Software requirements.

For the folders themselves and their default locations, see Microsoft Windows file storage locations.

Hardware

The CPU, memory and free disk space available for the components being installed. Disk space is measured on /opt on Linux and on the system drive on Windows.

Memory and disk failures are blocking. CPU produces a warning only, so an under-provisioned processor does not prevent installation.

Each resource is measured against two values, a minimum and the size CAST recommends, and the report prints both alongside the value it measured. Each result is one of three states:

Result	Meaning	Outcome
`Recommended`	At or above the size CAST recommends	Pass
`Minimum only`	Meets the minimum, but not the recommended size	Warning, never blocking
`Below minimum`	Below the minimum	Blocking for memory and disk, warning for CPU

A Minimum only result never blocks the installation, but it is worth acting on before you go into production - disk in particular grows quickly with use. The report closes with a Resources sizing summary counting how many checks fell into each state.

See Hardware requirements and Disk space for the values.

Ports

Every port needed by the components being installed must be free on that host. Where you have changed a port in your own configuration, the installer tests your configured value rather than the default.

A port already in use is a blocking failure: either free the port, or install the component on a different host.

Once CAST Imaging is installed, service port numbers cannot be changed. See TCP ports for the full list of ports per component.

Database

Available in ≥ 3.6.7-funcrel

Where you use your own external PostgreSQL instance, the installer connects to it and verifies that it is ready to host CAST Imaging. The embedded instance provided by CAST on Linux/Podman is not tested this way - it is covered by the check on port 2285 described above.

These checks run only where a database host is resolved from your configuration:

On Linux/Podman, configuration.conf must declare DB_MODE=external and a non-empty DB_HOST.
On Microsoft Windows there is no DB_MODE setting, so the checks run whenever a host is resolved from CSS_INFOS in config-all.conf or config-<component>.conf.

Where no host is resolved, the whole group is skipped and the installation is not affected.

Check	Outcome if it fails	Platform
The instance accepts a connection and authenticates the configured user	Blocking	Both
PostgreSQL 15 or above	Blocking	Linux only
The login role is `SUPERUSER`, or holds both `CREATEDB` and `CREATEROLE`	Blocking	Both
The login role can `CREATE` on the `pg_default` tablespace	Warning	Both
The server encoding is `UTF8`	Warning	Both
No `control_panel` or `keycloak` schema already exists in the target database	Blocking	Both
No quoted mixed-case variant of those schemas exists, `"CONTROL_PANEL"` for example	Blocking	Both

A server encoding other than UTF8 can corrupt analysis data, so resolve that warning before you install rather than after.

The version check runs on Linux only, where it matches the release CAST provides as the embedded instance. On Microsoft Windows the release of your instance is not tested, but the supported releases apply on both platforms.

The checks are run with a psql client, which the installer locates in this order:

The directory given by the --psql-dir option or the CAST_PSQL_DIR environment variable.
On Microsoft Windows, the client shipped with the installer in tools\postgres, then any psql on the PATH.
On Linux, any psql on the PATH. Where none is found, the installer runs psql from a temporary alpine/psql container through Docker or Podman.

Where neither a psql client nor a container engine is available, the checks cannot run: the group reports a single warning, and the installation continues without the database being validated.

The password of the database user is passed to psql through the PGPASSWORD environment variable and never on the command line, so it does not appear in process listings or logs.

For the supported PostgreSQL releases and the schemas CAST Imaging creates, see Database requirements.

Network

The endpoints the installer and the installed product need to reach:

Target	Outcome if unreachable	Purpose
CAST Extend	Blocking	Downloading and synchronizing CAST extensions
The Control Panel of the central machine	Blocking	Allows `analysis-node`, `imaging-viewer` and `dashboards` to register with the Control Panel when they are installed on separate machines. Not checked for a single-machine installation
Docker Hub	Warning	Pulling the container images on Linux
The default Maven repositories - Maven Central, Jenkins, JBoss, Eclipse and Apache	Warning	Resolving build dependencies during analysis

Restricted and air-gapped environments

The network checks describe endpoints that a restricted environment is not expected to reach, and unreachable endpoints are normal there:

Where access to CAST Extend is not permitted, install the Extend Local Server to manage extensions on-premises.
Where the machine has no internet access, transfer the container images to it before installing - the air-gapped installation instructions are part of each Linux installation guide.
Where your organization mirrors the Maven repositories internally, the warning about the public repositories can be disregarded.
Where the machine has no psql client and no access to Docker Hub, the database checks cannot run and report a single warning. Install a PostgreSQL client on the machine to have your external instance validated before the installation starts.

Precheck message reference - every failure and warning message, and how to resolve it
Hardware - CPU, RAM, disk and TCP ports
Software - operating systems, Java, container engines and browsers
Database - PostgreSQL releases and configuration
Disk space - per-component disk usage and storage locations