TVE (POC) Installation Instructions

TVE (POC) Installation Instructions

For technical validation events only
The instructions in this article are for technical validation events (TVEs), which demonstrate Hyperscience's capabilities during the sales process.
For installing Hyperscience after the sales process, see the articles in the Installation Process section.

Prerequisites

For more detailed information on the hardware requirements for running Hyperscience, refer to the Infrastructure Requirements Overview page and contact our Customer Experience team.

Server

If the server is running RHEL 8.10 or later, and Podman is not installed, follow the steps in Configuring Podman in RHEL 8 to install Podman.

If the server is running Ubuntu, and Docker is not installed, follow the steps in Docker’s Install Docker Engine on Ubuntu to install Docker.

If you're using Docker...

To confirm the version of Docker, run:

docker version

To check that there are no running containers, run:

docker ps

To ensure Docker runs all containers after system reboots, run the following as root:

systemctl enable docker

If you're using Podman...

To confirm the version of Podman, run:

podman version

To check that there are no running containers, run:

podman ps

To ensure Podman runs all containers after system reboots, run the following as root:

systemctl enable podman

File storage

Media & image storage

Choose a storage location for keeping your data. This location will hold uploaded images and database records and will be HS_PATH in the configuration section below.

After choosing a location, our application requires you to create a sub-folder named media owned by user 1000 and group 1000.

For instance, if /mnt/hs is your chosen location, run these commands as root:

mkdir -p /mnt/hs/media
chown 1000:1000 /mnt/hs/media

Additionally, if your VM uses SELinux, run as root:

chcon -R -t container_file_t /mnt/hs

Server access

Open port 80 for HTTP

The web UI is exposed on port 80, so you must open this port on any firewalls that might be enabled.

Ubuntu uses the ufw utility for firewall settings. If necessary, to check settings and open port 80:

sudo ufw status   #show the status of the firewall - enabled or disabled
sudo ufw app list #lists the configured, or opened ports by name
sudo ufw allow 80 #enables open service on port 80
sudo ufw reload   #reloads configuration after changing rules

RHEL uses the firewall-cmd utility for firewall settings. If necessary, to check settings and open port 80:

sudo firewall-cmd --list-all  #show currently applied rules
sudo firewall-cmd --zone=public --add-port=80/tcp --permanent  #adds exception to allow port 80 to accept traffic
sudo firewall-cmd --reload

From outside the server, you must be able to receive HTTP replies from our software at <external hostname or IP>:80. See the Login and begin testing section below to check access after installation.

root user access to install our software and other dependencies

During installation, you need one of the following:

Hyperscience installation

Unpack bundle

You should download the bundle onto the VM and untar it (we recommend doing it inside /opt/hs) with the following commands:

tar xvzf <hyperscience bundle file>
cd  <folder where contents were extracted to (e.g., /opt/hs)>

For example, the bundle file could be called hyperscience-41.0.x.tgz or hyperscience-trainer-41.0.x.tgz if installing Hyperscience along with the Trainer.

If extracting a bundle fails, you can verify whether the file was downloaded correctly. To do so, compare the downloaded file’s checksum value to the checksum value provided by our representatives with the download link. To obtain the downloaded file’s checksum value, run the following command:

sha256sum <Hyperscience_bundle_file_name>

Configuration

Configuration is managed through an ".env" file in the supplied bundle.

The interactive configure_tve script, located in the Hyperscience directory, helps you set the required parameters in the ".env" file. Run the following command to execute the script:

./configure_tve.sh

Verify complete configuration

Your ".env" file should appear similar to the following:

FORMS_DB_TYPE=postgres
FORMS_DB_HOST=localhost
FORMS_DB_PORT=5432
FORMS_DB_NAME=hs_db
FORMS_DB_USER=hs_user
FORMS_DB_PASS=<any password>
FORMS_USER=<username for UI>
FORMS_PASS=<username for UI>
FORMS_STORAGE_MODE=FILE
HS_PATH=/mnt/hs
DEPLOYMENT_TYPE=POC

The FORMS_USER and FORMS_PASS username and password that you provide are going to be used to log in to the Hyperscience application.

First startup

Now you can start a local database within our application with:

sudo bash run.sh db

Then you can initialize and set the database and application settings with:

sudo bash run.sh init

Note that any time the application configuration in the ".env" file is changed, the run.sh init command needs to be executed again.

Finally, start the remaining application containers with:

sudo bash run.sh

This command will start up the required application roles based on the configuration you have set. It will take as long as five minutes before the started containers finish their initialization.

Trainer (optional)

The training of models is completed by a trainer, which we recommend deploying on a separate VM from the main application. Doing so enhances resource and performance isolation between the trainer and the main application. The trainer connects to the main application via the API.

Requirements

For information on technical requirements for the trainer, see TVE (POC) Infrastructure Requirements.

Installing the trainer

First, you need to create the trainer_media directory. To do so, run the following commands:

mkdir -p /mnt/hs/trainer_media
chown 1000:1000 /mnt/hs/trainer_media

If you are using SELinux, you also need to run the following commands:

chcon -t container_file_t /mnt/hs/trainer_media
mkdir -p /mnt/hs/postgres_trainer<major_version_number>_<minor_version_number>
chcon -R -t container_file_t /mnt/hs/postgres_trainer<major_version_number>_<minor_version_number>

Hyperscience version numbers are formatted as follows:

<major_version_number>.<minor_version_number>.<patch_version_number>

For example, if your application version is 41.0.1, you would enter:

chcon -t container_file_t /mnt/hs/trainer_media
mkdir -p /mnt/hs/postgres_trainer41_0
chcon -R -t container_file_t /mnt/hs/postgres_trainer41_0

To install the trainer, from the same location where the Hyperscience bundle was untarred, run the following command:

sudo bash run.sh [--force] trainer <main application URL> <access token>

To obtain <access token>:

  1. Log in to the application.
  2. Click on Users, and click on any username.
  3. Find the user's Authentication Token, and click Copy.
  4. Click Done.

Details for the parameters:

For example, with values filled in:

sudo bash run.sh --force trainer https://abcd123.internal 187d88d6s63929cd0ad98

Log in and begin testing

Upon completing successfully, the run.sh script prints out the following message:

"The application has started successfully"

The Hyperscience software is now running. Enter the accessible name or IP address of your VM in a browser, and a login page will appear.