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:
$ git clone --depth 10 https://github.com/krishagni/openspecimen.git
$ 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.
gradle
to build and deploy the application.Following table lists pre-requisites and their supported versions.
Pre-requisite | Version |
---|---|
JDK | 17 |
Tomcat | 9+ |
MySQL | 5.7 |
Oracle | 11g+ |
Gradle | 2.9 |
GIT | 1.8 |
node.js | 10+ |
npm | |
bower | |
grunt |
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
|
Please refer to the following variables used throughout the document.
Keyword | Comment |
---|---|
| Directory where OpenSpecimen source code is checked-out. For example, |
| Directory where JDK is installed. For example, |
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 |
|
Oracle |
Note: |
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.
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:
The OpenSpecimen build system uses Gradle to manage code compilation, building web application archives, and deploying the application.
cd $OS_HOME
cd www/
npm install
bower install
cd ..
gradle deploy
gradle compileJava
gradle build
Once "gradle deploy" is ran successfully, start Tomcat and monitor the log files.
Operation | Windows | Linux |
Start |
|
|
Stop |
|
|
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
$OS_HOME.
Run below commands for your IDE
For Eclipse : gradle eclipse
This command creates the .project, .classpath
files and .settings
folder which is essential for project to be recognized as eclipse project.
For Intellij : gradle idea
This 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.
Eclipse: