Getting Started

From zero to running Study Tracker

Requirements

Depending on your needs, Study Tracker can be run with a number of different service integrations. The bare-minimum requirements for running Study Tracker are as follows:

• Java JDK 11 or higher

• Maven 3

• PostgreSQL 12 or higher

If you'd like to get the most out of what Study Tracker can offer, you should run it on AWS and integrate with the following additional services:

• ElasticSearch 7.10 (for enabling power search)

• AWS EventBridge (for enabling external event publishing)

• Benchling (for biology ELN)

• Egnyte (for cloud storage)

• Okta (single sign-on)

Additional service integrations are in the works, but these are the current production-ready ones.

Building and Running

Currently, the best way to run Study Tracker is to build it from source. You can find the latest stable build on the GitHub releases page:

Releases · Study-Tracker/Study-TrackerGitHub

Follow the instructions below to build and run Study Tracker with a minimal configuration, substituting any placeholder values (such as database host or passwords) with the appropriate values. Additional configuration is required to enable all of Study Tracker's available features, you can find a full list of the required steps further in this documentation. Suggested steps for setting up a production deployment are also available here.

Create the database

Study Tracker requires a PostgreSQL database for storing its data. Assuming you have an instance running locally or remote, you can run the following commands to create a new user and schema for Study Tracker:

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

Create an application configuration file

Study Tracker is a Spring Boot web application and uses .properties files to define required and optional configuration parameters. The top level of the project includes a application.properties.example file that can be used as a template for configuring Study Tracker. Copy or rename this file to application.properties and update the following properties:

### 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=localhost


# 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=studytrackerstudytracker


### 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=[e-mail]
admin.password=mypassword


### 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=st_user
db.password=anotherpassword
db.host=localhost
db.port=5432
db.name=study-tracker

These are the minimum required configuration parameters required to run Study Tracker. The admin email and password will be used to define a super user that you will use to sign into the application after it starts and perform configuration (you can change the password later).

Build the application

Study Tracker is a compiled and deployed as an executable WAR file. From the top-level of the project directory, run the following command to build the application:

mvn clean package -DskipTests

While the Study Tracker front-end is a React web application, Maven will use the frontend-maven-plugin to download NodeJS and NPM, install all dependencies, and compile the required code. Once complete, the compiled WAR file can be found in target/study-tracker-[VERSION_NUMBER].war.

Run the application

To run the compiled WAR file, simple execute:

java -jar web/target/study-tracker-0.7.2.war --spring.config.location=file:application.properties

This will start the embedded Tomcat web server and deploy Study Tracker. If no other parameters were configured in the application.properties file other than the required ones above, the application will be reachable at http://localhost:8080.