Instructions for setting up Study Tracker (v 0.5.0)

Elasticsearch-setup.md

Elasticsearch Setup

1. Create new Elasticsearch domain with the desired configuration. Be sure to enable SSL and user-authentication.
2. Create a user for your Study Tracker integration (eg. studytracker).
3. Create a role for the user, grant it unlimited privileges on the studies index and the indics:data/write/bulk permission.

Study-Tracker-Setup.md

Study Tracker Setup

These instructions assume that you have a working VM with a current LTS version of Ubuntu:

• Created a PostgreSQL database that can be used by Study Tracker.

• Have a configured Benchling tenant. This is optional to run Study Tracker, but the configuration described below includes Benchling references.

• Have a configured Egnyte tenant. This is also optional.

• Have Okta configured for your organization and have created an app in your SSO dashboard for Study Tracker.

  • Configure your app with the single-sign-on URL ending in /saml/SSO and the audience URI/SP Entity ID ending in /saml/metadata.
  • So for example, if your Study Tracker app was being hosted at https://mystudytracker:8443, the SSO URL value would be https://mystudytracker:8443/saml/SSO. These URLs are case-sensitive.

Setting up the server

• Install Java, Maven, Git, and NPM

   sudo apt-get install openjdk-11-jdk
   sudo apt-get install maven
   sudo apt-get install npm
   sudo apt-get install git

• Update NPM and dependencies

   sudo npm install -g npm less less-watch-compiler webpack webpack-cli
   

Downloading Study Tracker

• Generate an RSA key for cloning the repository. Don't use a password.

   ssh-keygen -t rsa -b 4096
   

  Associate the generated public key with your GitHub account so that you can clone the repository.

• Clone the repository into a directory of your choice.

   git clone git@github.com:Decibel-Therapeutics/Study-Tracker.git
   

  Enter the directory you cloned the repository to.

• For now, checkout and use the development branch:

   git checkout development
   

Configure Study Tracker

• Create a flyway.conf file with the following info:

   flyway.user=studytracker
   flyway.password=studytracker
   flyway.url=jdbc:postgresql://localhost:5432/study-tracker
   
  

• Run Flyway to clean and populate the database with initial state

   mvn -Dflyway.configFiles=flyway.conf flyway:clean
   mvn -Dflyway.configFiles=flyway.conf flyway:migrate
   

• Create a P12 keystore and self-signed certificate for SSL in the directory src/main/resources

   keytool -genkeypair -alias stsslstore -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore stssl.p12 -validity 3650
   

• Create a JKS keystore for SAML authentication in the directory src/main/resources

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

• Create a application.properties file in the directory src/main/resources. Sample contents:

   # Application
   application.host-name=myhost.com
   
   # Admin
   admin.email=me@email.com
   admin.password=xxxxxx
  
   # Data Source
   db.username=studytracker
   db.password=xxxxx
   db.host=localhost
   db.port=5432
   db.name=study-tracker
  
   # JPA
   spring.jpa.show-sql=true
   spring.jpa.hibernate.ddl-auto=validate
  
   # AWS
   aws.region=us-east-1
   aws.access-key-id=xxxxxx
   aws.secret-access-key=xxxxxx
   
   # Events
   events.mode=eventbridge
   aws.eventbridge.bus-name=research-data-dev
  
   # Email
   spring.mail.host=xxxxx
   spring.mail.port=xxxxx
   spring.mail.username=xxxxx
   spring.mail.password=xxxxx
   spring.mail.properties.mail.smtp.auth=true
   spring.mail.properties.mail.smtp.starttls.enable=true
   email.outgoing-email-address=${spring.mail.username}
  
   ### Notebook
   # Options: none, idbs, benchling
   notebook.mode=benchling
   benchling.eln.api.token=xxxxx
   benchling.eln.api.root-url=https://mytenant.benchling.com
   benchling.eln.api.root-entity=
   benchling.eln.api.root-folder-url=${benchling.eln.api.root-url}/decibeltest/f_
  
   ### Storage
   # Options: local, egnyte
   storage.mode=egnyte
   storage.use-existing=true
   storage.max-folder-read-depth=3
   
   # Local
   storage.temp-dir=/tmp
   storage.local-dir=${storage.temp-dir}
   
   # Egnyte
   egnyte.root-url=https://mytenant.egnyte.com
   egnyte.api-token=xxxxx
   egnyte.root-path=Shared/General/StudyTracker
   egnyte.qps=3
   
   ### Studies
   study.default-code-prefix=ST
   study.default-external-code-prefix=EX
   study.code-counter-start=10001
  
   ## SSL (optional)
   server.port=8443
   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
  
   ## Okta
   sso.url=xxxxx
   security.sso=okta-saml
   saml.audience=xxxxx
   saml.idp=xxxxx
   saml.metadata-url=xxxx
   saml.keystore.location=classpath:saml-keystore.jks
   saml.keystore.alias=stsaml
   saml.keystore.password=xxxx
   
  

Adding a company logo

• Create a folder named images within the directory src/main/resources/static.

• Copy a PNG image file to this directory and name it logo.png.

Running Study Tracker

• Build the application:

   npm install
   npm run build
   mvn clean package -DskipTests
   
  

• Run the app:

   java -jar /path/to/study-tracker.war

The first time you run Study Tracker, no users will be registered in the app. Upon initialization, the application will create an admin user with a temporary password. Look for this line in the output log:

2021-08-10 18:25:09.106  INFO 732669 --- [           main] c.d.s.c.i.AdminUserInitializer           : Created admin user with username 'admin' and password 'xxxxxx'. You should change this password from the login page as soon as possible.

Make a note of this password and use it to login to the application. You should change this password as soon as possible in the login screen.

Running as a service

• 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=/path/to/app
   ExecStart=/usr/bin/java -jar study-tracker.war
   Restart=always
   StandardOutput=syslog
   StandardError=syslog
   SyslogIdentifier=study-tracker
  
   [Install]
   WantedBy=multi-user.target
  

• Start the service:

   sudo systemctl start study-tracker

• Enable auto-start of the application on server restart:

   sudo systemctl enable study-tracker

Updating Study Tracker

• Stop the application server:

   sudo systemctl stop study-tracker

• Pull the latest commit:

   git reset --hard HEAD
   git pull --force

• Update the database:

   mvn -Dflyway.configFiles=flyway.conf flyway:migrate

• Build the application:

   npm install
   npm run build
   mvn clean package -DskipTests

• Copy the artifacts to the appropriate location and restart the service:

   sudo systemctl start study-tracker

Signing in the first time

Production Deployment Changes

When deploying in a production environment, there are a few things you should do differently.

• Run the server on port 443. You can configure this in the application.properties file.

   server.port=443