On-Premise Installation Instructions

1. Overview

Ursa Studio can run either on premise or in the cloud. On-premise installations can either be installed by hand on a VM or using one of our Docker images. This document is geared towards the traditional, by-hand install, but docker-based installs will follow many of the same steps.

Ursa Studio can be traditionally installed on any Linux VM. The “application database” can be installed on the same or on a different server as Ursa Studio.

The minimum recommended specifications for the Ursa Server are a 4-core, 8GB VM with 200GB of storage. These numbers are flexible and depend on the size and scope of the implementation. The server should be available via ports 80 and 443, and should have a HIPAA-compliant SSL certificate available.

2. Dependencies

The following software packages should be installed onto the server before installing Ursa Studio.

• PostgreSQL, version 10+. If the application database will reside on a different server, only the PostgreSQL client libraries are necessary.
• NodeJS, version 18.
• PM2, version 5+
• R, version 3.2+.
• Python, version 3.x
• Nginx, Apache, or equivalent
• AWS CLI
• Database driver binaries, as needed

3. Download Ursa Studio

Ursa Health staff will give you an AWS Access Key ID and an AWS Secret Access Key with permissions to download Ursa Studio onto your server. Plug these values into the aws configure command. You do not need to set a default region name or default output format. Ursa Health staff will furthermore give you the aws s3 download command to download Ursa Studio onto your server. You should download it into whichever directory from which you want to run the application. If you have a restrictive network environment, you might need to whitelist https://ursa-app-builds.s3.amazonaws.com for the aws s3 command to work.

4. Set up Application Database

Start PostgreSQL as a service on your server and create a database. By convention we typically call this database ursa_app_db, but you can call it whatever you want. Set up a service account for Ursa Studio. In the root directory of the Ursa Studio application code you just downloaded, you will see the ursa-app-database blank backup file. Use pg_restore to load the starter database from this backup file. There might be some errors about dropping schemas and tables that do not yet exist, or assigning to a user that does not exist, but these can be ignored.

5. Start Ursa Studio

You will find a list of required and optional environment variables in the Ursa Studio Technical Documentation file. Once you have loaded these into the environment you can verify that Ursa Studio is working by running npm start from within the ursa-app directory. If you see an ASCII picture of our logo and no errors, then the application is successfully running. Shut down the application and restart it in production mode via the command npm run start-production. Logs will be streamed to the folder you have designated as the URSA_OUTPUT_DIR environment variable. If you ever need to stop the application you can use the command npm run stop-production.

6. Set up Web Server

Before configuring your web server you should have decided on a domain name and have acquired a HIPAA-compliant SSL certificate.

The Ursa Studio application accepts requests over port 1337, but it should not be connected directly to the internet. You will want to set up a web server such as nginx or apache as a reverse proxy. The web server will need to redirect 80->443, terminate SSL, and forward requests from 443 to 1337. If requested, Ursa Health staff can provide an example nginx configuration file which performs these three tasks.

7. Start Using Ursa Studio

Congratulations! If you have followed all of these steps you should be able to get to the login screen of the Ursa Application.

Before you move on you should familiarize yourself with the Ursa Health Software Platform Technical Documentation. In particular, you should have set up transactional e-mail integration for the next step.

After the initial setup is complete, the application will be in a liminal state in which it has no registered users. The first user--and the first user only--can and must be generated by the app. To do so, enter the first user’s email address as the username, and a specialized keyword as the password which can be supplied by the Ursa Health team. The first user will be created via a transactional email sent to this email address.

After the first user has been created this technique will not work.

8. Bump the Ursa Studio version

The most common maintenance step you will need to perform will be the periodic upgrade of the Ursa Studio version. You can do this by means of a script named traditional-upgrade-app.sh that you will find in the scripts directory of the application code. Copy it into a separate location, such as your home folder, before invoking it. For the script to work you will want to set the URSA_HOME environment variable to be the ursa-app directory in which the application code is installed.