Difference between revisions of "GBrowse Install HOWTO"

From GMOD
Jump to: navigation, search
(Try the Browser Out)
(Details)
Line 286: Line 286:
  
 
;bp_load_gff.pl
 
;bp_load_gff.pl
:This will incrementally load a database, optionally initializing it
+
:This will incrementally load a database, optionally initializing it if it does not already exist. This script will work correctly even if the MySQL server is located on another host.
if it does not already exist. This script will work correctly even
+
if the MySQL server is located on another host.
+
  
 
;bp_bulk_load_gff.pl
 
;bp_bulk_load_gff.pl
:This Perl script will initialize a new Bio::DB::GFF database with a
+
:This Perl script will initialize a new Bio::DB::GFF database with a fresh schema, deleting anything that was there before. It will then load the file. Only suitable for use the very first time you create a database, or when you want to start from scratch! The bulk loader
fresh schema, deleting anything that was there before. It will then
+
is as much as 10x faster than bp_load_gff.pl, but does not work in the situation in which the MySQL database is running on a remote host.
load the file. Only suitable for use the very first time you create
+
a database, or when you want to start from scratch! The bulk loader
+
is as much as 10x faster than bp_load_gff.pl, but does not work in
+
the situation in which the MySQL database is running on a remote
+
host.
+
  
 
;bp_fast_load_gff.pl
 
;bp_fast_load_gff.pl
:This will incrementally load a database. On UNIX systems, it will
+
:This will incrementally load a database. On UNIX systems, it will activate a fast loader that makes the speed almost the same as the bulk loader. Be careful, though, because this software relies on features that are unevenly implemented across platforms. For example, it does not work correctly on Mac OSX.
activate a fast loader that makes the speed almost the same as the
+
bulk loader. Be careful, though, because this software relies on features that are unevenly implemented across platforms. For example, it does not work correctly on Mac OSX.
+
  
You will find these scripts in the Bioperl distribution, in the
+
You will find these scripts in the Bioperl distribution, in the subdirectory scripts/Bio-DB-GFF. If you requested that Bioperl scripts be installed during installation, they will also be found in your command path.
subdirectory scripts/Bio-DB-GFF. If you requested that Bioperl scripts be installed during isntallation, they will also be found in your command path.
+
  
For testing purposes, this distribution includes a GFF file with yeast
+
For testing purposes, this distribution includes a GFF file with yeast genome annotations. The file can be found in the test_data subdirectory. If the load is successful, you should see a message indicating that 13298 features were successfully loaded.
genome annotations. The file can be found in the test_data subdirectory.
+
If the load is successful, you should see a message indicating that
+
13298 features were successfully loaded.
+
  
Provided that the yeast load was successful, you may now run "make
+
Provided that the yeast load was successful, you may now run "make test". This invokes a small test script that tests that the database is accessible by the "nobody" user and that the basic feature retrieval functions are working.
test". This invokes a small test script that tests that the database is
+
accessible by the "nobody" user and that the basic feature retrieval
+
functions are working.
+
  
You may also wish to load the yeast DNA, so that you can test the
+
You may also wish to load the yeast DNA, so that you can test the three-frame translation and GC content features of the browser. Because of its size, the file containing the complete yeast genome is distributed separately and can be downloaded from:
three-frame translation and GC content features of the browser. Because
+
of its size, the file containing the complete yeast genome is
+
distributed separately and can be downloaded from:
+
  
 
   http://prdownloads.sourceforge.net/gmod/yeast.fasta.gz?download
 
   http://prdownloads.sourceforge.net/gmod/yeast.fasta.gz?download

Revision as of 14:42, 17 April 2007

This page contains detailed installation instructions for GBrowse, suitable for use on Linux and other Unix-like platforms. It also contains performance and maintenance hints useful for all systems.

Prerequisites

GBrowse runs on top of several software packages. These must be installed and configured before you can run GBrowse. Most preconfigured Linux systems will have some of these packages installed already.

Apache Web Server http://www.apache.org
The Apache web server is the industry standard open source web server for Unix and Windows systems.
Perl http://www.cpan.org
The Perl language is widely used for web applications. You will need version 5.8.6 or higher.
Standard Perl modules http://www.cpan.org
The following Perl modules must be installed for GBrowse to work. They can be found on the Comprehensive Perl Archive Network (CPAN):
  • CGI (2.56 or higher)
  • GD (2.07 or higher)
  • CGI::Session (4.03 or higher)
  • DBI (any version)
  • DBD::mysql (any version)
  • Digest::MD5 (any version)
  • Text::Shellwords (any version)
  • Class::Base (any version)
