---
title: "TVE (POC) Installation Instructions"
slug: "tve-poc-installation-instructions"
updated: 2026-08-07T12:20:53Z
published: 2026-08-07T12:20:53Z
canonical: "help.hyperscience.ai/tve-poc-installation-instructions"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.hyperscience.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TVE (POC) Installation Instructions

> [!NOTE]
> **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](/deployment/docs/technical-installation-upgrade-instructions) and the other articles in the [Installation Process](/deployment/docs/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)

> [!WARNING]
> **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](/deployment/docs/technical-installation-upgrade-instructions).

> [!WARNING]
> **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](/deployment/docs/hyperscience-virtual-machine-prerequisites#disable-swap-space) in [Hyperscience Virtual Machine Prerequisites](/deployment/docs/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](/deployment/docs/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](/deployment/docs/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](https://docs.docker.com/install/linux/docker-ce/ubuntu/).

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

```bash
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`:

```bash
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`:

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

> [!NOTE]
> **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:

```bash
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:

```bash
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](/deployment/docs/tve-poc-installation-instructions#6-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:

```bash
sudo wget <link-to-bundle>
```

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

```bash
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.

> [!NOTE]
> **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:
> 
> ```bash
> 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:

```bash
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:

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

> [!CAUTION]
> **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:
> 
> ```bash
> 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:

```bash
./configure_tve.sh
```

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

```bash
# 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.

> [!NOTE]
> 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:

```bash
sudo bash run.sh db
```

### 4) Initialize the application.

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

```bash
sudo bash run.sh init
```

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

> [!NOTE]
> 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:

```bash
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:

```bash
"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](/deployment/docs/license-keys#providing-a-license-key-during-installations-or-upgrades) in [License Keys](/deployment/docs/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.

> [!WARNING]
> **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](/deployment/docs/tve-poc-infrastructure-requirements).

### 1) Create the trainer media directory.

Run the following commands:

```bash
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)](/deployment/docs/tve-poc-installation-instructions#1-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:

```bash
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:

```bash
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:

```bash
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](/deployment/docs/tve-poc-installation-instructions#6-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:

```bash
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:

```bash
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:

```bash
# 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
```

> [!WARNING]
> **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](/deployment/docs/security) article.

> [!CAUTION]
> **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](/deployment/docs/configuring-hyperscience-hypercell).

A separate machine dedicated to handling resource-heavy tasks like training Identification models. It operates independently and connects to the main application through the API.

A configuration file used to define environment-specific variables, such as API keys or database credentials. It allows Hyperscience to run securely and consistently across different instances.