Press CTRL+K to open search

TVE (POC) Installation Instructions

  • Updated on Aug 7, 2026
  • Published on Sep 17, 2024
  • 11 minute(s) read
Prev Next

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 Technical Installation / Upgrade Instructions and the other articles in the Installation Process section.

Introduction

The sections below describe the purpose and scope of this article.

Purpose

This article provides the steps necessary to install the Hyperscience Application and Trainer in a technical validation environment (TVE). It is oriented toward the system administrators who will perform this.

Make sure you are either a root user or that you have elevated root-level permissions (i.e., you can execute sudo commands) on the machines that will be running Hyperscience.

Scope

This article is valid for first-time installs of the Hyperscience Application and Trainer in a TVE. A TVE differs from a production environment in the following ways:

  • The application runs on a single VM instead of a multi-machine cluster.

  • The database is a local PostgreSQL instance provided with the install bundle, rather than an external database.

  • The file store is a local directory (FORMS_STORAGE_MODE=FILE), rather than a network mount or cloud-based store.

  • Configuration is set through the interactive configure_tve.sh script instead of editing the ".env" file manually.

In the most common use case, the following steps need to be taken to perform this task:

  1. Prepare the VM (container runtime, file store, and network access)

  2. Download and unpack the Hyperscience bundle on each VM (Application and Trainer)

  3. Configure the environment variables

  4. Start up the application

  5. Start up the trainer (optional)

TVE environments are not supported for production use

Do not upgrade a TVE in place or migrate it into a production environment. For production deployments, follow Technical Installation / Upgrade Instructions.

Disable swap before you run the run.sh script

This applies to both installations and upgrades, on both application and trainer VMs. If swap is enabled, run.sh stops and returns the error "Having the swap enabled can potentially lock the system for a long time. We DO NOT recommend having the swap enabled. Refer to the installation instructions for more details about disabling it."

For the steps to turn swap off, see Disable swap space in Hyperscience Virtual Machine Prerequisites.

Prepare the VM

Before installing Hyperscience, prepare the VM by installing a container runtime, creating the local file store, opening the required port, and confirming your access to the machine. For detailed information on the hardware requirements for running Hyperscience in a TVE, see TVE (POC) Infrastructure Requirements and contact our Customer Experience team.

1) Install and verify the container runtime.

Hyperscience runs in containers, so either Docker or Podman must be installed and configured to start at boot.

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

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

If you're using Docker, run the following commands as root:

docker version          # confirm the installed version
docker ps               # check that there are no running containers
systemctl enable docker # ensure Docker starts all containers after reboots

If you're using Podman, run the following commands as root:

podman version          # confirm the installed version
podman ps               # check that there are no running containers
systemctl enable podman # ensure Podman starts all containers after reboots

2) Create the local file store.

Choose a storage location for your data. This location holds uploaded images and database records, and it is the value of the HS_PATH variable that you set later in this article.

The application requires a subfolder named media under this location, owned by user 1000 and group 1000. For example, if /mnt/hs is your chosen location, run the following commands as root:

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

The examples in this article use the default HS_PATH value

All commands below assume an HS_PATH of /mnt/hs. If you choose a different location, substitute it in each command.

3) 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. To check the settings and open port 80:

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

RHEL uses the firewall-cmd utility for firewall settings. To check the settings and open port 80:

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

From outside the server, you must be able to receive HTTP replies from Hyperscience at <external hostname or IP>:80. To verify access after installation, see Log in to the application.

4) Confirm root access.

During installation, you need one of the following:

  • Direct root access to the VM through a shared screen (e.g., Webex, Zoom, or Google Meet) or by SSH

  • Someone else with root access present to run the commands and help install the software

Download and unpack the installation bundle

The Hyperscience Application and Trainer come bundled in a single archive file named hyperscience-trainer-x.x.x.tgz where x.x.x is the version number.

Due to the archive's size, there is a limit on the number of times you can download a single version. If you are installing Hyperscience on more than one VM, download it once and then distribute it internally within your own network.

To download the bundle on a Linux VM, execute the following command:

sudo wget <link-to-bundle>

