Introduction

This document describes steps to build OpenSpecimen from source code and to set up a development environment. This guide is intended for developers or technical IT staff. Following are high-level steps of building OpenSpecimen code:

Install/Setup pre-requisite software. Refer to pre-requisites table below.
Use the below command to download the source code:
$ git clone --depth 10 https://github.com/krishagni/openspecimen.git
Above command will checkout the master branch or unreleased version of code. If you wish to build source code of a specific release then use below command before proceeding to build. The list of available release version tags can be view here: https://github.com/krishagni/openspecimen/releases
$ git checkout <release-version-tag> $ git checkout v6.1.RC7 # example to checkout source code of OpenSpecimen v6.1.RC7
Do all the pre-requisites setup before deploying WAR file.
Use gradle to build and deploy the application.

Prerequisites

For database privileges, refer to Database Configuration
Java JRE and JAVA_HOME is set.
MySQL on Linux: MySQL Case Sensitivity issues on Linux

Following table lists pre-requisites and their supported versions.

Pre-requisite	Version
JDK	17
Tomcat	9.0+
MySQL	8.0+
Oracle	11g+
Gradle	7.5.1
GIT	2.17.1
node.js	10+
npm	7+
bower	1.8
grunt	1.2

The recommended memory requirement for the OpenSpecimen app is 2GB. To configure Tomcat follow How to fix "out of memory" error?

Note: For the database, you can choose between Oracle or MySQL.

You'll also need to place an appropriate connector jar for MySQL/Oracle under the 'lib' directory in the tomcat server.

Environment Variables

Following table lists and describes environment variables

Environment Variable	Description
JAVA_HOME	The absolute path of the directory where JDK is installed. For example`:` `C:\JDK17`

Environment Variable

Description

JAVA_HOME

The absolute path of the directory where JDK is installed. For example:

C:\JDK17

Please refer to the following variables used throughout the document.

Keyword	Comment
`OS_HOME`	Directory where OpenSpecimen source code is checked-out. For example, `F:\OpenSpecimen`.
`JAVA_HOME`	Directory where JDK is installed. For example, `C:\JDK17`

Database configuration

The deployment process involves some database operations which require specific privileges set for the database user. Use the below command to create a database. Refer to Database Configuration and make sure these privileges are assigned before the deployment process.

Database Command

MySQL

Database	Command
MySQL	`create database <database-name>` `<database-name>`: name of the database to be used for storing OS data
Oracle	`create user <username> identified by <password>` Note: `<username>, <password>` has to be replaced with database username and password

create database <database-name>

<database-name>: name of the database to be used for storing OS data

Oracle

create user <username> identified by <password>

Note: <username>, <password> has to be replaced with database username and password

Configure Tomcat context.xml

Note: This section is applicable for the fresh install and upgrading OpenSpecimen from older versions before v5.0.

For Linux, configure the PID.txt path using the instructions here: How to run Tomcat using PID on Linux?

Refer to the attached context.xml for reference.

Configure the data source name in $TOMCAT_HOME/conf/context.xml using the snippet below.

<Resource name="jdbc/openspecimen" auth="Container" type="javax.sql.DataSource"
  maxActive="100" maxIdle="30" maxWait="10000"
  username="<db_user_name>" password="<db_password>"
  driverClassName="<DRIVER_CLASS_NAME>"
  url="<DB_URL>"
  testOnBorrow="true" validationQuery="select 1 from dual" />

	MySQL	Oracle
Driver class name	com.mysql.jdbc.Driver	oracle.jdbc.OracleDriver
DB URL	jdbc:mysql://<db_host>:<db_port>/<db_name>	jdbc:oracle:thin:@<db_host>:<db_port>:<dbname>

Add below XML fragment below <Resource> tag in $TOMCAT_HOME/conf/context.xml

<Environment
  name="config/openspecimen"
  value="$TOMCAT_DIR/conf/openspecimen.properties"
  type="java.lang.String"/>

