Deploying the ScaleOut Digital Twins UI

Introduction

This section explains how to install the ScaleOut Digital Twins UI. The UI can be installed either on a Windows host (Windows 10/11 or Windows Server 2019 and higher) or on a Linux host (Ubuntu or CentOS), which is called the management server here.

Note

The DT Host Agent must also be installed on all ScaleOut StreamServer hosts. Please see Deploying the Host Agent on Windows (or Deploying the Host Agent on Linux) for details.

The management server connects to your deployment of ScaleOut StreamServer’s in-memory data grid running on a cluster of on-premises servers, as illustrated below:

image0

The ScaleOut Digital Twins UI can be accessed from a web browser running on the management server. It optionally can be configured for remote access from a networked workstation, as shown above.

Components

The installer script installs the following components on the management server:

  • A Docker container that provides the user interface (UI)

  • A Docker container that provides user identity management

  • A Docker container that provides a REST service that the UI uses to access the in-memory data grid

  • A Docker container that provides a REST service for applications that need to send messages to the in-memory data grid and receive replies

  • A SQLite database that stores user identities

  • A SQLite database that stores real-time digital twin models, widgets, and other artifacts

Prerequisites

  • PowerShell version 5 or later, if required. Hosts running Windows 10 Anniversary Update or Windows Server 2016 should already have Windows PowerShell 5.1 installed. 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 not 5.1, then you’ll need to install Windows PowerShell 5.1 by downloading and installing the Windows Management Framework 5.1, which can be found here.

  • Prior to installing the ScaleOut Digital Twins UI, please install either Docker Desktop for Windows or Docker for Linux, which is used to host the containers needed to implement the ScaleOut Digital Twins UI.

Note

Docker Desktop for Windows requires that the Windows Subsystem for Linux (WSL) be installed on the management server and provides instructions for this.

  • In addition, ScaleOut StreamServer, which hosts the in-memory data grid, needs to be installed and configured on a cluster of servers. These servers need to be reachable from the management server. For initial testing prior to production use, ScaleOut StreamServer can be installed on the management server instead of a separate cluster.

Installation Steps

First, download the 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 ScaleOut Digital Twins UI runs. It is recommended that you extract the files to the following folder: C:\ScaleOutStreamServerDT on Windows or /srv/sossdt on Linux. This folder will be referred to as the installation folder. It will be used during installation and by components of the ScaleOut Digital Twins UI after their deployment. For example, it will contain files located on Docker volumes shared between DT Docker containers.