Move the bundle to the installation folder /opt/hs (recommended) and extract it:

cd /opt/hs/<folder where contents were extracted>
sudo tar -xzvf hyperscience-x.x.x.tgz

This extracts the bundle into a folder with the name of the archive. Inside it is the ".env" file, which you configure in the next section.

If extracting the bundle fails, verify that the file downloaded correctly

Compare the downloaded file's checksum to the checksum provided by your Hyperscience representative with the download link. To obtain the downloaded file's checksum, run:

sha256sum <hyperscience_bundle_file_name>

Install the application

After the VM is prepared and the bundle is unpacked, complete the steps below to configure and start the application.

1) Check SELinux status (RHEL only).

Run the following command on the machine:

sudo sestatus
# Sample Output
# SELinux status:     enabled / disabled
# Current mode:       enforcing / permissive

SELinux operates on the principle of default denial: anything not explicitly allowed is denied. When enabled, SELinux can operate in two global modes:

  • Permissive mode, in which permission denials are logged but not enforced

  • Enforcing mode, in which permission denials are both logged and enforced

If SELinux is enabled in permissive mode or disabled, go to the next step.

If SELinux is enabled in enforcing mode, you need to give your application containers access to the file store and to the ZIP files that contain flow blocks. These blocks are required to process submissions in Hyperscience.

To give the necessary permissions, run the following commands:

chcon -R -t container_file_t /mnt/hs
chcon -R -t container_file_t <installation_folder>/sdm_blocks

Skipping this step causes the application to fail on initialization

If you do not set these permissions, you will see the following error when initializing the application:

PermissionError: [Errno 13] Permission denied: '/var/www/forms/forms/sdm_blocks'
CommandError: Command [/var/www/post_migrate.sh] exited with 1

2) Configure the .env File.

Configuration is managed through the ".env" file in the supplied bundle. In a TVE, the interactive configure_tve.sh script sets the required parameters for you. From the folder where the bundle was unpacked, run:

./configure_tve.sh

When the script finishes, verify that your ".env" file looks similar to the following:

# Database configuration
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=<database password>

# Initial admin user
FORMS_USER=<username for UI>
FORMS_PASS=<password for UI>

# File storage
FORMS_STORAGE_MODE=FILE
HS_PATH=/mnt/hs

# Deployment type
DEPLOYMENT_TYPE=TVE

The FORMS_USER and FORMS_PASS values are the credentials you use to log in to the Hyperscience Application, they can be set to any preferred value.

Remove any ".env" variables that are left without a value to prevent startup issues.

3) Start the local database.

A TVE uses a local PostgreSQL database that is provided with the install bundle. Start it with:

sudo bash run.sh db

4) Initialize the application.

From the folder where the Hyperscience bundle was unpacked, run the initialization script:

sudo bash run.sh init

This script updates the database tables and prepares the application for startup.

Every time the configuration in the ".env" file is edited, you must run sudo bash run.sh init again.

5) Start the application.

After running the init command, start the remaining application containers:

sudo bash run.sh

This automatically starts the required application roles based on the configuration you have set. It can take as long as 5 minutes before the started containers finish initializing. As long as Docker or Podman is configured to start at boot, the application also starts at boot.

6) Log in to the application.

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

"The application has started successfully"

The Hyperscience software is now running. Enter the accessible hostname or IP address of your VM in a browser, and the login page appears. Log in with the FORMS_USER and FORMS_PASS credentials you set in the ".env" file.

On v39 and later, the application requires a valid license key. The first time a System Admin logs in after the install, the application prompts for the key. No other functionality is available until a valid key is entered. Each key is valid for a single instance, so request one for this instance from your Hyperscience representative before you continue. You need to give them the browser URL of your application and the instance type (e.g., TVE) the key applies to. For the steps to enter the key, see Providing a license key during installations or upgrades in License Keys.

Install the trainer (optional)

The training of models is completed by a trainer. The trainer does not need a separate database, as it uses its own local PostgreSQL database provided with the install bundle. It also uses a local file store, and it connects to the main application through the API.

Deploy the trainer on a separate VM from the main application

