Production Deployment

Instructions for deploying Study Tracker in a generic production environment

Overview

Once you are ready to deploy Study Tracker to a remote host, follow the steps below. These instructions assume that you have done a few things already:

• Created a VM with the following things installed:

  • JDK 17+

  • Maven

  • Git

  • PostgreSQL Client

• Created a PostgreSQL database that can be used by Study Tracker.

• Have an SMTP server you can use for sending emails.

• (optional) Create an OpenSearch 2+ host for enabling Study Tracker's power search functionality.

• (optional ) Configure single-sign-on for Study Tracker.

Setting up the server

Study Tracker has been developed and run primarily on Mac OS & Ubuntu hosts. It should work in any environment with a supported JDK, but keep in mind that all instructions below assume a Linux host and Bash shell.

Install system packages

• Install required system packages, if needed:

  sudo apt-get update
  sudo apt-get install -y git openjdk-17-jdk maven postgresql-client

• (Optional) If running on AWS, you should install the AWS CLI as well:

  sudo apt-get install -y unzip
  curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
  unzip awscliv2.zip
  sudo ./aws/install

Create a new database and user

• If you have not already done so externally, create a new database schema and user for Study Tracker on your PostgreSQL host using the installed psql client:

  export PGPASSWORD=rootpassword
  psql -h my-host -p 5432 -d postgres -U postgres -c "create database \"study-tracker\""
  psql -h my-host -p 5432 -d postgres -U postgres -c "create user st_user with encrypted password 'userpassword'"
  psql -h my-host -p 5432 -d postgres -U postgres -c "grant all privileges on database \"study-tracker\" to st_user"

• (Optional) If you are planning on re-using and overwriting an existing Study Tracker database, it is recommended you refresh it using Flyway. First, in the web directory of the Study Tracker source code, a create a new file named flyway.conf and provide the following parameters:

  flyway.user=my-username
  flyway.password=my-password
  flyway.url=jdbc:postgresql://my-host:5432/study-tracker

• Run Flyway to clean and populate the database with initial state:

  mvn -Dflyway.configFiles=flyway.conf -Dflyway.cleanDisabled=false flyway:clean flyway:migrate

Building Study Tracker

• Clone the Study Tracker source code repository and checkout the latest stable build:

  git clone https://github.com/Study-Tracker/Study-Tracker.git
  cd Study-Tracker
  git checkout tags/v1.0.0

• Compile the application source code:

  mvn clean package -DskipTests

Run directory & configuration files

• Create separate a directory to run the application from (eg. /opt/study-tracker):

  mkdir /opt/study-tracker
  chown ubuntu:ubuntu /opt/study-tracker
  cp web/target/study-tracker-1.0.0.war /opt/study-tracker/study-tracker.war

• Create default file storage locations for file uploads and study data:

  mkdir /opt/study-tracker/uploads
  mkdir /opt/study-tracker/data

• (Optional) Create a JKS keystore for SAML (Single Sign-On w/ Okta) authentication in the run directory /opt/study-tracker

  keytool -genkeypair -alias stsaml -keypass mypassword -keystore saml-keystore.jks

