Note: This page applies only for pre-5.0.2. For 5.1 onwards, refer to the below two pages:

Deployment steps (5.1 onwards)

Upgrade OpenSpecimen steps (5.1 onwards)

Download Latest OpenSpecimen

For Enterprise customers: For download details, please email contact@openspecimen.org

For Community edition: Download the code from Github  and follow steps on How to build from code?)

Prerequisites

1. Database: MySQL 5.7 or Oracle 11g/12c
2. See database privileges section
3. Java 8 JRE and JAVA_HOME is set.
4. MySQL on Linux: MySQL prerequisites on Linux

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

• MySQL (Ignore if you are going to use Oracle)
• JAVA
• Tomcat
• Apache for Linux
• Apache for Windows

Database Privileges

 Refer to Database Configuration

Database Import/Export

MySQL:

mysqldump -u<username> -p<password> --routines [database_name] > dumpfilename.sql

mysqldump -u<username> -p<password> --routines [database_name] | grep -v 'SQL SECURITY DEFINER' > dump.sql

Note: Use the second command when the test server dump is to be imported into the production database.

mysql -u<username> -p<password> [database_name] < dumpfilename.sql

Oracle:

expdp <username>/<password> full=y DIRECTORY=<DUMP_DIR> DUMPFILE=<dumpfilename.dmp> logfile=<logfile.log>

impdp <username>/<password> DIRECTORY=<DUMP_DIR> DUMPFILE=<dumpfilename.dmp> REMAP_SCHEMA=<from_user>:<to_user> logfile=<logfile.log> transform=oid:n

Deployment Instructions (for Enterprise Edition)

1. Unzip the installer file. Let's call the new folder OSPM_HOME
2. Change directory to OSPM_HOME

For Windows:

1. Double click on "openspecimen.exe" file which will start the installation wizard.
2. Follow the steps to proceed.

For Linux:

1. If MySQL, remember to perform steps here MySQL prerequisites on Linux 

2. Give executable permission using following command
   chmod +xopenspecimen.sh

3. You can install OpenSpecimen using one of below ways:
   

   1) GUI Mode

       With this mode, you can install OpenSpecimen with graphical user interface as follow:

   Start Installer wizard (Tomcat service will not be installed)

   ./openspecimen.sh

   
   

   2) Unattended mode

       With this mode first you must need to fill all valid values in properties.varfile (present in zip).

   Command to start installer in Unattended mode

   sudo ./openspecimen.sh -q -varfile properties.varfile

   
   

   Properties.varfile

   install_home	Valid directory path where OpenSpecimen needs to be installed.
   install_service	Whether to install tomcat as a service or not.yes- It will install tomcat service with name 'openspecimen' and will set it as an auto startup (Requires super admin privileges).no- It will not install tomcat service, but will start tomcat normally during installation.
   database_type	DB which you are going to use for installing OpenSpecimen (mysql / oracle).
   database_create	OnlyappliesforMySQLdatabase.yes- It will create a database with the specified name and will use same for OpenSpecimen.no- It won't create a new database, it will use existing database with the name provided in database_name.
   database_name	Name of the database will be used for OpenSpecimen.
   database_host	Hostname of the database server.
   database_port	The port on which database is running (default port are: MySQL - 3306 / Oracle - 1521).
   database_user	Database user name.
   database_password	Database password.
   app_server_port	The port on which Apache tomcat will start.
   app_host	Hostname of the application server.
   deployment_environment	development : It will set tomcat logging to Info, and will enable hibernate query logging. production : It will set tomcat logging to Error only, and will disable hibernate query logging.
   first_name	First name of the super admin user.
   last_name	Last name of the super admin user.
   email	The email address of the super admin user (This will be used as login name as well).
   password	Password for super adminusertologinintoOpenSpecimen.
   institute	Name of the institute whichwillbecreatedinOpenSpecimenon which super admin will get registered.

   
   

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

Upgrading existing versions of OpenSpecimen via Installer

Below are the few assumptions made during installation/upgradation.

• Consider installation directory is <install_home>.
• The installer will check whether tomcat is already present with name ‘tomcat-as’ under <install_home>. If yes, it upgrades existing one, else it will install new tomcat with name ‘tomcat-as’ which will be used for the OpenSpecimen installation.
• It will create ‘os-plugins’ directory in <install_home>, copy all plugins into this directory and use them for OpenSpecimen.
• It will create ‘os-data’ directory in <install_home> and use the same for OpenSpecimen.

NOTE: So while upgrading OpenSpecimen using an installer, please make sure the directory structure should be same as described above.

Tomcat Configuration Overwrite Policy

This applies only if you are installing OpenSpecimen on an existing Tomcat OR you have made some configuration changes OR have other applications deployed.

This should not apply to most installations where Tomcat is used only to deploy OpenSpecimen. 

In GUI mode: Select appropriate overwrite options. 

1. If "Yes/Yes to all" is selected,then it will use new database and tomcat port configuration.
2. If "No/No to all" is selected,then it will use existing tomcat configuration for database and port.

For "command line mode"

./openspecimen.sh -q -varfile properties.varfile -overwrite

Fresh/Upgrade: Data source handling

Data Source property for upgrading OpenSpecimen from OS 1.x to OS X.x via installer is handled automatically, no need to take extra care for this, the installer will automatically use relevant data source property.

Default Data Directory

Installer by default will create data directory with name "os-data" in the installation directory.

<installer-dir>/os-data

If you are having different data directory other than this default one, then please perform any of the following operation:

1)Ifyouwantstousedefault data directory created by the installer, then please update the locations (like sprpath, consent path etc...) via "Settings" menu and move data manually from older location to newer one.

2) If you want to use existing data directory, make sure directory is present & same location is used in "Settings" menu.

Plugin Directory

Installer by default will create plugin directory with name "os-plugins" in installation directory & will use the plugin from there only.

<installer-dir>/os-plugins

Super Admin Creation Via Installer

The installer will create a super admin only if there is no super admin present in the system.

Start/Stop OpenSpecimen server

OpenSpecimen(v3.3 onwards) installer supports the installation of Apache tomcat service, which is optional.

If user wants to install the service (which requires root privileges) then installer will install tomcat service with name "openspecimen" and will set this service to auto-start. 

If the user is not interested in installing service then it will start apache tomcat server once, and user will manually have to setup the service.

- It will start service with max heap size 2 GB.

For Windows:

-Set as service: Service can be started/stopped from windows services.

-Service not set: Use the below command:

• Open command prompt
• Go to ${TOMCAT_HOME}/bin
• ./catalina.bat start
• ./catalina.bat stop

For Linux:

-Set as a service:

• sudo service openspecimen start
• sudo service openspecimen stop
• sudo service openspecimen restart
  
  

-Service not set:

• Open command prompt
• Go to ${TOMCAT_HOME}/bin
• ./catalina.sh start
• ./catalina.sh stop

Refer to wiki page to create tomcat service manually

Plugin Deployment

Download and copy the plugin jar under ${install_home}/os-plugin directory. After copying the plugin you need to restart the tomcat.

Email Configuration

For email configuration, please refer: Email Configuration