Section 11: Installation GERON Genotyping is a J2EE web application and requires a servlet container or application server to run the application and a relational database for storage of data. Currently the application was developed and tested using Apache Tomcat© 4.x servlet container, but should work with minor changes on most Java application servers supporting the J2EE Servlet 2.3 and JSP 1.2 specifications. The application was also developed and tested using the MySQL® 4.x relational database, effort has been made to keep the JDBC layer and SQL syntax generic and non-database specific; however some porting may be required to run against another datastore. Because GERON Genotyping runs on top of an application server and requires a database server, these servers must be in place before installation of GERON Genotyping. This installation section will focus on installing the genotyping application and will briefy cover setup of the servlet container and database server. More detail on the installation and setup of Apache Tomcat© servlet container and MySQL® database server can be found at their respective websites. GERON Genotyping also makes use of PedCheck© to check for genotyping errors within a pedigree. In order to make use of this functionality the PedCheck© application should also be installed on your server. PLEASE NOTE: This application is intended for use in an intranet environment and requires setting up and configuring servers. As such the installation is probably beyond the ability and privileges of most end users. Also the installation steps outlined below are simple and brief and not intended to be a description of a fully optimized configuration or a completely secured deployment. It is highly recommended that you consult your organizations IT staff for deployment of the application. You should also consult with your sample collection Protocol staff about the storage of pedigree and genotyping data for your samples in a web based data repository. So while the initial installation of the application on the server may be resource intensive once installed at the server the are not any additional installation steps for the end user. Since the application is web based the end user only needs a web browser, the application has been tested on Mozilla Firefox© and Microsoft® Internet Explorer. Section 11.1: Creating the database on MySQL® Database Server This application was developed and tested using the MySQL® 4.1.x Standard Database Server. This section is a brief description of installing and setting up the MySQL® database server for use with GERON Genotyping. For more detailed information on installing, setting up and managing the MySQL® Database Server please see the MySQL® documentation and resources at http://www.mysql.com . The MySQL® database is an open source, fast, common and easy to use relational database and is available for download at the MySQL® website. This database server is supported on many operating system platforms. You should download the OS appropriate MySQL® database server form the MySQL® download site and follow the installation instructions at: http://dev.mysql.com/doc/mysql/en/Installing.html ; or you can use an existing instance of a MySQL® database server if you already have one (please see the MySQL® documentation for version inconsistencies or table migration information) . The MySQL® website also offers a couple of useful GUI tools for managing and working within MySQL® databases; MySQL® Administrator and MySQL® Query Browser. There are two simple methods for creating an instance of the GERON Genotyping database and two versions of the initial genotyping database. The two versions of the initial genotyping database consist of; a version that is almost blank and contains only the schema and a few initials values such as one user, a few map types, one disease model and 66 ethnicities, the other version consists of the schema, the initial seed data mentioned above, most of the Microsatellites and map positions from NCBI's Human UniSTS FTP site ( ftp://ftp.ncbi.nih.gov/repository/UniSTS/ ), most of the CEPH family pedigrees and microsatellite genotypes, allele sizes and frequency data from the CEPH Genotype Database ( http://www.cephb.fr/cephdb/ ). The two simple methods for creating an instance of the database are to create the database using SQL scripts or to unzip a copy of the database into the MySQL® data directory. Please note, using the SQL scripts will only create the almost empty version of the genotyping database. The SQL scripts and compressed copies of the database are available at the GERON software website. Section 11.1.1: Creating the database from a compressed copy Download either the blank (geron_genotyping_blank_db.zip) or seeded (geron_genotyping_seeded_db.zip) compressed copy of the of the database from the GERON software website. Uncompress the zip file into a temporary directory on the machine your database server resides on using a tool such as gunzip on Linux, WinZip® on Microsoft® Windows, or Stuffit Expander® on Mac OS X®. Move the entire genotyping directory and contents from you temporary directory to your MySQL® data directory. (If your MySQL® server is running on a Linux or Mac OS X operating system then you will need to run the chown -R, chgrp -R and chmod commands on the genotyping directory to make sure the correct owner, group and privileges are set on the genotyping directory and it contents based on the configuration of your database server). If your database server is already running you should now be able to see the genotyping database instance, if not please start your database server and the instance should be available. Also note that the default name of the database is genotyping, if you would like to change the databases name just change the directory name from genotyping to what you would like it to be. Section 11.1.2: Creating the database from SQL scripts Download the files: create_genotyping.sql and lng_genotyping_init.sql from the GERON software site. Make sure your database server is running, using the MySQL® command line interface or a GUI based application such as MySQL® Query Browser create a database (or schema) named genotyping or a whatever you want to name the database. Now using the MySQL® command or GUI interface load and execute the create_genotyping.sql script, then load and execute the lng_genotyping_init.sql script. If you named your database something other than genotyping you will need to modify the first line in both sql scripts to 'use yourdatabasename;' instead of 'use genotyping;. You should now be able to see an instance of the genotyping database and it schema. Now that you have an instance of the genotyping database available on your database server you should create a MySQL® database server user with a password that can access the genotyping database. You can use the MySQL® command line interface or the MySQL® Administrator to do so, please see the MySQL® documentation for details. Section 11.2: Installing Apache Tomcat© 4.x servlet Container Please visit http://jakarta.apache.org/tomcat/index.html for instructions on downloading and installing Apache Tomcat© 4.x. Section 11.3: (Optional but recommended) Installing PedCheck© Obtain a licensed copy of PedCheck© from: http://watson.hgen.pitt.edu/register/docs/pedcheck.html Once you have the binary (executable) for your operating system, put it somewhere that GERON Genotyping can execute it and you know the path to it. Section 11.4: Deploying GERON Genotyping on Apache Tomcat© Download the file genotyping.zip from the GERON software website. Unzip the contents of genotyping.zip into the 'webapps' directory of your Apache Tomcat© server. Open the file /webapps/genotyping/WEB_INF/web.xml in a text or xml editor. Change the log file path as necessary (approx line number 19): Log_File 'your_path'/genotyping.log.xml you may need to change privileges to this file based on your operating system and privileges of you Apache Tomcat©. Change the database URL as necessary (approx. line number 59): org/lng/genotyping/DataSource/Name jdbc:mysql://'your db server ip or hostname':3306/'genotyping or name you choose for database' java.lang.String Change the database server user name (approx. line number 69): org/lng/genotyping/DataSource/User 'database server username' java.lang.String Change the database server user password (approx. line number 74): org/lng/genotyping/DataSource/Password 'database server user password' java.lang.String Change PedCheck© executable path (approx. line number 80): org/lng/genotyping/pedcheck/executablepath 'pedcheck_path'/' os specific pedcheck executable' java.lang.String you may need to change privileges to this file based on your operating system and privileges of you Apache Tomcat©. Save your new web.xml file. Download the JDBC MySQL® driver, MySQL® Connector/J, from the MySQL® website, http://www.mysql.com/products/connector/j/ . Chooose the most recent production stable version for download. Extract the file mysql-connector-java-X.X.X-bin.jar (where X.X.X is the version number). Place this file in the /webapps/genotyping/WEB_INF/lib/ directory. If you have other Tomcat© web applications that use MySQL® you can place this file in the /common/lib/ directory or somewhere on the Java classpath (you should check that this will not introduce version conflicts with other applications though. Now start or restart your Apache Tomcat© server, you should now be able to access GERON Genotyping with the following URL in your browser: http://hostname:8080/genotyping/login.html Please note that the GERON Genotyping application does not include an authentication component, but does have authorized users with privileges. The login page is only a place to pass in the username to the index or main page. To include authentication for your authorized users please consult your organizations IT staff, Realms in Apache Tomcat© documentation, Single Sign On libraries for websites and portals, or roll your own code. If you use a separate authentication component the login page may be skipped an the user can be forwarded directly to http://hostname:port/genotyping/index.jsp?username=username provided that the users credentials pass authentication. Section 11.5: System Requirements While the web server and database server may be installed on the same host server it is highly recommended the the web and database servers be installed on separate dedicated host servers and that each host server have at least 1 GB of memory. For the MySQL® database server this will allow you to use the configuration settings in the my-huge.cnf, see MySQL® documentation for more information. This will also allow you to increase the Java heap size available to Apache Tomcat©, which can be done by inserting or modifying the CATALINA_OPTS line in the catalina script, such as CATALINA_OPTS="-server -Xmx768m -Xms256m -XX:MaxPermSize=256m", please see the Apache Tomcat© documentation for more information or alternatives.