Leave a comment at the end of this page or email contact@krishagni.com
Deployment steps
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
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)
Tomcat (Use the Tomcat zip provided into OpenSpecimen build zip)
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 |
|
Oracle |
Note: |
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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|
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/openspecimenUsername: admin (password: Login@123)
Additional Configuration
Java 17 changes (Linux and Ubuntu)
OpenSpecimen version 10.1 onwards.
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.
Rename the existing Java folder under C drive C:\Program Files\Java to C:\Program Files\Java_bkp
Uninstall the old java from the control Panel
Download and install the Java 17 from here.
Change the Java environment variables and insert the new path to the JDK folder.
Check the Java version using below command once the installation is complete.
# java -versionEdit the service.bat file inside $Tomcat_Home/bin/service.bat location.
Find the following string "--JvmOptions9" in the service.bat file and add the below line.
--add-opens=java.base/java.lang=ALL-UNNAMED#Edit the catalina.sh file inside $Tomcat_Home/bin/catalina.bat location.
Add the below parameter under the "JDK_JAVA_OPTIONS" options.
JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS --add-opens=java.base/java.net=ALL-UNNAMED"Deploy the OpenSpecimen build.
Upload workflow licence in OpenSpecimen
Navigate to Home → Extras → Licenses
Click on upload license.
Choose the provided license file and click on upload.
Leave a comment at the end of this page or email contact@krishagni.com