$CATALINA_HOME is the path to the Apache Tomcat root directory. $GNOMEX is the unzipped gnomex distribution downloaded from GitHub.

System Requirements

— Java 6 (http://java.sun.com/) — Apache Tomcat 7.0.41+ (see install instructions below)

— MySQL database server (http://mysql.com)

— MySQL JDBC driver (http://mysql.com, download mysql-connector-java-5.1.7.zip)

— Adobe Flash Player 11+ (http://get.adobe.com/flashplayer/)

Install Instructions

\\ NOTE: These install instructions are written for Linux/Unix based systems. Our development team also runs GNomEx on Windows 7 and Windows 8 workstations as well as Mac OS. The only part of the install notes that should vary are the instructions on installing Tomcat. Windows provides an installer and a run manager, so run time parameters can be set through that interface instead of through the shell scripts.

1. Download and uncompress the the GNomEx open source distribution (gnomex_x.xx.zip) from GitHub ( https://github.com/hci-gnomex/gnomex/releases).

2. Install Java, 1.6+. Make sure to set the JAVA_HOME environment variable.

3. Install Apache Tomcat 7

— Download Apache Tomcat 7 and install it (GNomEx has been validated using 7.0.41. Pick the stable release for Tomcat 7.)

— Login as root

— Start the Apache Tomcat Server

<pre>>cd $CATALINA_HOME/bin >sh startup.sh</pre>

Try to access Apache Tomcat from browser (http://myserver:8080) to make sure the Apache Tomcat page appears. You may need to open up port 8080 to gain access and punch holes through your firewalls.

— Shut down the server

>cd $CATALINE_HOME/bin  >sh shutdown.sh

4. Modify the Apache Tomcat 7 Configuration.

— Decide if you want to use port 80 for http or port 8080. In many cases, you may want to reserve port 80 for Apache for your website. In that case, use port 8080 for http. Port 443 will be used for https. These instructions assume that you will use port 80 for http. If you are going to use port 8080 instead, please substitute 80 for 8080 in the instructions below. All references to port 80 will be marked in red.

— Edit catalina.sh to bump up the heap space and allow Eclipse remote debugging. Insert this line as the first line after the block of comments:

export CATALINA_OPTS="-Xms512M -Xmx2048M -XX:MaxPermSize=256m"

- Change the port from 8080 to 80 in $CATALINA_HOME/conf/server.xml.  Also, bump up the header and post size.

<Connector port="<strong>80</strong>" protocol="HTTP/1.1"                 connectionTimeout="20000"  <strong>               maxHttpHeaderSize="1048576"</strong>  <strong>               maxPostSize="67589953"</strong>                 redirectPort="8443" />

— Restart Tomcat and try to access port 80 (http://myserver) to make sure the Apache Tomcat page appears.

— Copy all jar files in $GNOMEX/tomcat/lib to $CATALINA_HOME/lib

— Copy $GNOMEX/gnomex/dist/gnomex_realm.jar to $CATALINA_HOME/lib

— Copy the $GNOMEX/gnomex/dist/gnomex.war to $CATALINA_HOME/webapps

5. Install the MySQL database server 5.XX (http://mysql.com)

a. Make sure that you secure the initial MySQL accounts and remove anonymous access. See http://dev.mysql.com/doc/refman/5.1/en/default-privileges.html

b. Login to mysql.

>mysql -u root -p  [enter root password]

c. Choose two database passwords which will be indicated in further steps by: <password_for_gnomex> and <password_for_gnomexGuest>

d. Create a database user called gnomex and gnomexGuest. Grant all privileges on gnomex database to gnomex, but only read access on gnomex database to gnomexGuest.

CREATE DATABASE gnomex;  CREATE USER 'gnomex'@'localhost' IDENTIFIED BY '<password_for_gnomex>';  CREATE USER 'gnomex'@'%' IDENTIFIED BY '<password_for_gnomex>';  GRANT ALL PRIVILEGES ON gnomex.* TO 'gnomex'@'localhost' WITH GRANT OPTION;  GRANT ALL PRIVILEGES ON gnomex.* TO 'gnomex'@'%' WITH GRANT OPTION;  CREATE USER 'gnomexGuest'@'localhost' IDENTIFIED BY '<password_for_gnomexGuest>';  CREATE USER 'gnomexGuest'@'%' IDENTIFIED BY '<password_for_gnomexGuest>';  GRANT SELECT, EXECUTE ON gnomex.* TO 'gnomexGuest'@'localhost' IDENTIFIED BY '<password_for_gnomexGuest>';  GRANT SELECT, EXECUTE ON gnomex.* TO 'gnomexGuest'@'%' IDENTIFIED BY '<password_for_gnomexGuest>';  FLUSH PRIVILEGES;

e. Login into MySQL as gnomex user and run the SQL scripts

>mysql -u gnomex -p  [enter <password_for_gnomex>]  SOURCE $GNOMEX/gnomex/sql/gnomex_db_ddl.sql  SOURCE $GNOMEX/gnomex/sql/gnomex_db_populate.sql

6. Encrypt the passwords for gnomex and gnomexGuest.

a. Create a file to hold the <encryption_key>. The file must be named /properties/gnomex_tomcat.properties (/ is the system’s root directory). Edit the document to contain a single line. Choose the password, making it rather long. Random is always better.

key=<encryption_key>

b. Clamp down the permissions on this file.

     >chmod 700 /properties/gnomex_tomcat.properties

c. From the command line, run the AESEncryption program to obtain the encrypted password. Keep these handy for the next step.

>cd $CATALINA_HOME/lib  >java -classpath ./gnomex_realm.jar hci.gnomex.security.tomcat.AESEncryption <password_for_gnomex> <encryption_key>  > ... do the same command as above, but enter the gnomexGuest password

7. Add GNomEx properties to $CATALINA_HOME/conf/catalina.properties. Copy/paste the encrypted passwords from step #6 to the hci.gnomex.password and hci.gnomexguest.password.

# Mail server  hci.mailserver=hci-mail.hci.utah.edu

# Database connection properties  hci.gnomex.driverClassName=com.mysql.jdbc.Driver  hci.gnomex.username=gnomex  hci.gnomex.url=jdbc:mysql://localhost:3306/gnomex?noAccessToProcedureBodies=true  hci.gnomex.password=<encrypted_password_for_gnomex>  hci.gnomexguest.driverClassName=com.mysql.jdbc.Driver  hci.gnomexguest.username=gnomexGuest  hci.gnomexguest.url=jdbc:mysql://localhost:3306/gnomex?noAccessToProcedureBodies=true  hci.gnomexguest.password=<encrypted_password_for_gnomexGuest>

8. Start the Apache Tomcat Server

>cd $CATALINA_HOME/bin   >sh startup.sh

9. Run GNomEx Flex application from browser window.

a. From browser window, type in URL: http://myserver/gnomex/gnomexFlex.jsp

b. The flex application should load and then a login popup window should appear.

c. Enter the user name ‘admin’ and the password ‘admin’.

d. The first thing to do is get rid the the ‘admin’ user account and add yourself as an admin. Click and the ‘Users and Groups’ link. Click ‘New user’ link on bottom left. Enter your user information, including a login and password. Set the Permission level to Admin. Save the entry.

e. Try logging in again, using your new login and password. Then go back to the Users And Groups and remove the user named ‘admin’.

f. There are a number of configurable properties that you need to set for your installation. Click on the ‘Manage Dictionaries’ under the ‘Administration’ heading of the Welcome pane. Scroll in the left-hand tree to find the node called ‘Admin — Property’. Review the entries and make sure you modify the following properties to match your environment:

Required properties — Make sure all of these directories exist.

- experiment_directory     - analysis_directory  - flowcell_directory  - lucene_index_directory  - lucene_experiment_index_directory  - lucene_analysis_index_directory  - lucene_protocol_index_directory  - temp_directory

GNomEx Batch Jobs

GNomEx builds a searchable text index using Apache’s Lucene (http://lucene.apache.org/java/docs/). In order to refresh this index with the latest data, a batch chron job (nightly) must be scheduled.

The command to build the index is in the GNomEx ear. To run the command manually do the following

>cd $CATALINA_HOME/webapps/gnomex/scripts

For Windows environments:  >index_gnomex.cmd

For Unix environments:  >sh index_gnomex.sh

Configuring Tomcat for SSL (https)

By default, GNomEx is configured to run from a non-secure (http:) web-site. To run GNomEx from a secure web-site (https:), deploy the secure gnomex.ear, modify the tomcat configuration, and set up a server certificate.

1. Copy the $GNOMEX/gnomex/dist/secure/gnomex..war $CATALINA_HOME/webapps

2. Modify the Tomcat configuration. Uncomment the Connector and change the port to 443.

<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->   <Connector protocol="HTTP/1.1" port="443" maxThreads="200"   scheme="https" secure="true" SSLEnabled="true"   keystoreFile="/path/to/tomcat/keystore"   keystorePass="123456"   clientAuth="false" sslProtocol="TLS"/>

3. Create a keystore and reference it in above Connector

a. Create a keystore. Use the JDK or JRE installed on your server.

>keytool -genkey -keyalg "RSA" -keystore $CATALINA_HOME/keystore    -storepass 123456 -validity 5060

b. Modify the Connector entry about, setting the storepass to your keystore’s password and the keyStoreFile to your keystore file.

4. Obtain a Certificate

a. Generate a certificate request, specifying your password (-storepass), the file and to store the certificate request (-file) specifying your full web-server domain name (-alias).

>keytool -certreq -keyalg "RSA"  -file myserver.csr -keystore keystore   -storepass 123456 -alias myserver.someplace.somewhere.edu

b. Purchase a certificate (VeriSign, Thawte, etc) or obtain one from your institution. (Use the certificate request (.csr file) file generated in step c.)

c. Put the certificate returned (.cer file) into the keystore, specifying your certificate file (-file) and your full web-server domain name (-alias).

>keytool -keystore keystore -keyalg "RSA" -import -trustcacerts   -file myserver.cer -alias myserver.someplace.somewhere.edu

d. Make sure the signing authority (example: VeriSign) that you obtained the certificate from has it’s root certificate installed in the cacerts keystore. To list the root certificates:

>keytool -list -keystore $JAVA_HOME/jre/lib/security/cacerts

e. If the root certificate for the signing authority is not here, add it. When you obtained the certificate, there should have been a way to download the institutions’s root certificate (.cer) file. To allow the system to “trust” this signing authority, add the root certificate into cacerts for the jdk you are using. Default cacerts password is ‘changeit’, but recommend change to something else.

>keytool -keystore $JAVA_HOME/jre/lib/security/cacerts   -keyalg "RSA" -import -file myserver.cer -alias myserver.someplace.somewhere.edu

f. Making root certificate available for download from website.