GeneX

Installation Notes for the GeneX Database and Web Interface
===========================================================
# CVS $Id: INSTALL,v 1.28 2003/04/09 20:41:29 jason_e_stewart Exp $


Overall description of the installation process.
------------------------------------------------

0 - Make sure you really do want to install GeneX - read through the 
      docs and decide if it will give you what you need.
1 - Check the hardware requirements
2 - Check the software requirements and configuration
    - install 'apt-get-able' components and install them if not 
      already installed
    - install those components that are NOT 'apt-get-able'
      (currently 2 perl modules)
            
3 - Copy the genex-server/etc/GeneX.config file to the genex-server dir
4 - edit it for your local configuraton using a text editor.
5 - 'make configure' (as yourself)
6 - su to root & then 'make install'
7 - figure out why it didn't work, mail us at:
    genex-dev@lists.sf.net
    and go to 1 and try again.  
    Seriously, it probably will require a few attempts to install GeneX,
    but we'll help you as much as we can.
        
============================================================
Hardware Requirements
============================================================
   
More is better, but for a lab setup, you'll likely need:

- 1 GHz CPU or better; a 2 way system is better if you plan on hosting
  lots of queries, but none of the code is explicitly SMP.  Several of
  us run with slower CPUs, but speed will be an issue with large
  queries or large analyses.

- at least 512MB RAM; again, more is much better.  There are 2 RAM hogs 
  associated with this system in general - the first is the process of 
  loading the data, which requires a lot of RAM to create the objects in 
  memory before storing them to the DB.  The second is the analysis.  Both R 
  (the statistical language) and other analytical tools such as GeneSpring
  require LOTS of RAM.

- as much disk space as is necessary to hold your data.  We'd suggest that 
   the partition you install GeneX on has at least 4 GB free. Altho the 
   skeleton database is only ~30MBs with the Postgresql software base, it will 
   grow fast with data.  IDE disks now are dirt cheap and reasonably fast,
   altho SCSI disks still have the edge in speed. 

============================================================
Check prerequisite sofware and configuration
============================================================

- Operating System: Unix-like, preferably Linux. We have successfully
  installed GeneX on Intel and PowerPC architectures, with RedHat 8.x
  and Debian Sid systems.  
  
  We develop on, and HIGHLY recommend Debian UNSTABLE  as a GeneX server
  platform.  You can use a commercial Debian-based system  to install the
  base system and then upgrade to unstable (aka Sid) once  it's functional. 
  I recommend the MEPIS or LibraNet Debian distros as  starting points.

  Other flavors of Unix should work, but will probably require tweaking 
  of some of the code.

- Utility software: All recent, full Linux distros include (and
  GeneX depends on): 
  * gnu tar, 
  * gnu text & file utils (version >= 2)
  * sendmail (or a sendmail replacement such as exim)

- Further almost all recent Linux distros include the following as 
  recommended options:
  
  * Perl >=5.8.0 
  * apache web server, version 1.3.x.  (NOT apache version 2)
  * PostgreSQL database server (version >= 7.4)
  
 
------------------------------------------------------------
Prerequisites And how to install them
------------------------------------------------------------
We directly support the Debian Linux Distro, which uses the apt/dpkg
package management system to install software.  If want to use a
RedHat system to install the GeneX system, you will have to use
'alien' or another cross-distro package management tool to supply the
software we refer to be willing to figure out what the RPM equivalents
are. 

Semi-Automagic install of required Software
-------------------------------------------
The following commands pasted into a root shell will install most of 
the pre-requisites you need to support GeneX :

apt-get update

apt-get install  postgresql postgresql-doc \
 unixodbc-bin libiodbc2 odbc-postgresql unixodbc \
 expat libapache-mod-perl libdevel-symdump-perl \
 perl-modules libterm-readkey-perl libapache-session-perl \
 libapache-request-perl  libdbd-pg-perl libdbi-perl \
 libhtml-mason-perl libtie-ixhash-perl libxml-xerces-perl 
     
[as of 3.31.04, the above are all currently found in Debian unstable/Sid]


Important Exceptions  
--------------------
  Tie::StrictHash.pm 
  Apache::SubProcess.pm 

  use CPAN to install these (see the file 'docs/Using.CPAN')
  cpan> install Tie::StrictHash Apache::SubProcess
    
    
