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

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

Start the service:
```
sudo systemctl start study-tracker
```
Enable auto-start of the application on server restart:
```
sudo systemctl enable study-tracker
```

Enabling SSL

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
```

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

PreviousUpgrading to Version 1.0 NextConfiguration Properties Reference

Last updated 25 days ago