                         GRAMENE CORE INSTALLATION

$Id: INSTALL,v 1.12 2007/03/22 14:05:54 kclark Exp $

General Software Requirements
-----------------------------
*   A Unix system (any flavor)

*   Perl:  Perl 5.6.1 is recommended (5.6.0's Socket module has a bug
    that may affect Boulder module below), but newer versions of Perl
    should also work.

*   Apache/mod_perl:  Gramene makes use of Apache's embedded Perl
    module, "mod_perl."  You will need to install the lastest version
    of the 1.x Apache server and the lastest 1.x version of mod_perl
    (but a version <1.99, which is the development tree for
    mod_perl2).  You need the root privilege to run the web server on
    port 80, otherwise you will have to run it on a port number
    greater than 1024 (eg: 8080).

*   A database, such as MySQL (4.1) or Oracle (9i).

*   Various CPAN modules as required by the Build.PL script

Gramene Core
------------
To install the "core" Gramene (this distribution), execute the following
commands in this directory:

  $ perl Build.PL [destdir=/my/custom/path]
  $ su
  # ./Build install 

This will copy Gramene's code libraries, scripts, templates, HTML,
configuration files, and SQL schemas into "/usr/local/gramene" (or a
path determined by "destdir" above).

The first step ("perl Build.PL") will report any missing module
dependencies.  For example, you may be told that the "Template" module
is missing.  To install any missing modules and their dependencies,
use the CPAN Perl module like so (as root):

  # cpan Template

Or, if the "cpan" script can't be found:

  # perl -MCPAN -e 'install Template'

For more information, read the documentation for the CPAN module:

  $ perldoc CPAN

Some of the module names are confusing, however:

*   Date::Format is part of the "TimeDate" module
*   Time::ParseDate is part of the "Time-modules" module
*   Apache::Request is also called "libapreq"

Generally the CPAN module can figure out the correct module to
install, but, if you are required to install modules by hand (i.e.,
downloading the tarballs from CPAN, unpacking, building, etc.), you
will need to know the correct files to get.  Definitely you should try
using the CPAN shell as it can automatically satisfy dependencies for
you and generally does a good job hiding some of the complexities of
installing Perl modules.

A note about the "Bio" namespace included with Gramene:  These modules
are under the Bio namespace because they _need_ to conflict with the
BioPerl modules (i.e. bugfixes to BioPerl modules where the a
submitted patch is not yet released), or for modules that we would like
to contribute to BioPerl in future.

Databases
---------
Gramene is divided into modules that deal with specific aspects of the
site, such as "proteins," "qtl," "markers," "sequence," "ontology,"
etc.  Each module has its own schema which reside in the "schemas"
directory, but it's probably easiest to grab the MySQL dumps from our
FTP site (ftp.gramene.org).  It is probably easiest if you use the
Gramene naming convention of adding the build number to the module
name, e.g., "markers24" for Gramene's "markers" database for build
#24.

Don't forget to grant appropriate privileges for connecting,
selecting, deleting, etc.  For instance, with MySQL, you might do the
following for the "markers" module:

    $ mysqladmin -uroot -p create markers24
    $ mysql -uroot -p markers -e "grant select on markers24.* to \
        'gramene_web'@`%` identified by 'password'"

Repeat for each module defined in the "schemas" directory.  You will also
need to create a database for CMap and EnsEMBL;  see the docs in those
applications for more information.

Apache Configuration
--------------------
Gramene use mod_perl, an embedded Perl interpreter in the Apache
binary.  It will only work with the 1.x version of Apache.  If you
choose to build Apache/mod_perl, download the latest versions of
Apache and mod_perl in the version 1 tree (less than mod_perl 1.99)
and follow the "INSTALL.apaci" instructions included in the mod_perl
tarball with the following arguments:

  $ perl Makefile.PL \
      APACHE_PREFIX=/usr/local/apache \
      APACHE_SRC=../apache-1.3.X/src \
      DO_HTTPD=1 \
      USE_APACI=1 \
      EVERYTHING=1 \ 
      APACI_ARGS='--enable-module=rewrite, --enable-module=proxy, --enable-module=expires'
  $ make
  $ make test
  $ su 
  # make install