• Create a application.properties file in the run directory /opt/study-tracker. You can use the application.properties.example file in the top-level of the Study Tracker source code repository as a template. The required fields are below:

  ### General properties ###
  
  # Required
  # Host name of your application (should not include protocol or port). This is used for generating
  # links to your application in emails and other notifications.
  # Eg. localhost or mywebsite.com
  
  application.host-name=
  
  
  # Required
  # Character sequence used for seeding encryption keys. This should ideally be a long, random string
  # of characters between 16 and 512 characters. It is important that you do not change this value
  # after setting it.
  
  application.secret=
  
  
  ### Admin User ###
  
  # Required
  # The first time Study Tracker starts, an admin user will be created. You must specify an email and
  # default password for the admin account. The password can be changed after initial startup. If no
  # password is provided, a random one will be generated and printed to the console at startup.
  
  admin.email=
  admin.password=
  
  
  ### Data Source ###
  
  # Required
  # Provide the connection information for the primary Study Tracker database. The user and schema
  # need to be configured ahead of time.
  
  db.username=
  db.password=
  db.host=
  db.port=
  db.name=
  
  
  ### Email ###
  
  # Required
  # Provide SMTP connection details for outgoing emails.
  email.host=
  email.port=
  email.username=
  email.password=
  email.smtp-auth=true
  email.smtp-start-tls=true
  email.outgoing-email-address=
  email.protocol=smtp
  
  
  ### File Storage ###
  
  # Determines where to create project folders and store study files uploaded by users. Can be either
  # a local file system (default), or a cloud storage service (eg. Egnyte).
  # Options: local, egnyte. Defaults to local
  
  storage.mode=local
  
  # If storage.use-existing is set to 'true', Study Tracker will use existing folders with the same
  # name when trying to create new ones. If set to 'false', Study Tracker throw an error when trying
  # to create a folder that already exists. Defaults to 'true'.
  
  storage.use-existing=true
  
  # Local file storage
  # Sets the directory used for uploading files.
  
  storage.temp-dir=/opt/study-tracker/uploads
  
  # Sets the folder in which the root program/study/assay storage folder hierarchy will be created.
  # Required if storage.mode is set to 'local'.
  
  storage.local-dir=/opt/study-tracker/data

Running Study Tracker

• Once the above steps have been completed and the Study Tracker .war file has been added to your run directory, alongside the application.properties file, you can run it with the following command:

  java -jar study-tracker.war

While running a Spring Boot application like this technically works, it is best to run Study Tracker as a service, as described below.

Optional Configurations

Running as a service

1. In the directory /etc/systemd/system/ create a file named study-tracker.service and give it the following contents:

   [Unit]
   Description=Study Tracker
   
   [Service]
   WorkingDirectory=/opt/study-tracker
   ExecStart=/usr/bin/java -jar study-tracker.war
   Restart=always
   StandardOutput=syslog
   StandardError=syslog
   SyslogIdentifier=study-tracker
   
   [Install]
   WantedBy=multi-user.target

2. Start the service:

   sudo systemctl start study-tracker

3. Enable auto-start of the application on server restart:

   sudo systemctl enable study-tracker

Enabling SSL

1. Generate a PKCS12 keystore for handling encryption keys and save it to the application run directory (eg. /opt/study-tracker). For example, to generate a keystore and self-signed certificate:

   keytool -genkeypair -alias stsslstore -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore stssl.p12 -validity 3650

2. Configure Study Tracker to use SSL and your created keystore by adding the following attributes to your application.properties file:

   server.port=8443  # use 443 for production
   server.ssl.enabled=true
   server.ssl.key-store-type=PKCS12
   server.ssl.key-alias=stsslstore
   server.ssl.key-store=classpath:stssl.p12
   server.ssl.key-store-password=xxxxx

Enabling SAML Single Sign-On

Create a JKS keystore for SAML (Single Sign-On w/ Okta) authentication in the application run directory (eg. /opt/study-tracker ):

keytool -genkeypair -alias stsaml -keypass mypassword -keystore saml-keystore.jks

Follow the steps in the Single Sign-On section to configure your provider of choice.

Updating Study Tracker

In most cases, it is possible to perform an in-place upgrade of Study Tracker by pulling the latest version of the source code repository and checking out the stable build you are interested in.

Upgrades always have the potential to go wrong, so be sure to back-up your instance and PostgreSQL database before proceeding. There is no need to backup the ElasticSearch database, as it rebuilds itself automatically on startup.

• Stop the application server:

  sudo systemctl stop study-tracker

• Pull the latest commit:

  git reset --hard HEAD
  git pull --force
  git checkout tags/vX.X.X

• Build the application:

  mvn clean package -DskipTests

• Copy the artifacts to your run directory and restart the service:

  cp web/target/study-tracker-X.X.X.war /opt/study-tracker/study-tracker.war
  sudo systemctl start study-tracker