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 |
---|---|
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:
- 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)
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.