Deployment steps

Download OpenSpecimen

Enterprise EditionEmail contact@openspecimen.org
Community EditionDownload the code from Github  and follow steps on How to build from code?)

Prerequisites

  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

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

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

MySQLOracle
Driver class namecom.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"/>

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

Deployment

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

Edit "openspecimen.properties"

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 openspecimen.properties file.

FieldDescriptionValues
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.dirThe 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

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

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./install.sh <absolute_path_to_openspecimen.properties>
Windows./install.bat <absolute_path_to_openspecimen.properties>

Example : ./install.sh /usr/local/openspecimen/tomcat-as/conf/openspecimen.properties

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

Windows

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)

Linux

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

Start: $TOMCAT_HOME/bin/startup.sh

Stop: $TOMCAT_HOME/bin/shutdown.sh -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