| Table of Contents |
|---|
Download OpenSpecimen
...
Prerequisites
- Database: MySQL 5.7/ 8.0 or Oracle 11g/12c
- Java 8 JDK and Set JAVA_HOME is set.(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.
...
| 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
| Code Block | ||
|---|---|---|
| ||
<Environment name="config/openspecimen" value="$TOMCAT_DIR/conf/openspecimen.properties" type="java.lang.String"/> |
...
| 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 Upgrading installing new or upgrading OpenSpecimen from versions after v5.0 or installing OpenSpecimen for the first time. Use the below command.
Before running the installer.
...
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
Note: 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
...
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 -version - Edit 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.