/ 
GBrowse-2.56
River stage zero No dependents
/ pod::INSTALL.MacOSX

Installing the Generic Genome Browser on Mac OS X

This document will guide you through the steps necessary to install the Generic Genome Browser (GBrowse) on a stock Mac OS X system.

1. Hardware requirements

The minimum suggested hardware is:

Mac OS X.2 (Jaguar or above)
500 Mhz G4 or higher
512 MB RAM
1 gigabyte free disk space (more depending on database size)

2. Installation options

You have three (3!) options for installing GBrowse on OS X.

1. As a downloadable package
2. Using the build scripts located in the contrib directory
3. Manually, by following the steps in this document

Installing GBrowse using the package installer

GBrowse is a large and complicated set of software components. Have a look at the software requirements listed below. There are many dependencies which require custom configurations of the install process. It is strongly recommended that you use the package installer which has already resolved many of these difficulties, ensuring that all components work together appropriately.

To install the Package, simply double click on it and follow the included documentation. The package also includes an installer for the MySQL database.

The package installer will:

1. Install all required libraries
2. (Optionally) install the MySQL database
3. Install GBrowse
4. Configure your system for GBrowse, including building a
   sample database

Once installed, you may wish to read the sections on "Populating the database" below.

Installing GBrowse using the build scripts

GBrowse is distributed with scripts that automate the fetching and building of GBrowse and all of its software dependencies. These scripts are locate in contrib/install_macosx.

For example, to build GBrowse on Mac OS X,

% cd contrib/install_macosx
% make libraries  (wait and wait and wait)
% make gbrowse

See the README in contrib/macosx_install for additional details.

4. Installing GBrowse manually

Fundamental installation obstacles

Many of the differences in the installation process are due to slight differences in paths in MacOS X. If you run into installation difficulties, first check the paths for installations and dependencies!

Note: Throughout this document, commands to be typed at the command line by the root user begin with a "$". Those requiring a non-privileged user begin with a "%". When lines to be typed at the command line are too long, they are broken by a backslash (\).

This document primarily deals with a Genome Browser installation that does not rely on Fink. I think that it introduces to much of a "black-box" element. In the end, I think it is far easier to build and configure everything yourself in standard unix paths. When something breaks, it's far easier to trouble shoot things that you yourself have built.

--- Software requirements

You will need the following software packages (the specific versions refered to have been tested for this installation document):

1. Apple's Developer Tools, December 2002 release

The Developer Tools include compilers and unix utilities required for installing packages.

http://www.apple.com/developer
2. Apple's X11 Package and X11 SDK, Public Beta 3 or higher

X11 is a windowing system developed for unix platforms. Apple provides a convenient mechanism for installing X11 in a single precompiled package. You will also need the X11 SDK which provides additional libraries.

http://www.apple.com/macosx/x11/
3. The MySQL database, version 3.23.39 or higher

The MySQL database is a fast open source relational database that is widely used for web applications.

http://www.mysql.com
4. Perl, version 5.005 or higher

Preinstalled on MacOS X.

http://www.perl.org
5. Perl modules
1. Digest::MD5 2.16 or higher
2. GD 2.06 or higher
3. Storable 1.013 or higher
4. DBI 1.19 or higher
5. DBD::mysql 2.0416 or higher
6. Text::Shellwords
7. IO::String

The following are optional

1. XML::Twig 3.04 or higher
2. XML::Dom 1.34 or higher
3. XML::Writer 0.4 or higher
4. XML::Parser 2.30 or higher
5. LWP 5.53 or higher

If these modules are present, the "Sequence Dumper" plugin will be able to produce GAME and BSML output. They can be downloaded from CPAN. The LWP module enables loading of remote 3rd party annotations.

