Installation of the web application for generating and modifying phenotyping schemes
====================================================================================

The application has been tested both on linux (CentOS 6.4) and windows (Windows7). A basic knowledge of doing installations on at least one of the operating systems is assumed.

The PhenotypingSchemeComposer requires a set of software which is available for free. The application was tested with the specified versions but new versions may also work.

- MySQL 5.5 and MySQL-Workbench 5.2 (if not already done during intallation of the result web application) can be downloaded from http://dev.mysql.com/downloads/. Please follow the installation instructions available from there. MySQL-Workbench is not absolutely necessary but makes all administration tasks much easier. You should create one database user which will be used for making the connection from the website to the database. This user should be allowed to insert, select, update and delete database entries but nothing more.

- Tomcat 6.0.x is available through http://tomcat.apache.org/ along with installation instructions. For deploying the web application is is necessary to create at least one tomcat user with manager role (in conf/tomcat-users.xml). Maybe you will have to install a Java runtime environment too.

- Tool for compressing data (e.g. zip)

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Setting up the database.
- Create a database 'PhenotypingSchemeComposer'.
- Open dump file PhenotypingSchemeComposer.sql with a text editor, search the line "/*!50013 DEFINER=`user`@`localhost` SQL SECURITY DEFINER */" and replace 'user' in `user`@`localhost` with valid database user.
- Load the dump file PhenotypingSchemeComposer.sql to the MySQL instance. IMPORTANT: The current version is designed to link to the user table of the managing and result database 'phenotyper' which should be available on the same MySQL instance.

Installing the web application

- Deploying the WAR file:
	+ open a web browser and go to http://localhost:8080 (standard address of tomcat).
	+ go to Tomcat Manager and log in as the tomcat user with manager role
	+ in the section WAR file to deploy select the WAR file and click Deploy

- Configuration steps
	+ the main configuration file is located at <tomcat directory>/webapps/TestProgramComposer/WEB-INF/classes/TPCProperties.xml
	+ open the file with a text editor and customize the settings as described in the comments:
	
	#############################################################################################################
	<properties>
		//the path to the webapps directory of your tomcat installation
		<entry key="webApplicationParentPath">C:\\Program Files\\Apache Software Foundation\\tomcat\\webapps\\</entry>
		
		//name of the directory where files are stored temporarily for download within the web application parent path
		<entry key="downloadTempDirName">downloads</entry>
		
		//command line expression for starting the zip application (has to be installed on your computer). The first %s stands for the archive name the second %s for the list of the files to be compressed
		<entry key="zipProgramPath">zip -j %s %s</entry>
		
		<entry key="xmlExtension">.xml</entry>
		<entry key="zipExtension">.zip</entry>
		
		//key string for hashing the password - IMPORTANT: has to be equal to that used within the result web application
		<entry key="secureSalt">sdfghljljkljdf</entry>
		
		//a directory for storing images - has to be writable for the user running tomcat
		<entry key="imageDirectoryPath">C:\\phenotyperImages</entry>
		
		//a directory for storing images temporarily while being displayed on the web page - has to be writable for the user running tomcat 
		<entry key="imageDisplayDirectory">imagesForDisplay</entry>
		
		//limit for image files - may be customized
		<entry key="maxImageSizeInKb">500</entry>
		
		//link to the webpage of the ontology lookup service
		<entry key="linkToOntologyLookupService">http://www.ebi.ac.uk/ontology-lookup/</entry>
		
		//name and password of the database user created during the set up of MySQL - may be encrypted or in clear text - see below
		<entry key="hibernateConnectionUsername">OKNEJNDOjfsasfjasdjf</entry>
		<entry key="hibernateConnectionPassword">JKLJLKJDFSDFJASDKFJASd</entry>
		
		//name of the database server - usually localhost when the database is running on the same machine as the web application
		<entry key="databaseServerName">localhost</entry>
		
		//name of the database instance
		<entry key="databaseName">PhenotypingSchemeComposer</entry>
		
		//some database connection settings - need not to be changed
		<entry key="hibernateDialect">org.hibernate.dialect.MySQLInnoDBDialect</entry>
		<entry key="hibernateConnectionProfile">MySQL</entry>
		<entry key="hibernateConnectionDriverClass">com.mysql.jdbc.Driver</entry>
		<entry key="hibernateC3POMaxSize">20</entry>
		<entry key="hibernateC3POMinSize">5</entry>
		<entry key="hibernateC3POTimeout">1800</entry>
		<entry key="hibernateC3POMaxStatements">50</entry>
		<entry key="hibernateCurrentSessionContextClass">thread</entry>
		<entry key="hibernateShowSQL">true</entry>
		
		//if encrypted database credentials are used you have to indicate name and directory path of the key file here
		<entry key="keyFileName">keyfile</entry>
		<entry key="keyFilePath">keyfile</entry>
		
		//here you may specify if the database credentials should be encrypted or used as clear text - see above
		<entry key="useEncryptedDatabaseLoginData">true</entry>
	</properties>
	##############################################################################################################
	
	+ for using encrypted database credentials:
		- create a keyfile: java -jar Encrypter.jar <path to the keyfile>
		- encrypt username: java -jar Encrypter.jar <clear text username> <path to the keyfile> encrypt
		- encrypt password: java -jar Encrypter.jar <clear text password> <path to the keyfile> encrypt
		- customize encrypted username and password along with name and path of the keyfile in TPCProperties.xml