This method builds only mod_perl with Apache and some non-standard
modules (mod_rewrite, mod_proxy, mod_expires).  If you also wish to
compile other modules such as PHP or Tomcat, you will need to build
each pieces separately into the Apache source tree and then build
Apache.  Please read the appropriate docs to learn more.

You can configure Apache to serve Gramene by using the
"httpd.conf" file in the "conf" directory.  It may be easiest
to configure Gramene as a virtual server, running it on a non-standard
port such as "8080."  To do so, tell Apache to listen on the port,
enable virtual hosting, and define the virtual host, like so:

    Listen 8080
    NameVirtualHost 143.48.220.116:8080
    <VirtualHost 143.48.220.116:8080>
        ServerAdmin me@place.org
        Include /usr/local/gramene/conf/httpd.conf
    </VirtualHost>

However, you may wish to run only Gramene on your server, in which
case you can copy the "httpd.conf" file to Apache's
"httpd.conf" (be sure to back up the original), and then uncomment the
"Standalone" section therein.

Looking in the "httpd.conf" file, you'll notice that several
"<Location>" tags include password protection.  To make these work,
you will need to create the password files with the Apache program
"htpasswd" (which is included in Apache's "bin" directory).  You
should point the "AuthUserFile" entries to the correct files you
decide to protect these access points.

After making changes to Apache's configuration, restart the server
with "apachectl stop && apachectl start," correcting any errors that
are reported.

Database, Other Configuration
-----------------------------
You will to edit "gramene.conf" to match the correct values for your
installation (e.g., database names, user names, passwords, etc.).  In
addition, CMap installs it's own "cmap.conf" that will need to be
edited to indicate the CMap database (and you can instruct it to be
placed where you like, see below).

CMap
----
CMap is a generic web-based comparative mapping application.  Although
originally developed for the Gramene project, it is now distributed
separately as part of the GMOD project (http://www.gmod.org/).  You
will need to install the version of CMap that corresponds to the
release of Gramene:

  Build 24 -> CMap 0.16

CMap can be downloaded from Sourceforge.net:

  https://sourceforge.net/project/showfiles.php?group_id=27707&package_id=55129

To install CMap into the Gramene directory, use the following
configuration options to the CMap Build.PL:

  CONF=/usr/local/gramene/conf
  CGIBIN=/usr/local/gramene/cgi-perl
  TEMPLATES=/usr/local/gramene/templates/cmap
  HTDOCS=/usr/local/gramene/html/cmap
  CACHE=/usr/local/gramene/html/cmap/tmp

If you place the above into a file called "cmap_install.conf" in the
unpacked "cmap-0.x" directory,  these settings will be detected and
used automatically.

CMap needs to be able to write its images to a temporary directory
(the "CACHE" argument above).  Make sure that whatever you indicate
for this directory is writable by the Apache user (usually "nobody"),
e.g.:

  # chown nobody:nobody /usr/local/gramene/html/cmap/
  # chmod g+rwx /usr/local/gramene/html/cmap/

In order to get CMap to display with the Gramene navigation bar, you
will need to add the following line to the installed "cmap.conf":

  page_object Gramene::Page

For security reasons, you may wish to grant only SELECT privileges to
the database user on all tables.  If you do this, however, be sure to
grant INSERT and DELETE privileges on "cmap_map_cache" as well.

Gramene includes it's own "cmap.conf" directory in "conf" with the
config files for the build.

GDPDM
-----
The diversity module of Gramene is actually a separate package
available as "GDPDM-Tools" on our FTP site.  It was developed
separately as it works with a separately developed schema, GDPDM, from
a maize genetics group:

    http://www.maizegenetics.net/gdpdm/

Install that code into "/opt/GDPDM".

Ensembl
-------
See the README.ensembl file for instructions on installing the genome
browser.

Comments
--------
If you have any questions or comments, please write the Gramene
mailing list:

  gramene@gramene.org

  --The Gramene Team