Modify configuration files:
===========================
1 - Modify apache's httpd.conf file.
    Add the genex.conf file to /etc/apache/httpd.conf file.  
    Paste the following into a root shell window (this only needs to be 
    done once).

  echo "Include /usr/local/genex/etc/genex.conf" >> /etc/apache/httpd.conf

   make sure that your httpd.conf file has mod_perl support. It should
   contain a line like the following:
   
     LoadModule perl_module /usr/lib/apache/1.3/mod_perl.so
   
   Then don't forget to restart apache, usually like this:

     # /etc/init.d/apache restart   (as root, of course)
     
2 - modify the Postgresql config file for GeneX:

   For the basic postgres installation, please see:
   http://www.postgresql.org/docs/7.4/interactive/installation.html

   There are 2 additional things to be considered for GeneX:
   
 * Configuring Host Based Authentication for Postgres.
   The default Postgres installation sets up all DB users to
   authenticate themselves based on their unix login name. Most users
   of the Genex DB will not have a Unix login on the server, so this
   must be modified. To do this you must edit the Postgres
   configuration file called  (/etc/postgresql/pg_hba.conf in Debian, 
   and /var/lib/pgsql/data/pg_hba.conf under Mandrake and ??? under 
   RedHat).  You must ensure that the following stanza appears after all 
   the comments is as follows:

   # local    DATABASE    USER            METHOD  [OPTION]
   local      all         postgres        ident sameuser
   local      all         all             md5

   This will allow the unix user postgres' to login to any DB without 
   a password, but will require all other users to autheniate themselves 
   when logging in.
   
 * To enable the GeneX2 DB to be accessible remotely via TCP, install as 
   a standalone system and then configure for TCP access.  The additional
   work is trivial.  You need to change the 'pg_hba.conf' file to include a
   line like the one below (changing the network parameters for your case).

# TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD
host    all         all         127.0.0.1         255.255.255.255   password
host    genex       all         192.168.1.0       255.255.255.0     password
host    template1   all         192.168.1.0       255.255.255.0     password

   In the above example, the first line allows all users from the local
   machine to access all databases as long as they provide valid passwords. 
   The second line allows machines from a private subnet (192.168.1.0, masked
   255.255.255.0) to access only the genex DB and only if they are known
   postgres users and  supply the correct postgresql password.  There are
   more (and less) stringent  authentication schemes described in the
   comments in 'pg_hba.conf'. 
   The two net address fields specify to which client machines a host or
   hostssl record applies, based on their IP address.  The precise logic
   is that the (actual-IP-address XOR IP-address-field) AND IP-mask-field must
   be zero for the record to match.
   
   Finally, in order to open the DB to remote network connection, the
   postgres configuration file 'postgresql.conf' (usually kept in the  same
   place as the other config files) MUST INCLUDE THE LINE: 
   tcpip_socket = 1 
   (and does in the default Debian configuration).


FINALLY, after all the pre-requisites are installed and configured...

===========================================================================
              Check out the latest GeneX source via svn
                   (If you haven't already done so)
===========================================================================

% svn http://genex2.binf.gmu.edu:8080/svn/trunk/genex-server co genex-server

The above line will create a directory called genex-server.  cd into
it and follow the instructions below.

===========================================================================
               Edit the GeneX.config file for your site
===========================================================================

Copy the file "genex-server/etc/GeneX.config" up one level to
genex-server and edit it to set the parameters for your site.  Each
stanza has a paragraph decribing what the parameter means. Most of
them are already set and should only be changed if you have special
reasons for doing so.

===========================================================================
                     Run 'make configure' /as yourself/
===========================================================================

The script will do much derivation and munging of the parameters you
typed in and then apply them to a massive substitution through the
source tree.

===========================================================================
                    Finally /as root/, run 'make install'
===========================================================================

NB.  B E W A R E that Debian systems automatically clean out /tmp on reboot, so
  you may want to place the temporary files associated with the GeneX 
  installation elsewhere.


Suggestions
===========

Please keep track of things that blew up, behaved unexpectedly, you 
didn't understand or weren't explained well and email them directly 
to us at:     genex-user@lists.sourceforge.net


Thanks for reading through this to this point.


  * Jason Stewart
  * Harry Mangalam
  * Jennifer Weller
  * Durga Addepalli
  * Hrishikesh Deshmukh
  * Karen Schlauch
  
  > Michael Pear
  > William Anderson
  > Andrew Dalke
  > Carol Harger
  > Peter Hraber
  > Brandon King
  > Lonnie Montoya
  > Todd Peterson
  > Diane Trout
  > Mark Waugh
  > Kathy Waugh
  > Jiaye Zhou
  > Greg Colello
  
  * - current
  > - alumni (thanks guys!)