---
description: Instructions for deploying Study Tracker in a generic production environment
---

# Production Deployment

## 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](#enabling-saml-single-sign-on).

## Setting up the server

{% hint style="info" %}
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.
{% endhint %}

### Install system packages

*   Install required system packages, if needed:&#x20;

    ```
    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:&#x20;

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

    <pre class="language-bash"><code class="lang-bash"><strong>mvn -Dflyway.configFiles=flyway.conf -Dflyway.cleanDisabled=false flyway:clean flyway:migrate
    </strong></code></pre>

### Building Study Tracker

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

    ```bash
    git clone https://github.com/Study-Tracker/Study-Tracker.git
    cd Study-Tracker
    git checkout tags/v1.0.0
    ```
*   Compile the application source code:

    ```bash
    mvn clean package -DskipTests
    ```

### Run directory & configuration files

*   Create separate a directory to run the application from (eg. `/opt/study-tracker`):&#x20;

    ```
    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:&#x20;

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

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

    ```bash
    java -jar study-tracker.war
    ```

{% hint style="info" %}
While running a Spring Boot application like this technically works, it is best to run Study Tracker as a service, as described below.
{% endhint %}

## 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:

    ```bash
    sudo systemctl start study-tracker
    ```
3.  Enable auto-start of the application on server restart:

    ```bash
    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` ):

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

Follow the steps in the [Single Sign-On](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.&#x20;

{% hint style="warning" %}
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.
{% endhint %}

*   Stop the application server:

    ```bash
    sudo systemctl stop study-tracker
    ```
*   Pull the latest commit:

    ```bash
    git reset --hard HEAD
    git pull --force
    git checkout tags/vX.X.X
    ```
*   Build the application:

    ```bash
    mvn clean package -DskipTests
    ```
*   Copy the artifacts to your run directory and restart the service:

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