Table of Contents |
---|
...
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. These pre-requisites can be downloaded from http://www.openspecimen.org/prerequisites/
- 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
v4v6.
21.
4RC7 # example to checkout source code of
OpenSpecimen v4.2.4OpenSpecimen
v6.1.RC7
Do all the pre-requisites setup before deploying WAR file.
- Use
gradle
to build and deploy the application.
...
- For database privileges, refer to Database Configuration
- Java 8 JRE and JAVA_HOME is set.
- MySQL on Linux: MySQL Case Sensitivity issues on Linux
Following table lists pre-requisites and their supported versions.
Recommended The recommended memory requirement for OpenSpecimen app is 2GB. To configure Tomcat follow How to fix "out of memory" error ?
...
You'll also need to place appropriate connector jar for MySQL/Oracle under 'lib' directory in tomcat server.
Environment Variables
Following table lists and describes environment variables
...
Database | Command |
---|---|
MySQL |
|
Oracle |
Note: |
Configuring build.properties
...
Absolute path of the directory where Tomcat server is extracted and installed.
Note the path must be made up of forward slashes (/) instead of backward slashes (\)
...
app_data_dir
...
Create a new folder within 'app_home, say 'os-data' and specify it here.
Note the path must be made up of forward slashes (/) instead of backward slashes (\)
...
app_log_conf
...
The path of the logging configuration properties file. This property is optional, if kept empty default logging configuration will be used.
Note the path must be made up of forward slashes (/) instead of backward slashes (\)
...
Name of JDNI datasource configured in Tomcat/JBoss for connecting to database
...
java:comp/env/jdbc/openspecimen
...
Specifies type of deployment - whether the database was setup for pre-OS v2.0 or was setup for OS v2.0 onwards.
fresh: Database was created starting with OS v2.0
upgrade: Database was created using pre-OS v2.0 app
...
Hostname or IP address of machine running DBMS server software
...
Port on which DBMS server software listens for incoming requests
Commonly used port numbers are:
MySQL: 3306
Oracle: 1521
...
Database name for storing data. This is same as configured or created in database configuration step above
...
Valid DBMS user name for connecting to the database
...
Valid DBMS user password for authenticating and connecting to database
...
This is optional and needed only if you are using any plugins.
Create a new folder within 'app-dir' and specify there. This is where all the plugin JARs should exist. E.g. 'os-plugins'.
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.
Code Block |
---|
<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
Code Block |
---|
<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" |
Property Name | Description | Default Value | Allowed Values | ||||
---|---|---|---|---|---|---|---|
app_home | The absolute path of the directory where Tomcat server is extracted and installed. | None | Example: /usr/local/apache-tomcat-7.0/os-plugins | show_sql | A boolean switch indicating whether SQL statements should be printed in log files | false | true, falseopenspecimen/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
Note: Above commands needs to be executed successfully.
- Change directory to root directory of source code.
cd ..
- Use the following command to build and deploy OpenSpecimen into 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 the Tomcat process 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 |
|
|
Stop |
|
|
Setup OpenSpecimen project in Eclipse or Intellij
...
- Open command terminal
- Change to directory to root directory i.e
$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 createopenspecimen.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:
- Open File -> Import -> Existing Projects into Workspace
- Select the root directory of our project (i.e openspecimen). Project will get imported successfully
- Intellij:
- Open File -> Open and select the root folder of our project. (i.e openspecimen)
- Click on 'ok' on the next dialog. Project The project will get imported successfully.
Data Source Configuration in Tomcat Application Server
You will need to setup data source configuration in $TOMCAT_HOME/conf/context.xml file as below.
...
language | bash |
---|---|
title | Tomcat Configuration |
...
Here, driverClassName and URL should be like below:
Driver Class Name:
MySQL: com.mysql.jdbc.Driver
Oracle: oracle.jdbc.OracleDriver
Note: The appropriate driver jar file should be added to the Tomcat/lib directory.
DB URL:
MySQL: jdbc:mysql://<db_host>:<db_port>/<db_name>
Oracle: jdbc:oracle:thin:@<db_host>:<db_port>:<dbname>
Start and Shut Down the Application Server
...
Operation
...
Windows
...
Linux
...
Start
...
$TOMCAT_HOME/bin/catalina.bat start
...
$TOMCAT_HOME/bin/catalina.sh start
...
Stop
...
$TOMCAT
_HOME/bin/shutdown.bat
...
- .
...