1 Download OpenSpecimen
2 Prerequisites
3 Create Database
- 3.1 Note: Database privileges
4 Configure Tomcat context.xml
5 Deployment
- 5.1 Edit "openspecimen.properties"
- 5.2 Install / Upgrade
- 5.3 Starting/Stopping OpenSpecimen
- 5.4 Accessing OpenSpecimen
- 5.5 Additional Configuration

Download OpenSpecimen

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

Prerequisites

Database: MySQL 8.0 or Oracle 11g/12c
Set JAVA_HOME (Refer to this section for Java 17 changes)
Tomcat 9 and its service
MySQL prerequisites

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

MySQL (Ignore if you are going to use Oracle)
Java
Tomcat (Use the Tomcat zip provided into OpenSpecimen build zip)
Apache for Linux
Apache for Windows

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

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" />

	MySQL	Oracle

	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"/>

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

Deployment

Unzip the installer file. Let's call the new folder OSPM_HOME
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.

Field	Description	Values

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

Install / Upgrade

For installing new or upgrading OpenSpecimen from previous versions use the below command:

Operating system	Command

Operating system	Command
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

Notes for upgrade:

Download the build zip using the details provided by OpenSpecimen support team.
Once the build zip is extracted, copy the paid plugins (if any) under the new_plugins directory.
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.
Stop the Tomcat if running
Take the backup of the custom plugins if any
Take the backup of the database before upgrade

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

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

Deployment steps