Note: The word "openspecimen" above could be different based on your configuration. E.g. "os-test", "os-prod" etc.

Edit "openspecimen.properties"

Note: Please make sure data & plugin directory are present at the specified path.

Attaching openspecimen.properties.

Field	Description	Values
app.name	This field is useful for deploying multiple OpenSpecimen instances on the same Tomcat server. E.g. You can use "os-test" and "os-prod".	Typically this is "openspecimen".
tomcat.dir	The absolute path to the Tomcat directory
app.data_dir	Absolute path to OpenSpecimen data directory.	Best practice: Create a folder in parallel to 'tomcat.dir' with the name "OpenSpecimen/data"
app.log_conf	The folder where the OpenSpecimen logs should be created	If left empty logs are created in "app.data_dir/logs"
datasource.jndi	Name of datasource configured in "context.xml"	Usually, it is "jdbc/openspecimen".
datasource.type	"fresh": If your database schema is created by OpenSpecimen from scratch. "Upgrade": if your database schema is upgraded from a caTissue database. Note: The name is a bit misleading, we will fix this in v5.2.	"fresh" or "upgrade"
database.type	MySQL or Oracle	"mysql" or "oracle"
plugin.dir	Absolute path to the plugin directory.	Best practice: Create a folder in parallel to 'tomcat.dir' with the name "OpenSpecimen/plugins"

Configure build.properties

Property Name	Description	Default Value	Allowed Values
app_home	The absolute path of the directory where the Tomcat server is extracted and installed.	None	Example: /usr/local/openspecimen/tomcat-as

Notes:

Make sure all the above database and Tomcat configuration are done properly.
Copy the openspecimen.properties from downloaded location to $TOMCAT_HOME/conf directory.
Before starting deploy make sure no Tomcat process is running.

Steps to deploy

The OpenSpecimen build system uses Gradle to manage code compilation, building web application archives, and deploying the application.

Open command terminal
Change to the directory where OpenSpecimen source code is checked-out
- cd $OS_HOME
Setup npm & bower dependencies.
- ```
cd www/
```
- ```
npm install
```
- ```
bower install
```
Change directory to root directory of source code.
- ```
cd ..
```
Use the following command to build and deploy OpenSpecimen into the app_home directory (Tomcat or JBoss server).
- gradle deploy
To only compile Java source files use the following command
- gradle compileJava
To build OpenSpecimen web app archive without deploying use following command
- gradle build

Once "gradle deploy" is ran successfully, start Tomcat and monitor the log files.

$TOMCAT_HOME/logs/catalina.out
$OS_DATA_DIR/logs/os.log

Start and Shut Down the Application Server

Operation	Windows	Linux
Start	`$TOMCAT_HOME/bin/catalina.bat start`	`$TOMCAT_HOME/bin/./startup.sh`
Stop	`$TOMCAT_HOME/bin/shutdown.bat`	`$TOMCAT_HOME/bin/./shutdown -force`

Setup OpenSpecimen project in Eclipse or Intellij

OpenSpecimen creates project and classpath files for Eclipse and Intellij IDE. Using that created project file, it is very easy to import OS source code into Eclipse and Intellij.

To create the project setting and classpath file, follow the below steps

Open command terminal
Change to directory to root directory i.e $OS_HOME.
Run below commands for your IDE
1. For Eclipse : gradle eclipseThis command creates the .project, .classpath files and .settings folder which is essential for project to be recognized as eclipse project.
2. For Intellij : gradle ideaThis command create openspecimen.iml, openspecimen.ipr, openspecimen.iws files which are essential for project to be recognized as Intellij project.
Now import the project into IDE using import from existing sources.
1. Eclipse:
  1. Open File -> Import -> Existing Projects into Workspace
  2. Select the root directory of our project (i.e openspecimen). Project will get imported successfully
2. Intellij:
  1. Open File -> Open and select the root folder of our project. (i.e openspecimen)
  2. Click on 'ok' on the next dialog. The project will get imported successfully.