Skip to content

Distributed installation (preview)

IRIS+ Professional can be installed using Ansible to automate the deployment process - This guide provides step-by-step instructions.

Tip

It is recommended to have a high speed network connection, as multiple GBs of data will be downloaded during installation.

It is recommended to visit the hardware and software prerequisites page to learn more about deployment options and hardware requirements.

Docker credentials required

You will need valid Docker credentials to proceed with the installation. Make sure you have your Docker username and password ready, as they will be required in later steps. If you do not have these credentials, please contact sales@irisity.com to obtain them before continuing.

Installation via Ansible involves two node types:

  • Control Node: The control node is where you install Ansible to manage other machines. It runs the playbooks as well as the coordinate operations.

  • Target Nodes: The machines Ansible manages. They receive and execute tasks sent by the control node. The target node can be classified by deployment type, which can be standalone, core or indexer. In a cluster there must be at least 1 core node and 1 indexer node or a standalone. The indexer nodes can be scaled horizontally.

You must have SSH capability from the Control node to the Target nodes.

Info

A single machine can function as both the control node and a target node in an Ansible setup. This means you can install Ansible on this machine and include it in the inventory, allowing it to manage itself along with other nodes. This configuration enables the machine to execute Ansible tasks on itself as well as on other target systems.

Prerequisites on the target node(s)

Installation will require you to have sudo rights.

The system can be installed on any OS that supports docker, however the recommended OS is Ubuntu 22.04. The steps described below assume an Ubuntu 22.04 installation.

Logging

Logging is based on your journald configuration. Changes to parameters such as log retention time and disk space usage can be made by modifying the journald configuration.

1. System update

Make sure your system is up-to-date.

1
2
3
sudo apt update && \
sudo apt upgrade -y && \
sudo reboot

2. Add Docker GPG key and repository

1
2
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg && \
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3. Standalone and Indexer nodes only: Add NVIDIA Docker GPG key and repository

1
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

4. Standalone and Indexer nodes only: Add the NVIDIA container toolkit repository

1
echo 'deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://nvidia.github.io/libnvidia-container/stable/deb/$(ARCH) /' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

5. Install required dependencies

Standalone, indexer node: 

1
2
3
sudo apt update && \
sudo apt -y install ca-certificates curl software-properties-common docker-ce docker-ce-cli docker-compose-plugin containerd.io python3-pip python3-venv nvidia-driver-550 nvidia-docker2 openssh-server && \
sudo reboot

Core node: 

1
2
3
sudo apt update && \
sudo apt -y install ca-certificates curl software-properties-common docker-ce docker-ce-cli docker-compose-plugin containerd.io python3-pip python3-venv openssh-server && \
sudo reboot

Installation steps on the control node

1. Install Ansible

Note that the installer requires Ansible to be on the control node.

1
2
3
sudo apt -y install sshpass python3-pip && \
pip3 install --user ansible jmespath && \
source ~/.profile

2. Download and extract the Ansible installer

1
2
3
4
5
 wget https://professional.irisity.com/docs/r22/ansible_playbook.tar -P /tmp && \
 mkdir -p ~/ansible-installer && \
 tar -xvf /tmp/ansible_playbook.tar -C ~/ansible-installer && \
 rm /tmp/ansible_playbook.tar && \
 cd ~/ansible-installer

3. Set up the Ansible inventory

Info

If your control node and target node are both on a single machine, 127.0.0.1 can be used for ansible_host.

Set up the Ansible inventory file under inventories/all.yaml.

all:
  hosts:
    YOUR_TARGET_NODE_NAME_HERE:
      ansible_host:  # TARGET_NODE_IP_HERE
      ansible_port:  # TARGET_NODE_PORT_HERE

  • Replace YOUR_TARGET_NODE_NAME_HERE with the name of your target node.

  • ansible_host: The IP address or domain name of the target node.

  • ansible_port: The SSH port number of the target node.

Tip

You can check connectivity via the nc command:

nc -z TARGET_NODE_IP_HERE TARGET_NODE_PORT_HERE && echo "Connectivity succeeded!" || echo "Connectivity failed!"

4. Set up the Target node specific variables

Create a directory for node/host specific variables in the document root of the installer and copy the node class specific example variables:

mkdir -p host_vars/YOUR_TARGET_NODE_NAME_HERE && \
cp examples/NODE_TYPE/vars.yaml distributed/host_vars/YOUR_TARGET_NODE_NAME_HERE/
The NODE_TYPE represents one of the selected node class: standalone, core or indexer.

