Deployment steps

Download OpenSpecimen

Enterprise EditionEmail
Community EditionDownload the code from Github  and follow steps on How to build from code?)


  1. Database: MySQL 5.7 or Oracle 11g/12c
  2. Java 8 JDK and JAVA_HOME is set.
  3. Tomcat 9 and its service
  4. MySQL prerequisites

Please visit the respective download centers and download the latest version available for your operating system:

Note: Make sure MySQL prerequisites are configured correctly before moving on to the next steps.

Create Database

Note: Applicable only for a fresh install


create database <database-name>

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


create user <username> identified by <password>

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

Note: Database privileges

Refer to Database Configuration to set the proper privileges.

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>"
  testOnBorrow="true" validationQuery="select 1 from dual" />

Driver class namecom.mysql.jdbc.Driver


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


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


  1. Unzip the installer file. Let's call the new folder OSPM_HOME
  2. Change directory to OSPM_HOME

Edit ""

Note: If the data & plugin directory is not present at the specified path, installer script will create data & plugin directory at the specified path provided in the file.


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.dirThe absolute path to the Tomcat directory

Absolute path to OpenSpecimen data directory.

Best practice:

Create a folder in parallel to 'tomcat.dir' with the name "openspecimen/data"


Folder where the OpenSpecimen logs should be created

If left empty logs are created in "app.data_dir/logs"

datasource.jndiName of datasource configured in "context.xml"Usually, it is "jdbc/openspecimen".

"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.typeMySQL or Oracle

"mysql" or "oracle"


Absolute path to the plugin directory.

Best practice:

Create a folder in parallel to 'tomcat.dir' with the name "openspecimen/plugins"

Install / Upgrade

For Upgrading OpenSpecimen from versions after v5.0 or installing OpenSpecimen for the first time. Use the below command.

Before running the installer, shut down the Tomcat service (Windows user only).

Operating systemCommand
Linux./ <>
Windows./install.bat <>

Example : ./ /usr/local/openspecimen/tomcat-as/conf/

Note: The installer scripts automatically copies new WAR and plugin and took the backup of existing WAR and plugins into $os_data/old_builds directory.

Starting/Stopping OpenSpecimen


Start: Go to Task manager => Services tab => Click on  Apache Tomcat 9 service => Click on Start link. (In left panel)

Stop: Go to Task manager => Services tab => Click on  Apache Tomcat 9 service => Click on Stop link. (In left panel)


The installer starts OpenSpecimen automatically. If not started, run the following command:

Start: $TOMCAT_HOME/bin/

Stop: $TOMCAT_HOME/bin/ -force

Accessing OpenSpecimen

  1. Open a browser: Chrome, Firefox, Safari, IE (11 and above only)
  2. Type in: http://<SERVER_IP_ADDRESS>:<APP_SERVER_PORT>/openspecimen/
    E.g. http://localhost:8080/openspecimen
  3. Username: admin (password: Login@123)

Additional Configuration

  1. Email Configuration
  2. Locale Configuration

  3. LDAP Configuration