Got feedback or spotted a mistake?

Leave a comment at the end of this page or email contact@krishagni.com

Deployment steps

Owned by Srikanth Adiga
Last updated: Nov 14, 2024 by Nilesh Salunke
4 min read

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

  1. Database: MySQL 8.0 or Oracle 11g/12c

  2. Set JAVA_HOME (Refer to this section for Java 17 changes)

  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

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

  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.

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:

  1. Download the build zip using the details provided by OpenSpecimen support team. 

  2. Once the build zip is extracted, copy the paid plugins (if any) under the new_plugins directory.

  3. 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.

  4. Stop the Tomcat if running

  5. Take the backup of the custom plugins if any

  6. 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

  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

Java 17 changes (Linux and Ubuntu)

OpenSpecimen version 10.1 onwards.

  1. Install Java 17 using the below command.

Ubuntu

sudo apt install openjdk-17-jdk openjdk-17-jre

RedHat

sudo dnf install java-17-openjdk-devel java-17-openjdk

2. Change the existing JAVA_HOME directory path in .bashrc file and point to the Java 17 directory.

3. Check the Java version using the below command.

              # java -version

4. Edit the $Tomcat_Dir/bin/setenv.sh file and remove the below lines.

             "-XX:PermSize=64m -XX:MaxPermSize=512m"

5. Add the below-mentioned Java specific startup parameters required by Tomcat in $Tomcat_Dir/bin/catalina.sh file.

             JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS --add-opens=java.base/java.net=ALL-UNNAMED

6. Deploy the OpenSpecimen build.

 

Java 17 changes (Windows)

OpenSpecimen version 10.1 onwards.

  1. Rename the existing Java folder under C drive C:\Program Files\Java to C:\Program Files\Java_bkp

  2. Uninstall the old java from the control Panel

  3. Download and install the Java 17 from here.

  4. Change the Java environment variables and insert the new path to the JDK folder.

  5. Check the Java version using below command once the installation is complete.
                 # java -version

  6. Edit the service.bat file inside $Tomcat_Home/bin/service.bat location.

  7. Find the following string "--JvmOptions9" in the service.bat file and add the below line.
                --add-opens=java.base/java.lang=ALL-UNNAMED#



  8. Edit the catalina.sh file, which can be found under $Tomcat_Home/bin/catalina.bat directory.

  9. Add the below parameter under the "JDK_JAVA_OPTIONS" options.
                JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS --add-opens=java.base/java.net=ALL-UNNAMED"

  10. Deploy the OpenSpecimen build.

Upload workflow licence in OpenSpecimen

  1. Navigate to Home → Extras → Licenses

  2. Click on upload license.

  3. Choose the provided license file and click on upload.

 

Got feedback or spotted a mistake?

Leave a comment at the end of this page or email contact@krishagni.com