6. Libraries
1. zlib 1.14 or higher
2. libjpeg 6b or higher
3. libpng 1.25 or higher
4. libgd 2.0.15 or higher
5. expat 1.95.6 or higher
6. BioPerl package, vers 1.2.3 or higher
http://www.bioperl.org/
7. Apache 1.3.26 or higher (http://www.apache.org)

The Apache web server is the industry standard open source web server for Unix and Windows systems. Preinstalled on Mac OS X.

8. The Generic Genome Browser package, version 1.54 or higher
http://www.gmod.org/

--- Installing prerequisites

1. X11

X11 is a windowing system developed for Unix platforms. Many unix applications require X11 (that is, they do not run within the Mac environment directly).

Apple has made this incredibly easy with a downloadable package. X11 can also be installed via Fink, but this will not be discussed here. Furthermore, the Apple installation of X11 runs side-by-side with the Mac OS in windows that look and behave exactly like standard Mac OS windows, and is optimized for the graphical capabilities of Mac OS X. Thus, you can run unix applications side-by-side Mac applications!

Once installed, X11 also opens up lots of other useful options for your system. For example, you can easily install the preeminent text editor Xemacs via fink.

X11 can be installed in a variety of ways. This document only describes installations with Apple's X11 package because it is the fastest and easiest way to install X.

NOTE: X11 will come preinstalled with OS X.3 and greater.

Fetch the Apple X11 and X11 SDK installer packages.

http://www.apple.com/macosx/x11/download

The link to the SDK is a little obscure - look in the bottom right-hand corner. First intall the X11 package, followed by the X11 SDK by double clicking each package icon and following the onscreen instructions.

2. Creating users for MySQL

Since we are going to be installing MySQL, it's appropriate to create specific users and groups for the database.

User and group management under Mac OS X is handled by the NetInfo Manager. I'm going to bypass the GUI, instead adding the appropriate users and groups through the command line. The following commands should be run as root (or sudo):

Important Note: These examples assume that the specific user and group IDs are not yet assigned on your system. Change these values accordingly if they are.

	This example uses:
                 uid     gid
	mysql    2001    2001

The mysql user:

$ niutil -create / /users/mysql	
$ niutil -createprop / /users/mysql uid 2001
$ niutil -createprop / /users/mysql gid 2001
$ niutil -createprop / /users/mysql name mysql
$ niutil -createprop / /users/mysql passwd *
$ niutil -createprop / /users/mysql realname mysql
$ niutil -createprop / /users/mysql _writers_passwd root
$ niutil -createprop / /users/mysql change 0
$ niutil -createprop / /users/mysql home /usr/local/mysql
$ niutil -createprop / /users/mysql shell /dev/null

The mysql group:

$ niutil -create / /groups/mysql
$ niutil -createprop / /groups/mysql gid 2001
$ niutil -createprop / /groups/mysql passwd *

Note that the mysql user's home directory was set to /usr/local/mysql, a directory that will be created during the installation of MySQL.

3. MySQL

MySQL can be installed on Mac OS X as a precompiled package, compiled directly from source, or through the fink package manager as either source or binary. Installation from a precompiled binary is the fastest and most sure-fire way to get a working installation. However, I've found that a source install, although a little slower, more closely mirrors mysql installations on unix systems.

Installing MySQL from source
1. Download the source tarball from mysql.com
% curl -O ftp://ftp.orst.edu/pub/mysql/Downloads/MySQL-4.0/mysql-4.0.13.tar.gz
2. Unpack and install the distribution
% gnutar -zxf mysql-4.0.12.tar.gz
% cd mysql-4.0.12
% ./configure --prefix=/usr/local/mysql \
              --with-unix-socket-path=/usr/local/mysql/run/mysql_socket \
              --with-mysqld-user=mysql \
              --with-comment
% make
% sudo make install
% sudo mkdir /usr/local/mysql/run
3. Configure the installation
% sudo /usr/local/mysql/bin/mysql_install_db --force # create var/ for DBs
% sudo chown -R mysql /usr/local/mysql/var /usr/local/mysql/run
% sudo chgrp -R mysql /usr/local/mysql
Installing MySQL from a precompiled package
1. Download the package from mysql.com
http://www.mysql.com/downloads/

Find the "standard" release in pkg/dmg form and download it from a nearby mirror. Double click the .dmg file and follow the typical installer instructions. The package places everything in standard paths (ie the mysql.sock is found in /etc/).

2. Configure the installation
% sudo chown -R mysql /usr/local/mysql/data
% sudo chgrp -R mysql /usr/local/mysql
% cd /usr/local/mysql
% sudo ./configure # installs the appropriate databases
4. Starting MySQL
1. Start the mysql database daemon
% sudo /usr/local/mysql/bin/mysqld_safe --user=mysql &
     OR (for Fink installs):
% sudo /sw/bin/mysqld_safe &
2. Set a root user for the MySQL installation
% mysqladmin -u root password 'new_password'
3. Finally, be sure to add the mysql/bin directory to your path.
4. You will also probably want to create a mysql user and group.

See the MySQL documentation for more information.

5. Installing libjpeg, libpng, gd, and GD

gd is a graphics drawing library and is the most troublesome part of a GBrowse installation. Although GD and GD.pm can both be installed by fink, there are path and versioning difficulties that have yet to be worked out. In addition to <little> gd, there is <big> GD, a perl library for interacting with little gd.

Install jpegsrc and libpng

% curl -O  ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
% gnutar -xzf jpegsrc.v6b.tar.gz
% pushd jpeg-6b/
% ./configure
% make
% sudo make install mandir=/usr/local/share/man
% sudo make install-lib
% sudo ranlib /usr/local/lib/libjpeg.a
% popd

Now you need to compile the libpng code. This allows you to manipulate PNG files.

% curl -O http://www.libpng.org/pub/png/src/libpng-1.2.5.tar.gz
% gnutar -xzf libpng-1.2.5.tar.gz 
% pushd libpng-1.2.5/
% cp scripts/makefile.darwin makefile
% make ZLIBINC="/usr/lib" ZLIBLIB="/usr/lib"
% sudo make install
% sudo ranlib /usr/local/lib/libpng.a
% popd

% curl -O http://www.boutell.com/gd/http/gd-2.0.15.tar.gz
% gnutar -zxf gd-2.0.15.tar.gz
% pushd gd-2.0.15
% ./configure CPPFLAGS=-I/usr/X11R6/include/freetype2 \ 
     --prefix=/usr/local --mandir=/usr/local/man \
     --bindir=/usr/local/bin --with-freetype=/usr/X11R6/lib \
     --inludedir=/usr/local/include
% make
% sudo make install
% popd

% curl -O http://stein.cshl.org/WWW/software/GD/GD.pm.tar.gz
% gnutar xvfz GD-2.06.tar.gz
% pushd GD-2.06/
% perl Makefile.PL
% make
% make test
% sudo make install
% popd
6. Installing required Perl modules

Most of the required Perl modules for GBrowse can be installed painlessly on Mac OS X through the CPAN module, indicated by the cpan> prompt. The CPAN module simplifies the retrieval and installation of modules from the Comprehensive Perl archive Network (CPAN). The first time you run the CPAN module from the command line, it will go through some configuration steps. After this you will be presented with the "cpan>" prompt. Type "?" to get for help. To install modules, type "install <module_name>". For example, here's how to install the "Bundle::CPAN" module, which bundles together a number of modules recommended by CPAN:

eg: % sudo perl -MCPAN -e shell
    cpan> install Bundle::CPAN

Specific instructions for those that cannot be installed in this manner are provided below.

Many modules listed here are prerequisites for other components (primarily BioPerl). Only those marked with an * are required by GBrowse proper.

 Module:                                    Install By:
*1.  Bundle::LWP                            CPAN
    (installs a variety
     of required modules)
*2.  GD            	                   See above
*3.  Storable	                           CPAN
*4.  DBI			                   CPAN
*5.  DBD::mysql		                   CPAN
 6.  Text::Shellwords                       CPAN
 7.  IO::String                             CPAN
 8.  IO::Scalar                             CPAN
 9.  File::Temp                             CPAN
 10. Text::Balanced                         CPAN
 11. Parse::RecDescent                      CPAN
 12. Bundle::Bioperl                        CPAN
7. Installing DBD::mysql

If you have problems installing DBD via CPAN, read this, and check the paths to your mysql/include and mysql/lib libraries. There are some library path issues with source installs of MySQL and its library files.

DBD::mysql looks for libmysqlclient.dylib in /usr/local/mysql/lib dyld looks for it in /usr/local/mysql/lib/mysql/.

We remedy this conflict in the Makefile

# Fetch DBD-mysql-2.9002 from CPAN
% gnutar xvfz  DBD-mysql-2.9002
% cd DBD-mysql-2.9002/
% perl Makefile.PL --cflags=-I'/usr/local/mysql/include' \
                   --libs="-L/usr/local/mysql/lib -lmysqlclient -lz -lm"
% make
% make test
$ sudo make install

--- Installing optional components

The following modules are optional. If these modules are present, the "Sequence Dumper" plugin will be able to produce GAME and BSML output. The LWP module enables loading of remote 3rd party annotations.

Optional Modules:
1. XML::Parser 2.30 or higher
2. XML::Twig 3.04 or higher
3. XML::Dom 1.34 or higher
4. XML::Writer 0.4 or higher
5. XML::Parser::PerlSAX
1. Installing expat (optional)
curl -O http://umn.dl.sourceforge.net/sourceforge/expat/expat-1.95.6.tar.gz
gnutar -zxf expat-1.95.6.tar.gz
pushd expat-1.95.6/
./configure
make
make install
popd
2. Installing XML::Parser (optional)

The XML::Parser module requires that you download and install the expat XML parsing libraries of first. Download the expat library from expat.sourceforge.net. Untar the directory. The standard installation paths will work fine.

   % ./configure
   % make
   % sudo make install

After downloading and untarring XML::Parser from CPAN...
% cd XML-Parser-2.31
% perl Makefile.PL EXPATLIB=/usr/local/lib EXPATINCPATH=/usr/local/include
% make
% make test
% sudo make install

--- Installing the Generic Genome Browser

The Generic Genome Browser is a CGI script and some Perl modules that use Bio::DB::GFF and Bio::Graphics to create the navigable graphical displays of genomic data. But you know that already, or you wanted have made it this far, no? GBrowse lives at www.gmod.org. Download and unpack the latest version and run the following incantation to install it in the default locations for Apache.

% perl Makefile.PL HTDOCS=/Library/WebServer/Documents
                   CGIBIN=/Library/WebServer/CGI-Executables
                   CONF=/etc/httpd
% make
% sudo make install

Here I am using the default Sites folder to store the gbrowse-specific files.

--- Populating the database

Please see the similarly titled section in the main INSTALL document.

--- Configuring Apache

If you followed all examples in this document, you are ready to start using GBrowse. If you placed the GBrowse files in other paths, you need to let Apache know where they are. Specifically, this may required modifying the DocumentRoot, adding a ScriptAlias, or creating a VirtualHost. See the Apache documentation for more information.

You can start Apache by:

% sudo /usr/sbin/apachectl start

--- Testing the Browser

You should now be able to browse the yeast genome. Type the following URL into your favorite browser:

http://127.0.0.1/cgi-bin/gbrowse?source=yeast

This will display the genome browser instructions and a search field. Type in "III" to start searching chromosome III, or search for "glucose" to find a bunch of genes that are involved in glucose metabolism.

Authors

Todd W. Harris (harris@cshl.org). Please direct all questions, comments and bug reports relating to this documentation or the Installer package to me.

GBrowse was written largely by Lincoln Stein (lstein@cshl.org), with contributions by members of the Generic Model Organism Database (GMOD) community (http://www.gmod.org/).

You can read more about GBrowse in:

Stein LD, Mungall C, Shu S, Caudy M, Mangone M, Day A, Nickerson E, Stajich JE, Harris TW, Arva A, Lewis S.

The generic genome browser: a building block for a model organism system database. Genome Res. 2002 Oct;12(10):1599-610. http://www.genome.org/cgi/content/full/12/10/1599

Copyright information

Material in this document is copyright 2001-2003 by the Cold Spring Harbor Laboratory. This information is provided "AS-IS" without any warranty, expressed or implied.

$Id: INSTALL.MacOSX.pod,v 1.3 2003-12-01 18:15:08 scottcain Exp $