Deployment steps

Download OpenSpecimen

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


  1. Database: MySQL 8.0 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 installing new or upgrading OpenSpecimen from previous versions use the below command:

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

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

Notes for upgrade:

  1. The installer scripts automatically copies the new WAR and plugin and take the backup of existing WAR and plugins into $os_data/old_builds directory.
  2. Stop the Tomcat if running
  3. Take the backup of the custom plugins if any
  4. Take the backup of the database before upgrade

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