Fill in host_vars/YOUR_TARGET_NODE_NAME_HERE/vars.yaml:

  • The docker_username and docker_password variables.

Contact sales@irisity.com for docker credentials.

  • init_sysadmin_email: The initial system administrator email address.
  • init_sysadmin_pwd: The initial system administrator password.

Tip

You can specify the root folder for video storage and the message broker data directory in host_vars/YOUR_TARGET_NODE_NAME_HERE/vars.yaml using the variables below:

  • volume_videostorage_folder (example: volume_videostorage_folder: '/var/data/vs')

  • volume_kafka_folder (example: volume_kafka_folder: '/var/data/kafka')

HTTPS settings

You can enable HTTPS connectivity using the https_enabled variable in host_vars/YOUR_TARGET_NODE_NAME_HERE/vars.yaml. If you need HTTPS connectivity, select the 'certificate_type':

  • In the case of 'official_ca', our reverse proxy will attempt to generate a Let's Encrypt signed certificate.

  • It is required to fill in the domain variable as well.

  • An automatic renew process included.

  • The domain's A record must be a public IPv4 address that points to your target node.

  • The domain must be publicly accessible due to HTTP-01 validation for certificate generation and automatic renewal process.

  • In the case of 'self_signed', our reverse proxy will attempt to generate a self signed certificate.

  • It is required to fill in the domain variable as well.

  • An automatic renew process included.

  • In the case of 'custom', you can provide your own certificate and private key pair.

  • It is not required to fill in the domain variable.

  1. Create a directory relative to the installer's docroot:

    mkdir -p host_files/YOUR_TARGET_NODE_NAME_HERE/ssl

  2. Place the following in the created directory:

    • certificate.crt which represents the certificate.

    • certificate.key which represents the private key.

Core specific variables

metadata_broker_ip specifies the network endpoint (IP address) of the core machine that the indexer node must be able to access for proper operation.

primary_indexer_ip specifies the network endpoint (IP address) of the indexer machine that the core node must be able to access for proper operation.

5. Start the installation

Start the Ansible playbook for installation:

1
ansible-playbook distributed/start.yaml -t install

You will be prompted for your SSH and sudo passwords for authenticating the target node.

SSH password:
BECOME password[defaults to SSH password]:

Tip

If you can authenticate via an SSH private key, you can leave the value of SSH password blank. If there is no password requirement for sudo commands, you can leave the value of BECOME password blank as well.

Note that installation may take up to 30 minutes.

Creating a backup

Ensure you have met all requirements as outlined before proceeding.

Start the Ansible playbook for backup creation:

1
ansible-playbook distributed/start.yaml -t create-backup

You will be prompted for your SSH and sudo passwords for authenticating the target node.

SSH password:
BECOME password[defaults to SSH password]:

Tip

If authenticating via private SSH key is possible, you can leave the value of SSH password blank. If there is no password requirement for sudo commands, you can leave the value of BECOME password blank as well.

The Ansible playbook will stop all services related to IRIS+ Professional, create a backup, and then restart the services.

Listing available backups

Ensure you have met all requirements as outlined before proceeding.

Start the Ansible playbook for backup creation:

1
ansible-playbook distributed/start.yaml -t list-backups

You will be prompted for your SSH and sudo passwords for authenticating the target node.

SSH password:
BECOME password[defaults to SSH password]:

Tip

If authenticating via private SSH key is possible, you can leave the value of SSH password blank. If there is no password requirement for sudo commands, you can leave the value of BECOME password blank as well.

Restoring a backup

Ensure you have met all requirements as outlined before proceeding.

The restoration process will result in data loss.

Start the Ansible playbook for restoring:

1
ansible-playbook distributed/start.yaml -t restore

The restore process will revert to the most recent backup by default. If you want to restore from a specific backup, you can provide the full path to the desired backup file.

1
ansible-playbook distributed/start.yaml -t restore -e "backup_source_file=/path/to/backup/file"

The restore process will first create a backup of the current setup before starting the restore. If you want to skip this backup, you can use the skip-backup tag:

1
ansible-playbook distributed/start.yaml -t restore,skip-backup -e "backup_source_file=/path/to/backup/file"

You will be prompted for your SSH and sudo passwords for authenticating the target node.

SSH password:
BECOME password[defaults to SSH password]:

Tip

If authenticating via private SSH key is possible, you can leave the value of SSH password blank. If there is no password requirement for sudo commands, you can leave the value of BECOME password blank as well.

During the restore process, the Ansible playbook will stop all related services, create a backup, and re-start the services.