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 17 or higher
Maven 3
PostgreSQL 13 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:
OpenSearch 2 (for enabling power search)
AWS EventBridge (for enabling external event publishing)
Benchling (for biology ELN)
Microsoft SharePoint, Amazon S3, or 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:
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=me@email.com
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-trackerThese 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 -DskipTestsWhile 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-1.0.0.war --spring.config.location=file:application.propertiesThis 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.
Last updated