BioPerl version 1.5.2 or higher http://www.bioperl.org
Get the "developer release", which despite its name, is quite stable.
MySQL http://www.mysql.com (not required, but recommended)
The MySQL database is a fast open source relational database that is widely used for web applications. It is required for most real-live genome annotation projects. For small projects (a few thousands of annotated features), you can skip installing MySQL and use an in-memory database instead.

Optional modules:

These Perl modules are not needed for a functional GBrowse install. We recommend that you install them as needed to obtain additional features.

XML::Parser, XML::Writer, XML::Twig, XML::DOM
If these modules are present, the "Sequence Dumper" plugin will be able to produce GAME and BSML output. They can be downloaded from CPAN.
LWP
To load remote 3d party annotations. Available from CPAN.
Bio::Das
To display remote annotations using the Distributed Annotation System. The current version is available at http://www.biodas.org/download/Bio::Das/Bio-Das-0.92.tar.gz
BioMOBY
Needed by gbrowse_moby to fetch and display data from BioMOBY providers. Available from biomoby.org; obtain via anonymous cvs until it is released. Directions are at http://www.biomoby.org/GettingTheCode.html.
GD::SVG
To save images as publication-quality editable images in Scalar Vector Graphics format. Available from CPAN.
Bio::SCF File::Temp io-lib(v1.7+)
Needed by the sequencing trace glyph to parse SCF files and display the trace graph. The io-lib library can be downlowded from https://sourceforge.net/project/showfiles.php?group_id=100316&package_id=108243 which is part of the Staden Package https://sourceforge.net/projects/staden/.
Math::FFT Statistics::Descriptive
Needed by the Spectrogram plugin to calculate Fast Fourier Transforms. This module is available from CPAN.
Bio::PrimerDesigner, Math::Round, primer3
Needed by the PrimerDesigner plugin. The perl modules are available from CPAN. The linux primer3 binary is packaged with the Bio::PrimerDesigner distribution. The binary (or source code) can also be obtained from http://frodo.wi.mit.edu/primer3/primer3_code.html. If you are using this plugin, the primer3 binary must be installed in /usr/local/bin and named 'primer3'. If it is installed in another path, edit the following section in the PrimerDesigner plugin:
         use constant BINARY            => 'primer3';
         use constant BINPATH           => '/usr/local/bin';

Basic Installation

Once the prerequisites are installed, download the most recent version of the Generic-Genome-Browser source code from:

      http://prdownloads.sourceforge.net/gmod

This will give you a .tar.gz file, which must be uncompressed and unpacked. Then run the following commands (in brief):

           perl Makefile.PL
           make
           make test (optional)
           make install UNINST=1

