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:
Download, distribute, and unpack the Hyperscience bundle
Configure the environment variables
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.tgzThis 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 business steps for the upgrade process as per the Upgrade Process Overview article.
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 / permissiveSELinux 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 permissions denials are both logged and enforced.
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_blocksIf 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 12) 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.comMake 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
a. 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.
b. If you are upgrading to Hyperscience v38 or later and you are using a Load Balancer, make sure you add the HS_CSRF_TRUSTED_ORIGINS variable to your “.env” file to prevent login issues. For more information, refer to the Load Balancing section of Hyperscience Infrastructure Prerequisites.
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 initThis 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.shThis 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.
In addition, the trainer also uses a local file store, as opposed to a network mount or cloud-based one.
1) Check SELinux status (RHEL only).
Run the following command on the machine:
sudo sestatus
# Sample Output
# SELinux status: enabled / disabled
# Current mode: enforcing / permissiveSELinux 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 permissions denials are both logged and enforced.
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, assuming that you are using the default HS_PATH=/mnt/hs variable
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 39.0.2, you would enter:
# chcon -t container_file_t /mnt/hs/trainer_media
# mkdir -p /mnt/hs/postgres_trainer39_0
# chcon -R -t container_file_t /mnt/hs/postgres_trainer39_02) 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 .envb. 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, for example, if you created it in /my/path/hs/trainer_media, put the following config in the “.env” file:
HS_PATH=/my/path/hsUpgrade
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. This user could be any of the three types:
Dedicated local Trainer User
User-created by an external authentication method
Any local user with the proper permissions
The details on how to set up the first two options are described in the Connect to the application through local or external trainer users section below.
Once you choose the type of user to get the token from, follow these steps to obtain the authentication token:
Log in to the application.
Click on Users, and select the chosen user.
Find the user's Authentication Token, and click Copy.
Click Done.
b. Start the trainer.
Navigate to the folder where the Hyperscience bundle was unpacked and run the following command.
This will automatically start up the required trainer roles based on the configuration you have set. As long as Docker/Podman is configured to start at boot, then the trainer will also start at boot.
sudo bash run.sh 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.
# If 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. We recommend creating a service account,
# or a "user" whose token will provide API access to the trainer and other services.
# For information on obtaining tokens, see Managing API Tokens.Here are some good examples of how you can 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 trainer https://10.0.0.5 2e831cc1a420a7a45264aab0624aa26d9da1aa70Here are some examples of incorrect ways to run this command:
#Do not use 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 (IP address of the application server if using only one application server)
bash run.sh trainer environment-shortname 2e831cc1a420a7a45264aab0624aa26d9da1aa70The trainer connects to the main Hyperscience application via 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, the application load balancer URL changes, a new API authentication token is used, SSL is configured, LDAP is configured, etc.), you will have to restart the trainer by rerunning the command above.
If you would like 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.
4) Connect to the application through local or external trainer users.
We have security measures to:
enforce the use of a single authentication method, and
periodically invalidate API tokens for API users created with external authentication methods.
This automatic token invalidation is optional and disabled by default. To learn more, see External Authentication Methods and API Users.
If you're using an external authentication method, you can still connect your trainer to the application either through a local user or one obtained from the external authentication method.
Local trainer user
To do so, 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.
Add the
TRAINER_USERvariable to your application’s “.env” file, with the username of your trainer's user as its value:
TRAINER_USER=<username_of_trainer_user>Restart the application using:
sudo bash run.sh init
sudo bash run.shOnce you start the trainer with the new token, your trainer's user will be automatically added to the list of exempted users.
Editing the
TRAINER_USERvariable will create a new user with the username you enter, if it doesn’t already exist. It will not remove the user previously created through theTRAINER_USERvariable.
Trainer user from external authentication method
If you are connecting the trainer through a user created with your external authentication method, you must add the trainer's user name to the TOKEN_REVALIDATION_EXEMPTED_USERS variable. You should not add the TRAINER_USER variable to your “.env” file. For more information, see External Authentication Methods and API Users.