Technical Installation / Upgrade Instructions

Technical Installation / Upgrade Instructions

Introduction

Purpose

This article provides the steps necessary to install or upgrade the Hyperscience Application and Trainer. It is oriented toward the System Administrators who will perform this.

Also, 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 both the Hyperscience Application and Trainer, whether you are installing them for the first time, or if you are upgrading an already running environment to a newer version.

In the most common use case, the following steps need to be taken on the Application and the Trainer VMs to perform this task:

  1. Download, distribute, and unpack the Hyperscience bundle
  2. Configure the environment variables
  3. Start up the Application/Trainer

Download, distribute, and unpack the Install/Upgrade bundle

Whether you are installing or upgrading, the Hyperscience Application and Trainer come bundled in a single .tgz archive. The filename would be called 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 amount of times you can download a single version. If you are installing/upgrading Hyperscience on multiple VMs, make sure you download it once and then distribute it internally within your own network.

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

sudo wget <link-to-bundle>

Once the bundle has been downloaded and distributed to all VMs, move it to the installation folder /opt/hs (recommended) and extract it using:

sudo tar -xzvf hyperscience-trainer-x.x.x.tgz

This will extract the file into a folder with the name of the archive. Inside it is located the “.env“ file which will be further configured based on your setup.

Application Install/Upgrade

If you are doing a fresh Install, make sure you have completed the prerequisite steps to prepare your infrastructure and VMs as outlined in our Hyperscience Infrastructure Prerequisites and Hyperscience Virtual Machine Prerequisites articles.

If you are doing an application upgrade, make sure you are following the steps for the upgrade process as per The Upgrade Process.

Before proceeding with upgrading, make sure to back up your database and file store if you haven't already. This helps avoid losing data, and you can use the backup if you ever need to roll back to the previous version.

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:

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

If SELinux is enabled in enforcing mode, you also need to give your application containers access 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 command:

chcon -t container_file_t -R <installation_folder>/sdm_blocks

If you fail to do so, you will see the following error when attempting to initialize 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.

Install

a. If you are doing a fresh install of Hyperscience, you should edit the “.env” file and fill in all relevant configuration information. You would need to set the following variables at a minimum, and depending on your setup, there may be more. Any additional configuration like authentication, security, etc. can be added at a later stage:

# Database configuration
FORMS_DB_TYPE=<type of database used>
FORMS_DB_HOST=<hostname of the database>
FORMS_DB_NAME=<database name>
FORMS_DB_USER=<database user>
FORMS_DB_PASS=<database password>

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

# File storage
FORMS_STORAGE_MODE=<type of file storage>
HS_PATH=/mnt/hs

# Trusted origins domain if using Load Balancer
HS_CSRF_TRUSTED_ORIGINS=https://test.com,https://*.subdomain.com

Make sure to remove any “.env” variables that are left without a value to prevent startup issues.

b. If you have more than one application VM, make sure you distribute the same “.env” file across all machines. We validate the file’s checksum at startup, and failing to do so would result in startup failure on subsequent VMs.

Upgrade

If you are performing an upgrade, you should already have an “.env” file set from the previous version. Copy and replace the “.env” file from the old version folder to the new one.

3. Initialize the Application on the first machine.

On initial install, when upgrading to a new version, and every time the “.env” file is edited, you must initialize the application on the first application VM in the cluster.

Navigate to the folder where the Hyperscience bundle was unpacked and run the initialization script:

sudo bash run.sh init

This script will update the database tables and prepare the application for startup.

There is no need to run this script on all machines in the cluster.

4. Start the Application on all machines.

After running the above init command (whether for an initial install, upgrade, or configuration change), you must start/update the running application containers on each machine in the cluster:

sudo bash run.sh

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

Trainer Install/Upgrade

If you are doing a fresh install, make sure you have completed the prerequisite steps to prepare your infrastructure as outlined in our Hyperscience Infrastructure Prerequisites article.

The steps to install the trainer are similar to installing the application, but you do not need to set up a separate database for it, as it uses its own local PostgreSQL database that is provided with the install bundle.

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

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

If SELinux is enabled in enforcing mode, you also need to give your trainer containers access to the media and database directories.

To do so, depending on your Hyperscience version, 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>

2. Configure the “.env” file.

Install

a. If you are installing the trainer for the first time since most of the “.env” configurations relate to the application, remove the file and re-create it:

rm .env
touch .env

b. If you created the trainer_media folder under the default HS_PATH (/mnt/hs/trainer_media), proceed to the next step, “Starting the trainer.”

c. If not, you need to specify the HS_PATH that points to the media folder:

HS_PATH=/my/path/hs

Upgrade

If you are performing an upgrade, you should already have a “.env” file set from the previous Trainer version. Copy the “.env” file from the old version folder to the new one.

3. Start the trainer.

a. Obtain an authentication token.

You need to obtain an authentication token from a user with API permissions.

b. Start the trainer.

Navigate to the folder where the Hyperscience bundle was unpacked and run the following command.

sudo bash run.sh trainer <main application URL> <authentication token>

4. Connect to the application through local or external trainer users.

You need to add the TRAINER_USER variable to the “.env” file of the application machine. If you are upgrading Hyperscience, adding this variable ensures that your trainer's access to the application will not be interrupted after upgrading.

Once you start the trainer with the new token, your trainer's user will be automatically added to the list of exempted users.