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

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

  <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](/documentation/installation-and-configuration/single-sign-on.md) 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
  ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://study-tracker.gitbook.io/documentation/installation-and-configuration/production-deployment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.