Deploying the Host Agent on Windows

Introduction

This section explains how to install the Host Agent on Windows. 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 service (called the Agent Service) used by the UI to deploy real-time digital twin models to the in-memory data grid

  • OpenJDK 21.0.2 (an open-source distribution of Java SE)

Prerequisites

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

  • PowerShell version 5 or later, if not already present on your system. To check the current version of PowerShell run the ‘Get-Host | Select-Object Version’ command in a PowerShell window. If the returned version number is less than 5.1, you’ll need to install a later version, which can be found here.

  • 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 a folder that is accessible by a Network Service account, which is the account under which the ScaleOut Digital Twins UI runs. It is recommended that you extract the files to the following folder: C:\StreamServerDT. This folder will be referred to as the installation folder. 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 folder. Because both packages share two files, the operating system may prompt you to allow these files to be replaced when installing the second package.

Running the Installation Script

Open a Windows command prompt as an Administrator (right-click on the command prompt’s icon and select Run as Administrator). Set the current directory of the command prompt to the installation folder. Run the install_host.bat script located at the root of the installation folder. This script requires two parameters in the following order:

  • the installation folder for ScaleOut StreamServer (for example, “C:\Program Files\ScaleOut_Software\StateServer”)

  • 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:

install_host.bat "C:\Program Files\ScaleOut_Software\StateServer" "720-724"

If ScaleOut StreamServer was installed in its default location (C:\Program Files\ScaleOut_Software\StateServer) and uses the default ports (720-724), you can omit both of these parameters:

install_host.bat

The script performs several steps and takes several minutes to run.

Note

The install script additionally opens port 7700 to allow the ScaleOut Digital Twins 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 subfolder of the original installation folder. Next, open a Windows command prompt as an Administrator. Set the current directory of the command prompt to the update subfolder.

Next, run the update_host.bat script located at the root of the update subfolder. This script has no parameters. The update script will ask you whether you want a backup of your current installation folder to be created.

Note

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

soss.exe stop_ig all

This allows the language runtimes to be updated. After the update procedure is completed, you can restart the digital twin models using the UI. If the Java installation location has changed since the first installation of the Host Agent, the SOSS service 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 folder and local data.

First, open a Windows command prompt as an Administrator. Set the current directory of the command prompt to the installation folder.

Next, run the uninstall_host.bat script to remove the current deployment. Note that this script can be started without any parameters if it is running from the installation folder. Otherwise, the path to the installation folder needs to be specified.