Install on Linux with Podman

Overview

This guide covers the installation of CAST Imaging on Linux using Podman . It is intended for:

• Podman 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 images are pulled direct from https://hub.docker.com  during the installation. Alternatively you can configure the installer to function in offline mode.

Before embarking on the CAST Imaging installation, follow the items below to ensure that Podman is setup correctly.

Pre-install - Podman setup

Complete the following instruction on each machine where you will install a CAST Imaging component. These items must be completed before proceeding to the installation guides below.

Install podman-docker

podman-docker is a compatibility package that allows you to use Podman as a drop-in replacement for Docker: it creates a symbolic link from the docker command to podman. This means when you type docker run, docker build, or any other Docker command, you’re actually running Podman instead. This is required since the CAST Imaging installation script uses docker commands. You can install it as follows:

# Fedora/RHEL
$ sudo dnf install podman-docker

# Debian/Ubuntu
$ sudo apt install podman-docker

Check that the package has been correctly installed using a Docker command such as:

$ docker --version

You should see a response similar to:

Emulate Docker CLI using podman

Install a compose provider

CAST Imaging’s installer relies on docker compose to read and start containers and setup the required networks, volumes and file shares. Choose one of the following options:

Option A: Install podman-compose (recommended)

• Available through some package managers, or install via Python 3 and pip.
• See the official documentation .
• Ensure it’s installed globally to make it available to all users (including root)
• Check it’s installed using the following command:

$ which podman-compose

Option B: Install legacy standalone docker-compose

• This is the legacy 1.x release and is available in most package managers, for example:

# Fedora/RHEL
$ sudo dnf install docker-compose

# Debian/Ubuntu
$ sudo apt install docker-compose

Update registries.conf

Configure Podman to use Docker Hub as the default container registry. Create (if it does not exist) or update the following file:

$HOME/.config/containers/registries.conf

Add the following line to the file:

unqualified-search-registries = ["docker.io"].

Update containers.conf

Configure Podman to recognize your compose provider installed previously. First find your compose path (either podman-compose or docker-compose) using:

$ which podman-compose
# or
$ which docker-compose

Edit the containers.conf file using a text editor such as vi or nano (adapt the path to match your chosen compose provider):

/usr/share/containers/containers.conf

Update the compose_providers property to point to the relevant provider executable (the example below shows podman-compose):

compose_providers=["/usr/local/bin/podman-compose"]

Create a docker-compose wrapper

Create a wrapper script named docker-compose in:

$ sudo nano /usr/local/bin/docker-compose

Add the following content:

#!/bin/sh
podman compose "$@"

Make it executable:

chmod +x /usr/local/bin/docker-compose

Enable linger

The installation of CAST Imaging is supported as a non-root user (i.e. without the need to use sudo to elevate your user permissions). However, by default, all resulting containers are tied to the current user session (i.e. the user that performed the CAST Imaging installation), therefore when that user logs out, all containers stop. To remediate this behaviour and ensure that the CAST Imaging containers remain running when the associated user logs out, enable linger for the current user (update <username> to match the current user) which will allow services to run without an active session:

loginctl enable-linger <username>

Then check that it is correctly enabled:

loginctl show-user <username> | grep Linger
# Expected: Linger=yes

Step 1 - Choose your deployment scenario

A scenario defines which CAST Imaging components you install. All scenarios include imaging-services and require access to a database instance.

Advanced topology - Neo4j on a dedicated machine

For scenarios that include the Viewer (S1, S2, S3), you can run Neo4j on its own dedicated machine, separate from the Viewer services - useful for performance isolation and to update CAST Imaging independently of Neo4j. This deployment uses a tailored non-standard installation process, described in Neo4j on a dedicated machine.

Step 2 - Choose your deployment topology

A topology defines how components are distributed across machines:

• Single machine - all selected components on one host. Suitable for POC, testing, demo, or small production environments.
• Multi-machine - components distributed across dedicated hosts (or a mixed allocation). Recommended for production.

Step 3 - Go to your guide

Reference

For configuration references that apply across all Podman deployment scenarios, see the equivalent Docker reference pages:

• Installation variables
• Configuration examples
• Managing configuration files
• Managing environment variables
• Managing Docker Compose YAML files
• Reverse proxy configuration
• Setting up a shared folder (NFS)
• SSO service memory management