This will install the software in the default location for your platform. See [#Installation Details] to change this, or to install gbrowse into your home directory. The 'UNINST=1' will insure that older versions of perl modules being installed will be removed to help prevent conflicts.

To further configure GBrowse, see Generic-Genome-Browser/docs/pod/CONFIGURE_HOWTO.pod To run GBrowse on top of Oracle and PostgreSQL databases see Generic-Genome-Browser/docs/pod/ORACLE_AND_POSTGRESQL.pod To run on top of a BioSQL database, see Generic-Genome-Browser/docs/pod/BIOSQL_ADAPTER_HOWTO.pod. Note that these are in Perl "POD" format. To get rid of the formatting instructions, save to disk and run "perldoc CONFIGURE_HOWTO.pod"

Installation Details

The browser consists of a CGI script named "gbrowse", a Perl module that handles some of the gory details, a small number of static image files, and a configuration directory that contains configuration files for each data source. By default, these will be installed in the following locations:

CGI script
/usr/local/apache/cgi-bin/gbrowse
Static images
/usr/local/apache/htdocs/gbrowse
Config files
/usr/local/apache/conf/gbrowse.conf
Perl modules
the standard site-specific Perl library location

You can change change the location of the installation by passing Makefile.PL one or more NAME=VALUE pairs, like so:

     perl Makefile.PL CONF=/etc HTDOCS=/home/html

This will cause the configuration files to be installed in /etc/gbrowse.conf and the static files to be installed in /home/html/gbrowse.

The following arguments are recognized:

CONF
Configuration file directory
HTDOCS
Static files directory
CGIBIN
CGI script directory
APACHE
Base directory for Apache's conf, htdocs and cgibin directories
LIB
Perl site-specific modules directory
BIN
Perl executable scripts directory
NONROOT
If set to a non-zero value (e.g. NONROOT=1) then install gbrowse in a way that does not require root access.
DO_XS
Compile fast alignment algorithm (XS C extension)

The Makefile.PL script attempts to guess the appropriate directory locations for your system, but sometimes you will have to specify them manually. For example, if you are on a RedHat system, where the default Apache installation uses /var/www/html for HTML files, /var/www/cgi-bin for CGI scripts, and /etc/httpd/conf for the configuration files, you should specify the following configuration:

     perl Makefile.PL HTDOCS=/var/www/html \
                      CONF=/etc/httpd/conf \
                      CGIBIN=/var/www/cgi-bin

(The backslashes are there to split the command across multiple lines only). To make it easier when upgrading to new versions of the software, you can put this command into a shell script.

As a convenience, you can use the configuration option APACHE, in which case the static and CGI files will be placed into APACHE/conf, APACHE/htdocs and APACHE/cgi-bin respectively, where APACHE is the location you specified on the command line:

     perl Makefile.PL APACHE=/home/www

Note that the configuration files are always placed in a subdirectory named gbrowse.conf. You cannot change this. Similarly, the static files are placed in a directory named gbrowse. The install script will detect if there are already configuration files in the selected directory and not overwrite them if so. The same applies to the cascading stylesheet file (gbrowse.css) located in the gbrowse subdirectory. However, neither the GIF files in the "buttons" subdirectory nor the plugin modules in the gbrowse.conf/plugins directory are checked before overwriting them, so be careful to copy the new copies somewhere safe if you have modified them.

The DO_XS flag, if true (perl Makefile.PL DO_XS=1), will compile a small C subroutine for nucleotide alignments. This will vastly improve the performance of the gbrowse_details script when displaying alignments. To use this feature, you will need a C compiler.

You can always manually move the files around after install. See Generic-Genome-Browser/docs/pod/CONFIGURE_HOWTO.pod for details.

When installing the static files, the install script also creates an empty directory named "tmp". This directory is set to be world writable so that the GBrowse server can use it to manage temporary image files that it creates on the fly. If you would prefer not to have a world writable directory on your system, simply change the ownership and permissions to allow the web server account to write into it. The directory is located in HTDOCS/gbrowse/tmp by default.

The first time you run Makefile.PL, a file named GGB.def will be created your file path settings. When Makefile.PL is run again, it will ask you whether you wish to reuse the settings stored in the file.

Installing into your Home Directory

Read this section only if you are on a Unix system and do not have root privileges. You will need to configure Apache to run out of your home directory. One way to do this is to install Apache from source code and to specify your home directory when you first configure it:

      % cd apache_x.xx.xx
      % ./configure --prefix=$HOME/apache
      % make
      % make install

This will place Apache into your home directory under ~/apache. You should then edit ~/apache/conf/httpd.conf and replace the directive:

     Listen 80

with

     Listen 8000

so that Apache will listen for connections to the unprivileged port 8000 rather than the usual port 80. If you also see a "Port 80" directive, change it to read "Port 8000." You'll now be able to talk to Apache using URLs like http://your.host.edu:8000/.

You may not need to install Apache from scratch if your Unix distribution already has Apache installed. What you will do is to create an Apache directory tree in your home directory and then start Apache using command-line arguments that tell it to start up from the home directory rather than its default system-wide directory.

Create an Apache directory and its subdirectories using the following series of commands:

     % cd ~
     % mkdir apache
     % mkdir apache/conf
     % mkdir apache/logs
     % mkdir apache/htdocs
     % mkdir apache/cgi-bin

Now copy the system-wide httpd.conf into ~/apache/conf. You may need to search around a bit to find out where the system-wide httpd.conf lives (try running the command "locate httpd.conf):

     % cp /etc/httpd/conf/httpd.conf ~/apache/conf

Now open up ~/apache/conf/httpd.conf with a text editor and add the following four directives, replacing $HOME with the full path to your home directory (for example "/home/fred"):

     Listen       8000
     ServerRoot   $HOME/apache
     DocumentRoot $HOME/apache/htdocs
     SetEnv       PERL5LIB $HOME/lib  

You should search the httpd.conf file for older versions of these directives, and delete them if they're there. If you see a Port directive, change it to read "Port 8000".

Somewhere in httpd.conf there will be a ScriptAlias directives, as well as a <Directory> section that refers to "cgi-bin". Delete the ScriptAlias directive and the entire <Directory> section through to the </Directory> line. Replace both these sections with the following:

    ScriptAlias /cgi-bin/ "cgi-bin/"
    <Location "/cgi-bin">
       AllowOverride None
       Options None
       Order allow,deny
       Allow from all
    </Location>

You can now start Apache from the command line using the "apachectl" script:

    % /usr/sbin/apachectl -d ~/apache -k start

If Apache starts successfully, then this command will return silently. Otherwise, it will print an error message. More error messages may be found in ~/apache/logs/error_log. To confirm that Apache is running from your home directory, create a file named index.html and copy it into ~/apache/htdocs. You should then be able to open a browser, connect to http://localhost:8000/, and see the index.html file that you just created.

Now you can build and install gbrowse with the following incantation:

    % cd Generic-Genome-Browser-X.XX
    % perl Makefile.PL APACHE=~/apache LIB=~/lib BIN=~/bin NONROOT=1
    % make
    % make install

When you are prompted to load gbrowse using http://localhost/gbrowse, use http://localhost:8000/gbrowse instead.

Try the Browser Out

The installation procedure will create a small in-memory database of yeast chromosome 1 for you to play with. To try the browser out, use your favorite browser to open:

     http://localhost/cgi-bin/gbrowse

Try searching for "I" (the name of the first chromosome of yeast), or a gene such as NUT21 or TCF3. Then try searching for "membrane trafficking."

For your interest, the feature and DNA files for this database is located in the web server's document root at gbrowse/databases/yeast_chr1. The configuration file is in the web server's configuration directory under gbrowse.conf/yeast1.conf.

More configuration information and a short tutorial are located at:

      http://localhost/gbrowse

Populating the Database (MySQL)

This step takes you through populating the database with the full yeast genome. You can skip this step if you use the in-memory database for small projects.

Synopsis

     mysql -uroot -p password -e 'create database yeast'
     mysql -uroot -p password -e 'grant all privileges on yeast.* to me@localhost'
     mysql -uroot -p password -e 'grant file on *.* to me@localhost'
     mysql -uroot -p password -e 'grant select on yeast.* to nobody@localhost'
     bp_bulk_load_gff.pl -d yeast sample_data/yeast_data.gff

Details

Note: This section refers to the user account under which Apache runs as "nobody" because that is the most common case. However, many systems use a different user account. Mac OSX uses "www", Fedora Core uses "apache" and Ubuntu uses "www-data." In the instructions that follow, replace 'nobody' with the appropriate Apache account name.

You will need an installation of MySQL for this section. Using the mysql command line, create a database (called "yeast" in the synopsis above), and ensure that you have update and file privileges on it. The example above assumes that you have a username of "me" and that you will allow updates from the local machine only. It also gives all privileges to "me". You may be comfortable with a more restricted set of privileges, but be sure to provide at least SELECT, UPDATE and INSERT privileges. You will need to provide the administrator's name and correct password for these commands to succeed.

In addition, grant the "nobody" user the SELECT privilege. The web server usually runs as nobody, and must be able to make queries on the database. Modify this as needed if the web server runs under a different account.

The next step is to load the database with data. This is accomplished by loading the database from a tab-delimited file containing the genomic annotations in GFF format. The Bioperl distribution comes with three tools for loading Bio::DB::GFF databases:

bp_load_gff.pl
This will incrementally load a database, optionally initializing it if it does not already exist. This script will work correctly even if the MySQL server is located on another host.
bp_bulk_load_gff.pl
This Perl script will initialize a new Bio::DB::GFF database with a fresh schema, deleting anything that was there before. It will then load the file. Only suitable for use the very first time you create a database, or when you want to start from scratch! The bulk loader

is as much as 10x faster than bp_load_gff.pl, but does not work in the situation in which the MySQL database is running on a remote host.

bp_fast_load_gff.pl
This will incrementally load a database. On UNIX systems, it will activate a fast loader that makes the speed almost the same as the bulk loader. Be careful, though, because this software relies on features that are unevenly implemented across platforms. For example, it does not work correctly on Mac OSX.

You will find these scripts in the Bioperl distribution, in the subdirectory scripts/Bio-DB-GFF. If you requested that Bioperl scripts be installed during installation, they will also be found in your command path.

For testing purposes, this distribution includes a GFF file with yeast genome annotations. The file can be found in the test_data subdirectory. If the load is successful, you should see a message indicating that 13298 features were successfully loaded.

Provided that the yeast load was successful, you may now run "make test". This invokes a small test script that tests that the database is accessible by the "nobody" user and that the basic feature retrieval functions are working.

You may also wish to load the yeast DNA, so that you can test the three-frame translation and GC content features of the browser. Because of its size, the file containing the complete yeast genome is distributed separately and can be downloaded from:

  http://prdownloads.sourceforge.net/gmod/yeast.fasta.gz?download

Load the file with this command:

  bp_load_gff.pl -d yeast -fasta yeast.fasta.gz

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

  http://name.of.your.host/cgi-bin/gbrowse/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.

IF YOU GET AN ERROR examine the Apache server error log (depending on how Apache was installed, it may be located in /usr/local/apache/logs/, /var/log/httpd/, /var/log/apache, or elsewhere). Usually there will be an informative error message in the error log. The most common problem is MySQL password or permissions problems.

Loading Other Data Sets

   Genome feature tables for the major model organisms and human can be
   found at www.gmod.org in the downloads section, but these files are not
   guaranteed to be up to date.
   Each model organism database has its own flat file format for
   representing the data. For the most up to date information, you should
   download these files and process them into GFF format. Currently, all of
   the model organism databases require some tweaking of the flat files,
   but the bioperl distribution includes several small perl scripts to make
   this easier. These scripts are optionally installed when you install
   Bioperl. You'll find them in the bioperl scripts/Bio-DB-GFF directory if
   you didn't install them directly.
   They are:
     process_gadfly.pl     For FlyBase D. melanogaster flat files
     process_sgd.pl        For SGD S. cerevisiae flat files
     process_wormbase.pl   For WormBase C. elegans flat files
   In Bioperl 1.3, these scripts are named bp_process_gadfly.pl, and so
   forth.
   Run the script with the -h option to get some data-specific help:
     % process_gadfly.pl -h
 The bp_process_wormbase.pl script requires the AcePerl package, which is
   available from CPAN. It is not strictly necessary to run this script
   because the unaltered GFF files distributed from WormBase are compatible
   with GBrowse. process_wormbase.pl supplements the information with the
   physical positions of genetic markers, GenBank accession numbers and
   functional descriptions of gene products.
   For configuration files that will work with each of these databases,
   look in contrib/conf_files (or in
   http://localhost/gbrowse/contrib/conf_files). Simply copy the
   appropriate configuration file into your gbrowse.conf directory, and
   edit the database name as appropriate.
   You might also be interested in the load_genbank.pl script, which is
   installed when you install GBrowse. You can give this script a list of
   Genbank or EMBL accession numbers and it will automatically download the
   indicated entries and load them into a MySQL database. You can also load
   flat files in Genbank or EMBL format.
   For human gene models, we suggest you use the ucsc_genes2gff.pl script,
   which operates on the files downloadable from the UCSC genome browser.
   The sample configuration file 08.genbank.conf (located in
   contrib/conf_files) is appropriate for data loaded with load_genbank.pl.
 8. LOADING DNA
   To display the DNA sequence and to run sequence-dependent glyphs such as
   the three-frame translation, you will need to load the DNA as well as
   the annotations. The DNA must be formatted as a series of one or more
   FASTA-format files in which each entry in the file corresponds to a
   top-level sequence such as a chromosome pseudomolecule. You can then run
   the bp_load_gff.pl or bp_bulk_load_gff.pl script using the -fasta
   argument. For example, if the yeast genome is contained in a FASTA file
   named yeast.fa, you would run the command:
     bp_bulk_load_gff.pl -d yeast -fasta yeast.fa sample/yeast_data.gff
   Alternatively, you may put several FASTA files into a directory, and
   provide the directory name as the argument to -fasta.
   (The yeast DNA is too large to be included in this distribution, but you
   can get a copy of it from ftp://genome-ftp.stanford.edu/pub/yeast/)
   Run "bp_bulk_load_gff.pl -h" to see usage instructions.
   Newer versions of GFF (the so-called "GFF2.5" and "GFF3" formats)
   include the DNA at the bottom of the file, following the sequence
   annotations. If you are loading one of these GFF files, the DNA will be
   recognized automatically and loaded by any of the loaders.
9. CREATING YOUR OWN GENOME DATABASE
   See the file doc/pod/CONFIGURE_HOWTO.pod for information on how to
   create new databases from scratch, add new browser tracks, and how to
   get the browser to dump the DNA from the region currently under display.
 10. MAKING THE BROWSER RUN FASTER
   Three factors are major contributors to the length of time it takes to
   load a gbrowse page:
   1   Loading the Perl interpreter and parsing BioPerl and all the other
       Perl libraries that gbrowse uses.
   2   Query speed on the database
   3   The conversion at the Perl layer of database data into BioPerl
       objects for rendering.
   To improve (1), I recommend that you install the mod_perl module for
   Apache. (<http://perl.apache.org>). By configuring an Apache::Registry
   directory and placing gbrowse inside it (rather than in the default
   cgi-bin directory). The overhead for loading Perl and its libraries are
   eliminated, thereby increasing the performance of the script noticeably.
   Be aware that there is a bad interaction between the Apache::DBI module
   (often used to speed up database accesses) and Bio::DB::GFF. This will
   cause the GFF dumper plugin to fail intermittently. GBrowse does not
   need Apache::DBI to achieve performance increases under mod_perl and it
   is suggested that you disable Apache::DBI. If you cannot do this, then
   you should remove the file GFFDumper.pm from the gbrowse.conf/plugins
   directory.
   Database query performance (2) is also a major factor. If you are using
   MySQL as the backend, you will see dramatic performance increases by
   increasing the amount of memory available to the key buffer, sort
   buffer, table cache and other in-memory data structures. I suggest that
   you replace the default MySQL configuration file (usually stored in
   /etc/my.cnf) with one of the large-memory sample configuration files
   provided in the support-files subdirectory of the MySQL distribution. Of
   course, if you tell MySQL to use more memory than you have, then
   performance will degrade again.
   Finally, there is a slowdown when gbrowse converts the results of
   database SQL queries into renderable biological objects. This becomes
   particularly noticeable when there are lots of multi-segment objects to
   be displayed. You can work around this slowdown by using semantic
   zooming (see CONFIGURE_HOWTO). Otherwise, there's not much that can be
   done about this short of buying a faster machine. The GMOD team is
   working hard to reduce this performance hit.
 11. MAKING THE SERVER RUN SAFER
   Whenever you are running a server-side Web script using information
   provided by a web client, there is a risk that maliciously-formatted
   data provided by the use will trick the server-side script into
   performing some unintentional action, such as modifying a file on the
   server. Perl's "taint" checks are designed to catch places in the code
   where such malicious data could cause harm, and GBrowse has been tested
   extensively with these taint checks activated.
   Because of taint checks' noticeable impact on performance, they have
   been turned off in the distributed version of gbrowse. If you wish to
   reactivate the extra checking (at the expense of a performance hit), go
   to the file "gbrowse" located in the Web scripts directory and edit the
   top line of the file to read:
     #!/usr/bin/perl -w -T
   The -T switch turns on taint checks.
   If you are running GBrowse under mod_perl, add the following line to the
   httpd.conf configuration file:
     PerlTaintCheck  On
   This will affect all mod_perl scripts globally.
 12. BIOPERL VERSIONS
   GBrowse is evolving quickly, and some of its features are dependent on
   new features in Bioperl 1.4.0. If you are having trouble making GBrowse
   run, make sure you are using Bioperl 1.4.0!
 13. THE GBROWSE_IMG SCRIPT
   The gbrowse_img CGI script (a new feature as of version 1.41), is a
   stripped-down version of gbrowse which just generates images. It is
   suitable for incorporating into <img> tags in order to make a thumbnail
   of a region of interest. The thumbnail can then be linked to the
   full-featured gbrowse. Here is an example of how this works using the
   WormBase site:
     <a href="http://www.wormbase.org/db/seq/gbrowse/wormbase?name=mec-3">
       <img src="http://www.wormbase.org/db/seq/gbrowse_img/wormbase?name=mec-3;width=200">
     </a>
   This will generate a 200-pixel inline image of the region. Clicking on
   the image will link to the fully-navigable gbrowse script.
   You can also use gbrowse_img to superimpose temporary features (like
   BLAST hits) on the existing genome features.
   Read docs/gbrowse_img.txt DOES NOT EXIST for the CGI parameters and
   other instructions. A copy of these instructions in HTML form will be
   generated when gbrowse_img is called without any arguments. Type
   http://your.host/cgi-bin/gbrowse_img into your favorite web browser.
 14. PLUGINS
   Gbrowse has a plugin architecture which makes it easy for third-party
   developers to expand its functionality. The plugins are Perl .pm files
   located in the directory gbrowse.conf/plugins/. To install plugins,
   simply copy them into this directory. To uninstall, remove them.
   If you wish to install your own or third party plugins, it is suggested
   that you create a separate directory outside the gbrowse.conf/ hierarchy
   in which to store them and then to indicate the location of these
   plugins using the plugin_path setting:
     plugin_path = /usr/local/gbrowse_plugins
   This setting should be somewhere in the [GENERAL] section of the
   relevant gbrowse configuration file.
 15. THE GENBANK/EMBL PROXY
   Sample configuration number 5 ("05.embl.conf") corresponds to an
   experimental pass-through proxy for Genbank. At least in theory, if you
   enter a landmark that isn't recognized, gbrowse will go to EMBL using
   the bioperl BioFetch facility, parse the record, and enter it into the
   local database. This allows you to browse arbitrary Genbank/EMBL/Refseq
   entries.
   You are free to experiment with this, but don't expect it to be entirely
   reliable. To get it to work, you must:
   1   Make sure you are using Bioperl 1.02 (or a patched version of 1.01)
   2   Create a local database named "embl" and initialize it this way:
   3   Set up permissions for this database so that "nobody@localhost" has
       SELECT, INSERT, UPDATE and DELETE privileges
   4   Initialize the database for use with this command:
         % bp_load_gff.pl -c -d embl </dev/null
       (if you are on a windows system, just leave out the </dev/null)
   5   If you need to use a proxy to access remote web sites, uncomment the
       -proxy line in the conf file, and adjust the URL of the proxy as
       appropriate.
   6   Go to http://localhost/cgi-bin/gbrowse/embl. Search for a Genbank or
       embl accession number, such as CEF58D5
 16. UPDATING THE BROWSER WITHOUT REENTERING YOUR DIRECTORY SETTINGS
   When updating GBrowse to a new version of the software, you can
   configure it using your preferred directory settings by making a backup
   copy of the file GGB.def that was generated the first time you installed
   GBrowse and using `cat GGB.def` as the argument to Makefile.PL. Here is
   the recipe:
     cp Generic-Genome-Browser-1.40/GGB.def Generic-Genome-Browser-1.41/GGB.def
     cd Generic-Genome-Browser-1.41/
     perl Makefile.PL `cat GGB.def`
     make
     make install
 17. REMOVING OUT-OF-DATE IMAGE FILES
   As GBrowse runs, it creates temporary image files in the gbrowse tmp
   directory (typically /usr/local/apache/htdocs/gbrowse/tmp). These image
   files are relatively small, but if you run GBrowse for a long time they
   may begin consuming significant amounts of disk space. The following
   Unix shell commands will remove old image files:
     cd /usr/local/apache/htdocs/gbrowse/tmp
     find . -type f -atime +20 -print -exec rm {} \;
   You might want to run this command under cron, but be aware that since
   the image files are owned by user "nobody", you must install this
   command in the cron script for "nobody" or "root."
 18. KNOWN BUGS
   Currently there is one known bug. The navigation buttons do not operate
   properly when the client is using Internet Explorer 5.1 on a Macintosh
   and accessing gbrowse running on a MacOS X server running Apache. Other
   combinations of clients and servers work properly.
 19. FEATURE WISH LIST (updated April, 2004)
     - Configure data sources on a track-by-track basis.
     - A configurable synteny viewer.
   If you are interested in working on any of these features, please
   contact the developers at the address given in the next section.
 20. SUPPORT AND BUG REPORTS
   Please send requests for help to gmod-gbrowse@lists.sourceforge.net.
   There is also a formal bug tracking and feature request system in place
   at <http://www.gmod.org/>
   Have fun!
   Lincoln Stein & the GMOD team lstein@cshl.org

AUTHORS

Copyright 2007, Lincoln D. Stein <lstein@cshl.edu>. Redistribution is welcome provided that acknowledgement of authorship is maintained.