> For the complete documentation index, see [llms.txt](https://study-tracker.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://study-tracker.gitbook.io/documentation/installation-and-configuration/production-deployment.md). # 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: 
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: ```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`): ``` 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` ```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. {% 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 ```