--- title: "Technical Installation Instructions" slug: "technical-installation-upgrade-instructions" updated: 2026-08-07T12:20:24Z published: 2026-08-07T12:20:24Z canonical: "help.hyperscience.ai/technical-installation-upgrade-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. # Technical Installation Instructions This article provides the steps necessary to install the Hyperscience Application and Trainer for the first time. It is oriented toward the system administrators who will perform this. To upgrade an environment that is already running, see [Technical upgrade instructions](/deployment/docs/technical-upgrade-instructions). In the most common use case, you take the following steps on the application and trainer virtual machines: 1. Download, distribute, and unpack the Hyperscience bundle 2. Configure the environment variables 3. Start the application and the trainer > [!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). ## Before you begin Make sure you have completed the prerequisite steps to prepare your infrastructure and virtual machines, as outlined in [Hyperscience Infrastructure Prerequisites](/deployment/docs/hyperscience-infrastructure-prerequisites) and [Hyperscience Virtual Machine Prerequisites](/deployment/docs/hyperscience-virtual-machine-prerequisites). Make sure you are either a root user or that you have elevated root-level permissions (that is, you can execute `sudo` commands) on the machines that will run Hyperscience. ## Download, distribute, and unpack the install 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 multiple virtual machines, make sure you download it **once** and then distribute it internally within your own network. To download the bundle on a Linux virtual machine, execute this command: ```bash sudo wget ``` Once the bundle has been downloaded and distributed to all virtual machines, move it to the installation folder `/opt/hs` (recommended) and extract it: ```bash sudo tar -xzvf hyperscience-trainer-x.x.x.tgz ``` This extracts the file into a folder with the name of the archive. The folder contains the ".env" file, which you configure based on your setup. ## Install the application Complete the following steps on each application virtual machine in the cluster, in the order given. ### 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, proceed to the next step. If SELinux is enabled in enforcing mode, you also need to give your application containers access to the archive files that contain flow blocks. These blocks are required to process submissions in Hyperscience. To give the necessary permissions, run the following command: ```bash chcon -t container_file_t -R /sdm_blocks ``` If you do not, you see the following error when you attempt to initialize 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 Edit the ".env" file and fill in all relevant configuration information. You need to set the following variables at a minimum, and depending on your setup there may be more. You can add any additional configuration, such as authentication and security, at a later stage. ```ini # Database configuration FORMS_DB_TYPE= FORMS_DB_HOST= FORMS_DB_NAME= FORMS_DB_USER= FORMS_DB_PASS= # Initial admin user FORMS_USER= FORMS_PASS= # File storage FORMS_STORAGE_MODE= HS_PATH=/mnt/hs # Trusted origins domain if using Load Balancer HS_CSRF_TRUSTED_ORIGINS=https://test.com,https://*.subdomain.com ``` > [!NOTE] > Remove any ".env" variables that are left without a value to prevent startup issues. If you have more than one application virtual machine, distribute the same ".env" file across all machines. We validate the file's checksum at startup, and failing to do so results in startup failure on subsequent virtual machines. If you are running Hyperscience v38 or later behind a load balancer, set the `HS_CSRF_TRUSTED_ORIGINS` variable to prevent login issues. For more information, see the [Load Balancing](/deployment/docs/hyperscience-infrastructure-prerequisites#load-balancing) section of [Hyperscience Infrastructure Prerequisites](/deployment/docs/hyperscience-infrastructure-prerequisites). ### 3. Initialize the application on the first machine On initial install, and every time the ".env" file is edited, you must initialize the application on the first application virtual machine in the cluster. Go to the folder where the Hyperscience bundle was unpacked, and run the initialization script: ```bash sudo bash run.sh init ``` This script updates the database tables and prepares the application for startup. There is no need to run it on all machines in the cluster. ### 4. Start the application on all machines After running the `init` command, start the application containers on each machine in the cluster: ```bash sudo bash run.sh ``` This automatically starts the required application roles based on the configuration you have set. As long as Docker or Podman is configured to start at boot, the application also starts at boot. ### 5. Enter a license key 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., PROD, UAT or DEV) 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). > [!WARNING] > **Enter the license key before you install the trainer** > > The trainer connects to the application with an authentication token that you copy from the Users page. You cannot reach that page until the application is unlocked with a valid license key. ## Install the trainer 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. 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: ```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, 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, run the following commands, assuming that you are using the default `HS_PATH=/mnt/hs` variable: ```bash chcon -t container_file_t /mnt/hs/trainer_media mkdir -p /mnt/hs/postgres_trainer_ chcon -R -t container_file_t /mnt/hs/postgres_trainer_ # Hyperscience version numbers are formatted as follows: # .. # For example, if your application version is 42.3.2, 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 ``` ### 2. Configure the ".env" file Most of the ".env" configurations relate to the application, so when you install the trainer for the first time, 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`), proceed to the next step. If not, 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 configuration in the ".env" file: ```ini HS_PATH=/my/path/hs ``` ### 3. Start the trainer First, obtain an authentication token from a user with API permissions. This user can be any of these 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 [Connect the trainer through local or external users](/deployment/docs/technical-installation-upgrade-instructions#connect-the-trainer-through-local-or-external-users). Once you choose the type of user to get the token from, follow these steps to obtain the authentication token: 1. Log in to the application. 2. Click **Users**, and select the chosen user. 3. Find the user's **Authentication Token**, and click **Copy**. 4. Click **Done**. Next, go to the folder where the Hyperscience bundle was unpacked, and run the following command. 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. ```bash sudo bash run.sh trainer
#
: # 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. # : # 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: ```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 trainer https://10.0.0.5 2e831cc1a420a7a45264aab0624aa26d9da1aa70 ``` Here are some **examples of 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 <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 if using only one 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 — for example, the URL of the Hyperscience application changes, the application load balancer URL changes, a new API authentication token is used, SSL is configured, or LDAP is configured — you have to 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 [Security](/deployment/docs/security). ### 4. Connect the trainer through local or external 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](/deployment/docs/external-authentication-methods-and-api-users). If you are 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 connect through a local user, add the `TRAINER_USER` variable to the ".env" file of the application machine. 1. Add the `TRAINER_USER` variable to your application's ".env" file, with the username of your trainer's user as its value: ```bash TRAINER_USER= ``` 2. Restart the application: ```bash sudo bash run.sh init sudo bash run.sh ``` Once you start the trainer with the new token, your trainer's user is automatically added to the list of exempted users. > [!NOTE] > Editing the `TRAINER_USER` variable creates a new user with the username you enter, if it does not already exist. It does not remove the user previously created through the `TRAINER_USER` variable. **Trainer user from an external authentication method** If you are connecting the trainer through a user created with your external authentication method, add the trainer's username to the `TOKEN_REVALIDATION_EXEMPTED_USERS` variable. Do not add the `TRAINER_USER` variable to your ".env" file. For more information, see [External Authentication Methods and API Users](/deployment/docs/external-authentication-methods-and-api-users).