We recommend this configuration because it improves resource and performance isolation between the trainer and the main application.

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

1) Create the trainer media directory.

Run the following commands:

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

2) Check SELinux status (RHEL only).

Run sudo sestatus as described in Check SELinux status (RHEL only) above.

If SELinux is enabled in permissive mode or disabled, go to the next step.

If SELinux is enabled in enforcing mode, you need to give your trainer containers access to the media and database directories. 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 v42.3.1, you would enter:
# chcon -t container_file_t /mnt/hs/trainer_media
# mkdir -p /mnt/hs/postgres_trainer42_3
# chcon -R -t container_file_t /mnt/hs/postgres_trainer42_3

3) Configure the ".env" file.

Most of the ".env" configuration relates to the application, so on a dedicated trainer VM, remove the file and re-create it:

rm .env
touch .env

If you created the trainer_media folder under the default HS_PATH (/mnt/hs/trainer_media), go to the next step.

If not, specify the HS_PATH that points to the parent of the media folder. For example, if you created it in /my/path/hs/trainer_media, add the following to the ".env" file:

HS_PATH=/my/path/hs

4) Obtain an authentication token.

You need an authentication token from a user in the main application that has the API Access permission enabled. To obtain the token:

  1. Log in to the application. Note that you can only reach the Users page after you log in and unlock the application with a valid license key. See Log in to the application.

  2. Go to the Users page (Administration > Users), and select the chosen user.

  3. Find the user's Authentication Token, and click Copy.

  4. Click Done.

5) Start the trainer.

From the same location where the Hyperscience bundle was unpacked, run the following command:

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

# <main application URL>:
# This is the URL of the main application.
# This must be specified without the trailing slash.
# You can use either the IP address or the hostname. If using the hostname,
# make sure it can be properly resolved.

# <authentication token>:
# This is the authentication token for a user provisioned in the main application
# that has the API Access permission enabled.

# --force:
# This is needed only if the trainer runs on the same machine as the application.

This automatically starts the required trainer roles based on the configuration you have set. As long as Docker or Podman is configured to start at boot, the trainer also starts at boot.

The following examples show correct ways to run this command:

sudo bash run.sh trainer http://environment.hyperscience.com 2e831cc1a420a7a45264aab0624aa26d9da1aa70

sudo bash run.sh trainer https://environment.hyperscience.com 2e831cc1a420a7a45264aab0624aa26d9da1aa70

sudo bash run.sh trainer http://10.0.0.5 2e831cc1a420a7a45264aab0624aa26d9da1aa70

sudo bash run.sh --force trainer https://10.0.0.5 2e831cc1a420a7a45264aab0624aa26d9da1aa70

The following examples show incorrect ways to run this command:

# Do not use a trailing slash on the URL:
bash run.sh trainer http://environment.hyperscience.com/ 2e831cc1a420a7a45264aab0624aa26d9da1aa70

# Do not keep the < and > brackets when substituting the variables for the command:
bash run.sh trainer <https://environment.hyperscience.com> <2e831cc1a420a7a45264aab0624aa26d9da1aa70>

# Always include either "http://" or "https://" at the start of your URL:
bash run.sh trainer environment.hyperscience.com 2e831cc1a420a7a45264aab0624aa26d9da1aa70

# Always use a fully qualified domain name, or the IP address of the application server:
bash run.sh trainer environment-shortname 2e831cc1a420a7a45264aab0624aa26d9da1aa70

The trainer connects to the main Hyperscience Application through the API

Whenever you change the configuration of the connection between the trainer and the main application (e.g., the URL of the Hyperscience Application changes, a new API authentication token is used, SSL is configured, or LDAP is configured), you must restart the trainer by rerunning the command above.

To configure the trainer to connect to the application over TLS, follow the guidelines in the TLS configuration for outbound connections section of the Security article.

Do not run the trainer on the same machine as the application

Use this configuration only when a Hyperscience representative instructs you to do so. It requires the --force flag and can cause resource contention that affects both the application and training performance.

Begin testing

Your TVE is now ready for use. To continue configuring your environment, see Configuring Hyperscience Hypercell.

© Hyperscience