Deploying the Host Agent on Linux

Introduction

This section explains how to install the Host Agent on Linux. ScaleOut Digital Twins™ requires a Host Agent installed on every server in the ScaleOut StreamServer in-memory data grid (called a host here). This agent allows the ScaleOut Digital Twins UI to communicate with the hosts. In addition to communicating with the UI, the Host Agent includes runtime environments for real-time digital twin models written in Java and JavaScript.

Note

Please see Deploying the ScaleOut Digital Twins UI for details on installing the UI that uses this Host Agent.

Components

The installer script installs the following components on each ScaleOut StreamServer host:

A system service/daemon (called the Agent Service) used by the ScaleOut Digital Twins UI to deploy real-time digital twin models to the in-memory data grid
Java digital twin model runtime components

Prerequisites

Prior to installing the DT Host Agent, please install the following third-party software on each cluster host:

PowerShell version 7 or later, if required. You can find and follow the PowerShell installation steps for your Linux distribution here.
If not already installed, Python version 3.x, which is used by the installation script
ScaleOut StreamServer, which hosts the in-memory data grid. The ScaleOut StreamServer service needs to be reachable from the management server. For initial, single-server testing before production use, ScaleOut StreamServer can be installed on the management server instead of a separate cluster of hosts.
Note

If you choose to deploy the ScaleOut Digital Twins UI to a different network than the cluster of ScaleOut StreamServer hosts, additional steps must be taken to ensure that the UI can communicate with the Host Agent:
- Ensure that the following TCP ports on your cluster are opened to the network where the UI is deployed:
  7700: Host Agent ports.
  
  720-724: ScaleOut StreamServer ports.
- Configure each instance of the ScaleOut service to advertise its public IP address as the gateway IP address for each host. The service’s gateway_ip parameter is used to specify the public IP address of the host. ScaleOut StreamServer’s Management Tools can be used to set the gateway IP.

Installation Steps

First, download the Host Agent installation script from ScaleOut Software here and extract the files into your desired directory. (We recommend that you install into /srv/sossdt. If you have already installed the ScaleOut Digital Twins UI component on this system, it is recommended that you install the Host Agent into the same directory. This directory (e.g. /srv/sossdt) will be referred to as the installation directory. It will be used during installation and by components of the Host Agent after their deployment.

Note

When installing both the Host Agent and the ScaleOut Digital Twins UI on a single server, the installation files from both packages can be extracted into the same installation directory. Because both packages share two files, the operating system may prompt you to allow these files to be replaced when installing the second package.

Prior to running the installation script, please complete the following configuration step.

Edit the digital_twin_service_configuration.json file in the data subdirectory (e.g. /srv/sossdt/data). Locate the javaPath element and specify the path to your Java installation directory, for example:

{
  ...
  "javaPath": "/usr/lib/jvm/jdk-12"
  ...
}

Running the Installation Script

Open a terminal window. Set the current directory of the command prompt to the installation directory. Run the install_host.sh script located at the root of the installation directory. This script requires two parameters in the following order:

the installation directory for ScaleOut StreamServer (for example, /usr/local/soss)
the range of TCP ports used by StreamServer (typically, 720-724), which the script uses to open the firewall for the UI

For example, the installation script could be run with the following command:

sudo ./install_host.sh /usr/local/soss 720-724

If ScaleOut StreamServer is installed in its default location (/usr/local/soss) and uses the default ports (720-724), you can omit both of these parameters:

sudo ./install_host.sh

Note

The install script additionally opens port 7700 to allow the UI to access the Host Agent.

Updating the Host Agent

First, download the latest version of the installation script from ScaleOut Software here and extract the files into the update subdirectory of the original installation directory. Next, open a Terminal window and set the current directory of the command prompt to the update subdirectory.

Next, run the update_host.sh script located at the root of the update subdirectory:

sudo ./update_host.sh

This script has no parameters. The update script will ask you whether you want a backup of your current installation directory to be created.

Note

If you have any digital twin models deployed, you need to run the following management command to stop them before running the update_host.sh script:

soss stop_ig all

This allows the language runtimes to be updated. After the update procedure is completed, you can restart digital twin models using the ScaleOut Digital Twins UI. If the Java installation location has changed since the first installation of the Host Agent, the SOSS daemon will be restarted during the update process.

Note

If the ScaleOut StreamServer hosts are restarted, it will be necessary to remove any existing widgets or continuous queries in the UI and then recreate them.

Uninstalling the Host Agent

You can uninstall the Host Agent with the following steps. This process will leave the original installation directory and local data.

First, open a terminal window and set the current directory of the command prompt to the installation directory.

Next, run the uninstall_host.sh script to remove the current deployment:

sudo ./uninstall_host.sh

Note that this script can be started without any parameters if running from the installation directory. Otherwise, the path to the installation directory needs to be specified.