Next, determine whether you need to access the UI from a remote workstation. If you are planning to use ScaleOut StreamServer just on your local workstation and are not considering accessing it remotely, then you can use the default installation settings and access the ScaleOut Digital Twins UI via a localhost alias (https://localhost:5501), which is secured by a self-signed certificate created by ScaleOut Software. The installation steps are described in the next section, Installing for Local Access.

Alternatively, if you’re planning to install the ScaleOut Digital Twins UI so other users can access it simultaneously from remote workstations, then you need to make configuration changes before you deploy the system. These steps are described in the section below Installing for Remote Access.

Note

If you are using a Linux machine, make sure all .sh extracted files have the execute permission option set to be run as a program (‘x’ flag).

Installing for Local Access

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

First, edit the .env file located at the root of the installation folder. Locate the DT_HOST_IP environment variable and specify the IP address of the local system (that is, the management server) as the variable’s value, for example:

DT_HOST_IP=10.0.4.230

By default, the ScaleOut Digital Twins UI is accessible via the https://localhost:5501 URL. You can change default port 5501 to any other port. To do that, locate the DT_HOST_PORT environment variable and specify the port number you want to use. For example, if you would like to access the service via the https://localhost URL, make the following change:

DT_HOST_PORT=443

If the DT Host Agent is installed on a separate set of machines, the SOSS_CONNECTION environment variable’s value needs to be adjusted to reflect that. By default, this connection string uses a local DT_HOST_IP address for simplest use case when the DT Host Agent with ScaleOut Stream server is installed locally on the same machine. For a distributed deployment scenario, the connection string should list all StreamServer hosts’ IP public addresses accessible from this management server. For example, let’s assume the StreamServer cluster contains 2 hosts with public IP addresses 10.0.4.240 and 10.0.4.241, then the SOSS_CONNECTION environment variable should look as follows (assuming StreamServer uses default server TCP port 721):

SOSS_CONNECTION=BootstrapGateways=10.0.4.240:721,10.0.4.241:721;ignoreKeyAppId=true

Next, install the default SSL certificate supplied in the subfolder data/certs, as described below. On Windows host it needs to be installed into the local system’s Trusted Root Certification Authorities store. On Linux, the certificate installation instructions are specific for each browser. This public certificate can be found in the dtserver.scaleoutsoftware.com.crt file (for Windows) and dtserver.scaleoutsoftware.com.pem (for Linux).

To install the certificate on a Windows host:

  • Right-click on the .crt certificate file and choose Install Certificate. The Certificate Import Wizard will appear.

  • Select the Local Machine store location and click Next.

  • Select Place all certificates in the following store and click on Browse.

  • Select the Trusted Root Certification Authorities store and click Ok.

  • Click Next and then Finish to complete the installation of the certificate.

To install the certificate on a Linux host, run the following commands for the respective browsers:

  • For the Google Chrome browser: certutil -d sql:$HOME/.pki/nssdb -A -t “TC,,” -n “localhost” -i /srv/sossdt/data/certs/dtserver.scaleoutsoftware.com.pem

  • For the Firefox browser: certutil -d sql:<FIREFOX_PROFILE_PATH> -A -t “TC,,” -n “localhost” -i /srv/sossdt/data/certs/dtserver.scaleoutsoftware.com.pem

Installing for Remote Access

This installation process configures the ScaleOut Digital Twins UI for access by remote workstations. In addition to the above steps, it requires specifying the management server’s host name and a custom SSL certificate.

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

First, edit the .env file located at the root of the installation folder. Edit the following two entries:

  • Locate the DT_HOST_NAME environment variable and specify the hostname of the local system as its value, for example:

    DT_HOST_NAME=myserver

    or:

    DT_HOST_NAME=myserver.mydomain.com

  • Locate the DT_HOST_IP environment variable and specify the IP address of the local system (that is, the management server) as the variable’s value, for example:

    DT_HOST_IP=10.0.4.230

  • If the DT Host Agent is installed on a separate set of machines, the SOSS_CONNECTION environment variable’s value needs to be adjusted to reflect that. By default, this connection string uses a local DT_HOST_IP address for simplest use case when the DT Host Agent with ScaleOut Stream server is installed locally on the same machine. For a distributed deployment scenario, the connection string should list all StreamServer hosts’ IP public addresses accessible from this management server. For example, let’s assume the StreamServer cluster contains 2 hosts with public IP addresses 10.0.4.240 and 10.0.4.241, then the SOSS_CONNECTION environment variable should look as follows (assuming StreamServer uses default server TCP port 721):

    SOSS_CONNECTION=BootstrapGateways=10.0.4.240:721,10.0.4.241:721;ignoreKeyAppId=true

Next, edit the reverse_proxy.conf file located in the subfolder data/nginx. Locate the upstream dtserver configuration block and change the localhost name to the hostname (or DNS alias) of the local system, for example:

server myserver:3000;

Finally, install a custom SSL certificate supplied in the subfolder data/certs into the local system’s Trusted Root Certification Authorities store (for Windows) or follow the browser-specific instructions for Linux hosts. This server-side certificate is used to secure the SSL endpoints and match the target local system’s name (e.g., “myserver”) or its corresponding DNS alias. The unique URL endpoints that need to be secured by the SSL certificate are as follows:

  • ScaleOut Digital Twins UI: https://{DT_HOST_NAME}:5501

  • ScaleOut Digital Twins middle-tier endpoints: https://{DT_HOST_NAME}:7701

  • ScaleOut Digital Twins admin site: https://{DT_HOST_NAME}:9901

  • ScaleOut Digital Twins messaging api endpoints: https://{DT_HOST_NAME}:8801

Copy your certificate (both the .pfx file and the pair of .pem/.key files) into the data/certs subfolder.

Open the .env file again located at the root of the installation folder and specify the values for four environment variables with names starting with DT_SSL_. For example, if the prefix for your SSL certificate is mycert, specify the values as follows:

DT_SSL_PFX_CERT_FILE_NAME=myсert.pfx
DT_SSL_PFX_CERT_FILE_PWD=myсertpwd
DT_SSL_PEM_CERT_FILE_NAME=myсert.pem
DT_SSL_KEY_CERT_FILE_NAME=myсert.key

Now install the certificate. On a Windows host:

  • Right-click on the .pfx certificate file and choose Install Certificate. The Certificate Import Wizard will appear.

  • Select the Local Machine store location and click Next.

  • Select Place all certificates in the following store and click on Browse.

  • Select the Trusted Root Certification Authorities store and click Ok.

  • Click Next and then Finish to complete the installation of the certificate.

On a Linux host run the following commands:

  • For the Google Chrome browser: certutil -d sql:$HOME/.pki/nssdb -A -t “TC,,” -n “localhost” -i /srv/sossdt/data/certs/myсert.pem

  • For the Firefox browser: certutil -d sql:<FIREFOX_PROFILE_PATH> -A -t “TC,,” -n “localhost” -i /srv/sossdt/data/certs/myсert.pem

Running the Installation Script

Now you are ready to run the installation script. On Windows, open a Windows command prompt as an Administrator. (You can do this by right-clicking on the command prompt’s icon and selecting Run as Administrator.) On Linux, open a terminal window. Set the current directory of the command prompt to the installation folder. Run the install_mgt.bat script on Windows or the install_mgt.sh script on Linux. These files are located at the root of the installation folder.

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

install_mgt.bat
or
install_mgt.sh

The script performs several steps and takes several minutes to run. Once completed, please proceed to the section Configuring the ScaleOut Digital Twins UI below.

Configuring the ScaleOut Digital Twins UI

After running the installation script, the system administrator should update the default configuration parameters that are used to connect the ScaleOut Digital Twins UI to ScaleOut StreamServer’s in-memory data grid. This step should be completed before the first user registers an account and logs in.

To access the ScaleOut Digital Twins admin tool open the browser and navigate to the ScaleOut Digital Twins Admin Site using the https://{DT_HOST_NAME}:9901 URL. Note that if the UI component was installed only for local access, DT_HOST_NAME is set to “localhost”. Log in to the admin site using the built-in admin user’s credentials:

  • user name: admin@streamserver.dt

  • password: Sc@le0ut

Click the Configuration column link. By default, the IP address of the local system is specified. If the ScaleOut StreamServer in-memory data grid is not located on the local system, this IP address must be removed. Now add if necessary the IP addresses of all ScaleOut StreamServer hosts and specify the server TCP port that ScaleOut StreamServer uses. Click the Save button and log out. You should be redirected to the ScaleOut Digital Twins UI’s login page, as described below.

Using the ScaleOut Digital Twins UI

You are now ready to use the ScaleOut Digital Twins UI, which can be accessed at the following URL:

https://{DT_HOST_NAME}:5501

or

https://localhost:5501

when running the UI on the local host.

Press the Log In button and click the Register as a new user link to create a user account. Enter the email address and password that you would like to use. The password must be between 6 and 100 characters long, have at least one non-alphanumeric character, have at least one digit (‘0’-‘9’), and have at least one uppercase (‘A’-‘Z’).

After registering your account, you will see the UI where you can deploy your first digital twin model! Please see ScaleOut Digital Twins™ UI Guide topic for a description of the user interface. Note that all features of the cloud service are available on-premises except for those that manage organizations.

Applications can send incoming messages to the built-in REST service at the following URL:

https://{DT_HOST_NAME}:8801

Note that the REST service uses API keys, which can be created in the ScaleOut Digital Twins UI.

Updating the ScaleOut Digital Twins UI

You can either perform a full update or a partial update. A partial update just updates the Docker containers. 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, on Windows, open a Windows command prompt as an Administrator. On Linux, open a new terminal window. Set the current directory of the command prompt to the update subfolder.

Full Update

To perform a full update, run the update_mgt.bat script on Windows or update_mgt.sh on Linux. These files 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. It will then stop all running ScaleOut docker containers and other components, update the product components while preserving your custom configuration, and restart all docker containers and components.

Partial Update

When a new version of ScaleOut Docker images become available on DockerHub, you can just update these images by running the update_partial_mgt.bat script on Windows or update_partial_mgt.sh on Linux.

The script will stop all running ScaleOut docker containers and other components, pull new docker images, and restart all docker containers.

Starting and stopping Docker containers

Sometimes it might be neccessary to restart ScaleOut’s Docker containers. On Windows, open a Windows command prompt as an Administrator. On Linux, open a new terminal window. Set the current directory of the command prompt to the installation folder.

To stop ScaleOut’s Docker containers run the following command:

docker compose down

To start the containers, run the following command:

docker compose -f docker-compose.yml -f docker-compose.onprem.yml up -d

Configuring Service Endpoints

By default, the REST API and Authentication Service Docker containers are configured to run on localhost using ports 7701 and 9901, respectively. However, you may choose to deploy these containers on different hosts or ports depending on your environment.

After deploying the containers to your desired locations, follow these steps to allow the UI to communicate with the correct service endpoints:

  1. Navigate to the data subfolder within your installation directory.

  2. Open the startup.json file in a text editor.

  3. Update the values for the following keys with the appropriate URLs corresponding to your deployed services:

    • rest_api_url_prefix

    • auth_service_url_prefix

  4. Save the file.

  5. To apply the changes:

    • Run the install_mgt.bat or install_mgt.sh script.

    • Refresh the UI in your browser.

Uninstalling the ScaleOut Digital Twins UI

You can uninstall the ScaleOut Digital Twins UI with the following steps. This process will leave the original installation folder and local data.

First, on Windows, open a Windows command prompt as an Administrator. On Linux, open a new terminal window. Set the current directory of the command prompt to the installation folder.

Next, run the uninstall_mgt.bat script on Windows or the uninstall_mgt.sh on Linux 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.