Difference between revisions of "AmiGO Manual: Installation 1.7"

From GO Wiki
Jump to: navigation, search
Line 257: Line 257:
 
We are going to assume that you have full administrative privileges on the machine and that you are working from a fully up-to-date (as of July 27, 2009) Ubuntu 9.04 desktop machine. This will install AmiGO for local usage.
 
We are going to assume that you have full administrative privileges on the machine and that you are working from a fully up-to-date (as of July 27, 2009) Ubuntu 9.04 desktop machine. This will install AmiGO for local usage.
  
=== Getting started ===
+
== Getting Apache ==
  
First, we'll install cvs and checkout the development repository.
+
While the installation and configuration of Apache is way outside the scope of this document, we are going to assume that the installing user has read and write access to the htdocs and cgi-bin directories of the apache server. For the sake of completeness, we'll say they're the default values of "/srv/www/htdocs" and "/srv/www/cgi-bin".
 +
 
 +
To install apache, use the command:
 +
 
 +
sudo apt-get -u install apache2
 +
 
 +
The configuration file that we'll use is:
 +
 
 +
<VirtualHost *:80>
 +
ServerAdmin webmaster@localhost
 +
 
 +
#DocumentRoot /var/www
 +
DocumentRoot /srv/www/htdocs
 +
<Directory />
 +
Options FollowSymLinks
 +
AllowOverride None
 +
</Directory>
 +
#<Directory /var/www/>
 +
<Directory /srv/www/htdocs/>
 +
Options Indexes FollowSymLinks MultiViews
 +
AllowOverride None
 +
Order allow,deny
 +
allow from all
 +
</Directory>
 +
 
 +
#ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
 +
ScriptAlias /cgi-bin/ /srv/www/cgi-bin/
 +
#<Directory "/usr/lib/cgi-bin">
 +
<Directory "/srv/www/cgi-bin">
 +
AllowOverride None
 +
Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
 +
Order allow,deny
 +
Allow from all
 +
</Directory>
 +
 
 +
ErrorLog /var/log/apache2/error.log
 +
 
 +
# Possible values include: debug, info, notice, warn, error, crit,
 +
# alert, emerg.
 +
LogLevel warn
 +
 
 +
CustomLog /var/log/apache2/access.log combined
 +
 
 +
    Alias /doc/ "/usr/share/doc/"
 +
    <Directory "/usr/share/doc/">
 +
        Options Indexes MultiViews FollowSymLinks
 +
        AllowOverride None
 +
        Order deny,allow
 +
        Deny from all
 +
        Allow from 127.0.0.0/255.0.0.0 ::1/128
 +
    </Directory>
 +
 
 +
</VirtualHost>
 +
 
 +
=== Getting GO ===
 +
 
 +
As simple as installing cvs and checking out the development repository.
  
 
  sudo apt-get -u install cvs
 
  sudo apt-get -u install cvs
 
  cvs -z3 -d:pserver:anonymous@geneontology.cvs.sourceforge.net:/cvsroot/geneontology co -P go-dev
 
  cvs -z3 -d:pserver:anonymous@geneontology.cvs.sourceforge.net:/cvsroot/geneontology co -P go-dev
 
Next, using the
 
  
 
=== Database installation ===
 
=== Database installation ===
Line 272: Line 326:
 
  sudo apt-get -u install mysql-server
 
  sudo apt-get -u install mysql-server
  
Since we happen to be behind a firewall that makes effective ftp impossible we'll directly download and load the database. See the above section on database installation for more (and easier) options or go to the [http://www.geneontology.org/GO.downloads.database.shtml GO downloads page].
+
Since we happen to be behind a firewall that makes effective ftp impossible (and therefore the installation script as well) we'll directly download and load the database. See the above section on database installation for more (and easier) options or go to the [http://www.geneontology.org/GO.downloads.database.shtml GO downloads page].
  
 
  wget http://archive.geneontology.org/latest-lite/go_20090719-seqdblite-data.gz
 
  wget http://archive.geneontology.org/latest-lite/go_20090719-seqdblite-data.gz
Line 312: Line 366:
 
Our output for libraries that still need to be installed is:
 
Our output for libraries that still need to be installed is:
  
Bio::DB::SwissProt
 
Bio::Index::GenBank
 
Bio::Index::Swissprot
 
Bio::PrimarySeq
 
Bio::SeqIO
 
Bio::Species
 
 
  CGI::Application
 
  CGI::Application
 
  CGI::Application::Plugin::Redirect
 
  CGI::Application::Plugin::Redirect
 
  CGI::Application::Plugin::Session
 
  CGI::Application::Plugin::Session
 
  CGI::Application::Plugin::TT
 
  CGI::Application::Plugin::TT
 +
DBD::Sqlite
 
  DBIx::Class
 
  DBIx::Class
 
  DBIx::Class::Schema
 
  DBIx::Class::Schema
Line 340: Line 389:
 
  YAML
 
  YAML
  
While this list is more complete, it is the product of hard-wired searches and is therefor more prone to errors (such as requiring unnecessary libraries).
+
While this list is more complete, it is the product of hard-wired searches and is therefor more prone to errors (such as requiring unnecessary libraries). However, it does get fussed over fairly often, and is likely fairly comprehensive.
  
 
This method may be better for people with new installations.
 
This method may be better for people with new installations.
Line 348: Line 397:
 
The following commands include all libraries needed for the proper functioning of AmiGO. Afterwards, rerunning simulate.pl and version.pl will return no further libraries to install.
 
The following commands include all libraries needed for the proper functioning of AmiGO. Afterwards, rerunning simulate.pl and version.pl will return no further libraries to install.
  
  sudo apt-get -u install libcgi-application-perl libcgi-application-basic-plugin-bundle-perl libcgi-application-extra-plugin-bundle-perl libgraphviz-perl graphviz libdbix-class-perl libossp-uuid-perl libtest-www-mechanize-cgiapp-perl
+
  sudo apt-get -u install libcgi-application-perl libcgi-application-basic-plugin-bundle-perl libcgi-application-extra-plugin-bundle-perl libgraphviz-perl graphviz libdbix-class-perl libossp-uuid-perl libtest-www-mechanize-cgiapp-perl libdbd-sqlite3-perl
 +
 
 +
Since we want to allow for very very large numbers in JSON, we need to remove the opportunistic module JSON::XS (which does not specifically allow them).
  
#sudo apt-get -u install bioperl libgraph-perl
+
sudo apt-get -u remove libjson-xs-perl
#sudo apt-get -u install libxml-xpath-perl libxml-writer-perl libxml-libxml-perl libxml-libxslt-perl
 
  
Next, we  
+
Next, we install the GO::TermFinder module. It's not usually in distribution repositories, so it must be installed manually. Some people prefer to use CPAN directly, but for this example we'll go through the Debian package manager. There may be problems with the tests of GO-TermFinder that you'll have to fix manually.
  
 
  sudo apt-get -u install g++ dh-make-perl
 
  sudo apt-get -u install g++ dh-make-perl
 
  dh-make-perl --build --notest --cpan GO::TermFinder
 
  dh-make-perl --build --notest --cpan GO::TermFinder
  sudo dpkg -i libgo-termfinder-perl_0.7-1_amd64.deb  
+
  sudo dpkg -i libgo-termfinder-perl_0.7-1_i386.deb
  
 
All dependencies for running AmiGO (under Ubuntu 9.04) should now be met.
 
All dependencies for running AmiGO (under Ubuntu 9.04) should now be met.
  
 
=== Installation and final config.pl===
 
=== Installation and final config.pl===
 
While the installation and configuration of Apache is way outside the scope of this document, we are going to assume that the installing user has read and write access to the htdocs and cgi-bin directories of the apache server. For the sake of completeness, we'll say they're the default values of "/srv/www/htdocs" and "/srv/www/cgi-bin".
 
  
 
The final piece of installation is:
 
The final piece of installation is:
Line 369: Line 417:
 
  ./install.pl -v
 
  ./install.pl -v
  
The Q&A process, and further refinements, is hard to show here, but the final config.pl file of the machine looks like:
+
The Q&A process, and further refinements, is hard to show here, but the final config.pl file of this example machine looks like:
 +
 
 +
$ENV{GO_ROOT}='/home/sjcarbon/go-dev';
 +
$ENV{GO_DBNAME}='go_latest';
 +
$ENV{GO_DBHOST}='localhost';
 +
$ENV{GO_DBUSER}='';
 +
$ENV{GO_DBAUTH}='';
 +
$ENV{GO_DBPORT}='';
 +
$ENV{GO_DBSOCKET}='';
 +
$ENV{GO_HAS_COUNT_BY_SPECIES}='1';
 +
$ENV{AMIGO_PROJECT_NAME}='amigo';
 +
$ENV{AMIGO_HTDOCS_PARTIAL_PATH}='/srv/www/htdocs';
 +
$ENV{AMIGO_HTDOCS_PARTIAL_URL}='http://localhost';
 +
$ENV{AMIGO_CGI_PARTIAL_PATH}='/srv/www/cgi-bin';
 +
$ENV{AMIGO_CGI_PARTIAL_URL}='http://localhost/cgi-bin';
 +
$ENV{AMIGO_SHOW_GP_OPTIONS}='1';
 +
$ENV{AMIGO_SHOW_GRAPHVIZ}='1';
 +
$ENV{AMIGO_DOT_PATH}='/usr/bin/dot';
 +
$ENV{AMIGO_SHOW_BLAST}='1';
 +
$ENV{AMIGO_FASTA_DB}='/var/www/data/go.fasta';
 +
$ENV{AMIGO_BLASTP}='/usr/bin/blastp';
 +
$ENV{AMIGO_BLASTX}='/usr/bin/blastx';
 +
$ENV{AMIGO_BLAST_METHOD}='cgi';
 +
$ENV{AMIGO_QSUB}='/usr/local/command';
 +
$ENV{AMIGO_QUEUE}='/usr/local/queue';
 +
$ENV{AMIGO_PBS_USER}='nobody';
 +
$ENV{AMIGO_MAX_SEQ_NUM}='100';
 +
$ENV{AMIGO_MAX_SEQ_LENGTH}='3000000';
 +
$ENV{AMIGO_SHOW_GOOSE_LINKS}='1';
 +
$ENV{AMIGO_USE_DEFAULT_AMIGO_FILTERS}='1';
 +
$ENV{AMIGO_SHOW_ONT_FILTER}='1';
 +
$ENV{AMIGO_SHOW_TAXID_FILTER}='1';
 +
$ENV{AMIGO_SHOW_SPECIESDB_FILTER}='1';
 +
$ENV{AMIGO_SHOW_EVCODE_FILTER}='1';
 +
$ENV{AMIGO_SHOW_GPTYPE_FILTER}='1';
 +
$ENV{AMIGO_SHOW_ASSBY_FILTER}='0';
 +
$ENV{AMIGO_SHOW_QUAL_FILTER}='0';
 +
$ENV{AMIGO_TEMPLATE_PATHS}='templates/pages:templates/includes';
 +
$ENV{AMIGO_SESSION_DIR}='sessions';
 +
$ENV{AMIGO_MAX_SESSIONS}='200';
 +
$ENV{AMIGO_SESSION_TIMEOUT}='7200';
 +
$ENV{AMIGO_PAGE_SIZE}='50';
 +
$ENV{AMIGO_MAX_RESULTS_HTML}='200';
 +
$ENV{AMIGO_MAX_RESULTS_DOWNLOAD}='1000';
 +
$ENV{AMIGO_CALCULATE_GP_COUNTS}='0';
 +
$ENV{AMIGO_CALCULATE_TERM_COUNTS}='0';
 +
$ENV{AMIGO_GET_RELEVANCE}='1';
 +
$ENV{AMIGO_CLEVER_MODE}='1';
 +
$ENV{AMIGO_OBSOLETE_BEHAVIOUR}='include_commented';
 +
$ENV{AMIGO_TERM2TERM_METADATA_LOADED}='0';
 +
$ENV{AMIGO_TERM_REGEXP}='GO\:[0-9]{7}';
 +
$ENV{AMIGO_VERBOSE}='0';
 +
$ENV{AMIGO_BETA}='0';
 +
 
 +
Finally, because of script compatibility on our production servers, add a link from your perl of choice into local. Some things look there for the interpreter.
 +
 
 +
sudo ln -s /usr/bin/perl /usr/local/bin/perl
  
...
+
Enjoy your AmiGO: http://localhost/cgi-bin/amigo/go
  
 
=Contacts=
 
=Contacts=

Revision as of 14:54, 28 July 2009

Overview

This document is intended for AmiGO version 1.7 (the current beta release).

AmiGO, at its heart, is a simple perl CGI script. However, behind the simple external interface lies a somewhat baroque system of file caches, databases connections, temporary files, and delegation. To set-up all of these things properly, AmiGO provides three scripts:

  • version.pl : a script to check the environment's perl libraries and make suggestions about what should still be installed. This script should probably run first if you have never tried to install this version of AmiGO before. Probably better for new installations of AmiGO.
  • simulate.pl : similar to (and a likely replacement of) version.pl. Instead of recursively parsing files and seeing what the requirements look like, this script actually runs the various perl scripts in the perl interpreter and tries to catch what is necessary. The developers are switching over to this. Probably better for upgrading installations of AmiGO.
  • install.pl : an installation script that asks questions about the user's environment and tries to catch the biggest errors that one can make during installation.
  • refresh.pl : this final script creates all of the caches for the various subsystems. Required (as opposed to recommended, but technically optional) caches are also created during the installation process (install.pl). This script is useful for refreshing caches and taking some of the load off of the processing needed for Reference Genome subsystems (which wouldn't really be necessary for most installations of AmiGO).

All of the scripts will give options and help with the "perldoc <scriptname>" command.

The rest document is intended to help fill the gaps between the cryptic install scripts and what the developers know because they wrote it; no installation system is perfect.

As a concrete example, at the end is a HOWTO for the installation of AmiGO from a completely fresh Ubuntu 9.04 desktop system.

Download

The most recent stable version of AmiGO should be available as part of the go-dev repository on the GO CVS site at SourceForge.net: http://sourceforge.net/projects/geneontology

The sourceforge CVS repository can be found at: geneontology.cvs.sourceforge.net:/cvsroot/geneontology go-dev (this is a change from a couple years ago). I do not think that you need any subdirectories of go-dev other than go-perl, go-db-perl, and amigo.

You also need a GO database you can connect to via DBD::mysql (which you might already have if you have an old amigo installation).

Requirements

GO database

There are numerous ways of loading GO into a MySQL database for AmiGO to use. Below, two of the most common will be covered. For more detailed information, please see the main GO database pages.

A lot more is outside the scope of this document. For more information about installing, see the online documentation. For permission issues with connecting to your GO database, check with your friendly system admin.

Loading by script

Probably the easiest way of getting a GO database to work with is using a perl script that is provided in the go-dev distribution (see above): go-dev/go-db-perl/scripts/go_db_install.pl. Usage and examples are given by:

go-dev/go-db-perl/scripts/go_db_install.pl -h

For example, the following incantation will load the latest lite database dump into a database called go_latest_lite on localhost:

go-dev/go-db-perl/scripts/go_db_install.pl -i -e go_latest_lite -v -d localhost

The following example loads the latest database dump into a database called go_latest onto localhost:

go-dev/go-db-perl/scripts/go_db_install.pl -v -d localhost

This method is also very easy to put into a crontab.

Manual loading

The following instructions can be used to create a GO database for AmiGO to use.

  • Download a database dump from http://archive.geneontology.org/ ; make sure that the file name ends with "-data.gz". In this example, we'll call this file go_200XXXXX-seqdblite-data.gz.
  • Unzip the database dump file.
  • Using your favorite MySQL client, create a database. In this example we'll call it go_2000XXXXX. Using the default MySQL client, the command would be :
CREATE DATABASE go_200XXXXX;
  • From the command line, load the database dump file into the database:
mysql go_200XXXXX < go_200XXXXX-seqdblite-data
  • Done!

Loading Annotations

While the usual GO database dumps found at http://archive.geneontology.org include many useful annotations, users may also load their own annotations into their local GO databases. To accomplish this, the go-dev distribution comes with many different scripts to manage association files. The easiest to use is probably go-dev/go-db-perl/scripts/load-go-into-db.pl .

The following incantation would load a gene association (ga_file.gz) file into the my_go_db database on localhost:

GO_ROOT=/path_to_go-dev/go-dev perl ./load-go-into-db.pl -d my_go_db -h localhost -datatype go_assoc -fill_count ga_file.gz

If the user does not have the perl DBIx::Stag, go-perl, or go-db-perl modules loaded and/or in their path, the same incantation would look like:

 GO_ROOT=/path_to_go-dev/go-dev perl -I /path_to_go-dev/go-dev/go-db-perl -I /path_to_go-dev/go-dev/go-perl -I /path_to_dbixstag/DBIx-DBStag-0.09 ./load-go-into-db.pl -d my_go_db -h localhost -datatype go_assoc -fill_count ga_file.gz

Web server

AmiGO does not provide its own web server, it is currently developed and run on Apache. However, there are some experimental components that run their own web server, but it is unlikely this will concern most people trying to install AmiGO.

For what it's worth, AmiGO is currently developed on various sub-versions of Apache 2.2 and has its main public deployment on Apache 2.0.

BLAST

Also, if you are interested having the AmiGO wrapper for BLAST, you will need to download and install WU BLAST. You will also need a FASTA file from the Stanford GO archive.

GraphViz

Currently, AmiGO also depends on having GraphViz in its execution path--specifically the "dot" program.

Perl

As far as the perl environment goes, major packages that are necessary are: CGI::Application, GO::TermFinder, Template, CGI, DBI, and DBD::mysql, GraphViz, bioperl, go-perl, and go-db-perl (the last two included with the go-dev repository and are sometimes treated differently because of this--AmiGO is usually run as part of the complete go-dev repository). The vast majority of these should be available in your distribution. Otherwise, you will have to install them manually through CPAN.

version.pl

There is a script in go-dev/amigo called version.pl that can be used to get a more detailed opinion of what the developers feel is necessary to run AmiGO (there are many old, uneccessary, and experimental libraries that might confuse things). The script must be run from the go-dev/amigo directory.

simulate.pl

As mentioned above, simulate.pl may be the new version.pl. We're still trying it out, but so far so good.

install.pl

Once you have the software and requirements met, you just go to the amigo directory and type install.pl (the "-h" flag you will get usage details). Depending on your environment, you may want to first set the following ENV variables:

setenv GO_ROOT <path_to_go-dev_source_dir>
setenv PATH /tools/perl/5.8.8/bin:${PATH}:${GO_ROOT}/go-perl/scripts
setenv PERLLIB $GO_ROOT/go-perl:$GO_ROOT/go-db-perl:$GO_ROOT/amigo/perl

When you run install.pl it asks you around a couple dozen questions about the installation configuration. The questions may be a little cryptic (the "-v" flag can be helpful here). A "config.pl" file will be created in the same directory as installer.pl during a successful installation run and is the basis for all future installation attempts after the first.

The "-r" option will overwrite config.pl if it exists and use its contents as defaults for a new round of interactive questioning.

The "-i" option will ignore config.pl if it exists and use the internal variables as the defaults for a new round of interactive questioning.

The "-f <filname>" option will read in <filename>, write a new config.pl, and continue installation as normal. This is useful if you have multiple AmiGO configurations that you're trying to juggle.

There is also the ability to change config.pl manually and rerunning installer.pl with no arguments at all--by default, it will use whatever is in config.pl. This is how I generally do things. (Also, I typically use this and copy different known good configurations elsewhere for use with the "-f" option.

Using the "-v" option in conjunction with any of the other options may give you a better idea of what variables are being targeted and what files are read.

Google Analytics

To enable Google Analyics in AmiGO, create a file called .analytics.json in the AmiGO cgi-bin directory and enter your id as below:

{"google_analytics_id":"UA-XXXXXXX-X"}

Example config.pl files

While you can construct a config.pl file from scratch, it is highly recommended that you let the script create the file the first time, and then you may modify the values manually and rerun the script.

Be prepared to accept defaults or have an answer for these. Obviously, the path names are the most important.

Example file #1

These are the values used by one of the developer's at Berkeley.

config.pl

$ENV{GO_ROOT}='/home/sjcarbon/local/src/cvs/go-dev';
$ENV{GO_DBNAME}='go_new';
$ENV{GO_DBHOST}='localhost';
$ENV{GO_DBUSER}=;
$ENV{GO_DBAUTH}=;
$ENV{GO_DBPORT}=;
$ENV{GO_DBSOCKET}=;
$ENV{GO_HAS_COUNT_BY_SPECIES}='1';
$ENV{AMIGO_PROJECT_NAME}='amigo';
$ENV{AMIGO_HTDOCS_PARTIAL_PATH}='/srv/www/htdocs';
$ENV{AMIGO_HTDOCS_PARTIAL_URL}='http://localhost';
$ENV{AMIGO_CGI_PARTIAL_PATH}='/srv/www/cgi-bin';
$ENV{AMIGO_CGI_PARTIAL_URL}='http://localhost/cgi-bin';
$ENV{AMIGO_SHOW_GP_OPTIONS}='1';
$ENV{AMIGO_SHOW_GRAPHVIZ}='1';
$ENV{AMIGO_DOT_PATH}='/usr/bin/dot';
$ENV{AMIGO_SHOW_BLAST}='1';
$ENV{AMIGO_FASTA_DB}='/www/toy_9002/cgi-bin/data/go_20071106-seqdblite.fasta';
$ENV{AMIGO_BLASTP}='/share/bdgp64/wublast/blastp';
$ENV{AMIGO_BLASTX}='/share/bdgp64/wublast/blastx';
$ENV{AMIGO_BLAST_METHOD}='cgi';
$ENV{AMIGO_QSUB}='/usr/local/command';
$ENV{AMIGO_QUEUE}='/usr/local/queue';
$ENV{AMIGO_PBS_USER}='nobody';
$ENV{AMIGO_MAX_SEQ_NUM}='100';
$ENV{AMIGO_MAX_SEQ_LENGTH}='3000000';
$ENV{AMIGO_SHOW_GOOSE_LINKS}='1';
$ENV{AMIGO_USE_DEFAULT_AMIGO_FILTERS}='1';
$ENV{AMIGO_SHOW_ONT_FILTER}='1';
$ENV{AMIGO_SHOW_TAXID_FILTER}='1';
$ENV{AMIGO_SHOW_SPECIESDB_FILTER}='1';
$ENV{AMIGO_SHOW_EVCODE_FILTER}='1';
$ENV{AMIGO_SHOW_GPTYPE_FILTER}='1';
$ENV{AMIGO_SHOW_ASSBY_FILTER}='0';
$ENV{AMIGO_SHOW_QUAL_FILTER}='0';
$ENV{AMIGO_TEMPLATE_PATHS}='templates/pages:templates/includes';
$ENV{AMIGO_SESSION_DIR}='sessions';
$ENV{AMIGO_MAX_SESSIONS}='200';
$ENV{AMIGO_SESSION_TIMEOUT}='7200';
$ENV{AMIGO_PAGE_SIZE}='50';
$ENV{AMIGO_MAX_RESULTS_HTML}='200';
$ENV{AMIGO_MAX_RESULTS_DOWNLOAD}='1000';
$ENV{AMIGO_CALCULATE_GP_COUNTS}='0';
$ENV{AMIGO_CALCULATE_TERM_COUNTS}='0';
$ENV{AMIGO_GET_RELEVANCE}='1';
$ENV{AMIGO_CLEVER_MODE}='1';
$ENV{AMIGO_OBSOLETE_BEHAVIOUR}='include_commented';
$ENV{AMIGO_TERM2TERM_METADATA_LOADED}='0';
$ENV{AMIGO_TERM_REGEXP}='GO\:[0-9]{7}';
$ENV{AMIGO_VERBOSE}='1';
$ENV{AMIGO_BETA}='1';


Variable meanings

Below is a list of meanings for some of the more important AmiGO variables that might not self-evident.

  • GO_ROOT : The location of the local go-dev repository.
  • GO_DBNAME
  • GO_DBHOST
  • GO_DBUSER
  • GO_DBAUTH
  • GO_DBSOCKET
  • GO_HAS_COUNT_BY_SPECIES : Whether or not this was done during the GO db installation process.
  • AMIGO_PROJECT_NAME : This will be added to the end of the next four variables to copy files to the proper location and generate URLs. Useful to change if you want multiple AMiGO installations on the same web server.
  • AMIGO_HTDOCS_PARTIAL_PATH : The path to the root htdocs directory (in Apache terminology).
  • AMIGO_HTDOCS_PARTIAL_URL : The URL the above resolves to.
  • AMIGO_CGI_PARTIAL_PATH : The path to the root cgi-bin directory
  • AMIGO_CGI_PARTIAL_URL : The URL the above resolves to.
  • AMIGO_SHOW_GP_OPTIONS
  • AMIGO_SHOW_GRAPHVIZ
  • AMIGO_DOT_PATH : Location of the dot binary
  • AMIGO_SHOW_BLAST
  • AMIGO_FASTA_DB : The location of the downloaded FASTA file.
  • AMIGO_BLASTP
  • AMIGO_BLASTX
  • AMIGO_BLAST_METHOD
  • AMIGO_QSUB
  • AMIGO_QUEUE
  • AMIGO_PBS_USER
  • AMIGO_MAX_SEQ_NUM
  • AMIGO_MAX_SEQ_LENGTH
  • AMIGO_SHOW_GOOSE_LINKS
  • AMIGO_USE_DEFAULT_AMIGO_FILTERS
  • AMIGO_SHOW_ONT_FILTER
  • AMIGO_SHOW_TAXID_FILTER
  • AMIGO_SHOW_SPECIESDB_FILTER
  • AMIGO_SHOW_EVCODE_FILTER
  • AMIGO_SHOW_GPTYPE_FILTER
  • AMIGO_SHOW_ASSBY_FILTER
  • AMIGO_SHOW_QUAL_FILTER
  • AMIGO_TEMPLATE_PATHS
  • AMIGO_SESSION_DIR
  • AMIGO_MAX_SESSIONS
  • AMIGO_SESSION_TIMEOUT
  • AMIGO_PAGE_SIZE
  • AMIGO_MAX_RESULTS_HTML
  • AMIGO_MAX_RESULTS_DOWNLOAD
  • AMIGO_CALCULATE_GP_COUNTS
  • AMIGO_CALCULATE_TERM_COUNTS
  • AMIGO_GET_RELEVANCE
  • AMIGO_CLEVER_MODE
  • AMIGO_OBSOLETE_BEHAVIOUR
  • AMIGO_TERM2TERM_METADATA_LOADED
  • AMIGO_TERM_REGEXP
  • AMIGO_VERBOSE : Whether or not to output tons of debugging information. Useful for debugging.
  • AMIGO_BETA : Whether of not to make the experimental version of AmiGO visible (used with the install.pl -e option).

Example Installation

Even though currently we only have a step-by-step for the most recent Ubuntu, the instructions should hold with little change (different package manager commands) for other flavors of *nix.

Ubuntu 9.04 desktop

We are going to assume that you have full administrative privileges on the machine and that you are working from a fully up-to-date (as of July 27, 2009) Ubuntu 9.04 desktop machine. This will install AmiGO for local usage.

Getting Apache

While the installation and configuration of Apache is way outside the scope of this document, we are going to assume that the installing user has read and write access to the htdocs and cgi-bin directories of the apache server. For the sake of completeness, we'll say they're the default values of "/srv/www/htdocs" and "/srv/www/cgi-bin".

To install apache, use the command:

sudo apt-get -u install apache2

The configuration file that we'll use is:

<VirtualHost *:80>

ServerAdmin webmaster@localhost

#DocumentRoot /var/www DocumentRoot /srv/www/htdocs <Directory /> Options FollowSymLinks AllowOverride None </Directory> #<Directory /var/www/> <Directory /srv/www/htdocs/> Options Indexes FollowSymLinks MultiViews AllowOverride None Order allow,deny allow from all </Directory>

#ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ ScriptAlias /cgi-bin/ /srv/www/cgi-bin/ #<Directory "/usr/lib/cgi-bin"> <Directory "/srv/www/cgi-bin"> AllowOverride None Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch Order allow,deny Allow from all </Directory>

ErrorLog /var/log/apache2/error.log

# Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel warn

CustomLog /var/log/apache2/access.log combined

   Alias /doc/ "/usr/share/doc/"
   <Directory "/usr/share/doc/">
       Options Indexes MultiViews FollowSymLinks
       AllowOverride None
       Order deny,allow
       Deny from all
       Allow from 127.0.0.0/255.0.0.0 ::1/128
   </Directory>
</VirtualHost>

Getting GO

As simple as installing cvs and checking out the development repository.

sudo apt-get -u install cvs
cvs -z3 -d:pserver:anonymous@geneontology.cvs.sourceforge.net:/cvsroot/geneontology co -P go-dev

Database installation

First, we'll download the appropriate MySQL server package.

sudo apt-get -u install mysql-server

Since we happen to be behind a firewall that makes effective ftp impossible (and therefore the installation script as well) we'll directly download and load the database. See the above section on database installation for more (and easier) options or go to the GO downloads page.

wget http://archive.geneontology.org/latest-lite/go_20090719-seqdblite-data.gz
gunzip  go_20090719-seqdblite-data.gz
sudo mysql -p
mysql> CREATE DATABASE go_latest;
mysql> GRANT ALL ON go_latest.* TO @'localhost';
mysql> quit
mysql go_latest < go_20090719-seqdblite-data

Running simulate.pl

Next, we'll take a look at what the simulator thinks is necessary.

cd go-dev/amigo
./simulate.pl

This gives output about what libraries are searched for when perl is run for the various parts of AmiGO. Our output for libraries that still need to be installed is:

CGI::Application
GO::TermFinder
JSON
Template

This list is very small because as perl tries to compile the programs, by not being able to meet these dependencies, it is unable to find deeper ones. After these libraries are installed, rerunning simulate.pl would give a different set.

This method may be better for people upgrading their installation.

Running version.pl

Now, let's take a look at what the other library detection script thinks is necessary. If you haven't already, go to the amigo directory:

cd go-dev/amigo

Now run the script:

./version.pl

Our output for libraries that still need to be installed is:

CGI::Application
CGI::Application::Plugin::Redirect
CGI::Application::Plugin::Session
CGI::Application::Plugin::TT
DBD::Sqlite
DBIx::Class
DBIx::Class::Schema
Data::FormValidator
Data::UUID
GO::TermFinder
Graph::Directed
Graph::TransitiveClosure
GraphViz
FreezeThaw
IO::Scalar
JSON
Template
Template::Constants
Test::WWW::Mechanize::CGIApp
WWW::Mechanize
XML::Writer
YAML

While this list is more complete, it is the product of hard-wired searches and is therefor more prone to errors (such as requiring unnecessary libraries). However, it does get fussed over fairly often, and is likely fairly comprehensive.

This method may be better for people with new installations.

Getting the proper libraries

The following commands include all libraries needed for the proper functioning of AmiGO. Afterwards, rerunning simulate.pl and version.pl will return no further libraries to install.

sudo apt-get -u install libcgi-application-perl libcgi-application-basic-plugin-bundle-perl libcgi-application-extra-plugin-bundle-perl libgraphviz-perl graphviz libdbix-class-perl libossp-uuid-perl libtest-www-mechanize-cgiapp-perl libdbd-sqlite3-perl

Since we want to allow for very very large numbers in JSON, we need to remove the opportunistic module JSON::XS (which does not specifically allow them).

sudo apt-get -u remove libjson-xs-perl

Next, we install the GO::TermFinder module. It's not usually in distribution repositories, so it must be installed manually. Some people prefer to use CPAN directly, but for this example we'll go through the Debian package manager. There may be problems with the tests of GO-TermFinder that you'll have to fix manually.

sudo apt-get -u install g++ dh-make-perl
dh-make-perl --build --notest --cpan GO::TermFinder
sudo dpkg -i libgo-termfinder-perl_0.7-1_i386.deb

All dependencies for running AmiGO (under Ubuntu 9.04) should now be met.

Installation and final config.pl

The final piece of installation is:

./install.pl -v

The Q&A process, and further refinements, is hard to show here, but the final config.pl file of this example machine looks like:

$ENV{GO_ROOT}='/home/sjcarbon/go-dev';
$ENV{GO_DBNAME}='go_latest';
$ENV{GO_DBHOST}='localhost';
$ENV{GO_DBUSER}=;
$ENV{GO_DBAUTH}=;
$ENV{GO_DBPORT}=;
$ENV{GO_DBSOCKET}=;
$ENV{GO_HAS_COUNT_BY_SPECIES}='1';
$ENV{AMIGO_PROJECT_NAME}='amigo';
$ENV{AMIGO_HTDOCS_PARTIAL_PATH}='/srv/www/htdocs';
$ENV{AMIGO_HTDOCS_PARTIAL_URL}='http://localhost';
$ENV{AMIGO_CGI_PARTIAL_PATH}='/srv/www/cgi-bin';
$ENV{AMIGO_CGI_PARTIAL_URL}='http://localhost/cgi-bin';
$ENV{AMIGO_SHOW_GP_OPTIONS}='1';
$ENV{AMIGO_SHOW_GRAPHVIZ}='1';
$ENV{AMIGO_DOT_PATH}='/usr/bin/dot';
$ENV{AMIGO_SHOW_BLAST}='1';
$ENV{AMIGO_FASTA_DB}='/var/www/data/go.fasta';
$ENV{AMIGO_BLASTP}='/usr/bin/blastp';
$ENV{AMIGO_BLASTX}='/usr/bin/blastx';
$ENV{AMIGO_BLAST_METHOD}='cgi';
$ENV{AMIGO_QSUB}='/usr/local/command';
$ENV{AMIGO_QUEUE}='/usr/local/queue';
$ENV{AMIGO_PBS_USER}='nobody';
$ENV{AMIGO_MAX_SEQ_NUM}='100';
$ENV{AMIGO_MAX_SEQ_LENGTH}='3000000';
$ENV{AMIGO_SHOW_GOOSE_LINKS}='1';
$ENV{AMIGO_USE_DEFAULT_AMIGO_FILTERS}='1';
$ENV{AMIGO_SHOW_ONT_FILTER}='1';
$ENV{AMIGO_SHOW_TAXID_FILTER}='1';
$ENV{AMIGO_SHOW_SPECIESDB_FILTER}='1';
$ENV{AMIGO_SHOW_EVCODE_FILTER}='1';
$ENV{AMIGO_SHOW_GPTYPE_FILTER}='1';
$ENV{AMIGO_SHOW_ASSBY_FILTER}='0';
$ENV{AMIGO_SHOW_QUAL_FILTER}='0';
$ENV{AMIGO_TEMPLATE_PATHS}='templates/pages:templates/includes';
$ENV{AMIGO_SESSION_DIR}='sessions';
$ENV{AMIGO_MAX_SESSIONS}='200';
$ENV{AMIGO_SESSION_TIMEOUT}='7200';
$ENV{AMIGO_PAGE_SIZE}='50';
$ENV{AMIGO_MAX_RESULTS_HTML}='200';
$ENV{AMIGO_MAX_RESULTS_DOWNLOAD}='1000';
$ENV{AMIGO_CALCULATE_GP_COUNTS}='0';
$ENV{AMIGO_CALCULATE_TERM_COUNTS}='0';
$ENV{AMIGO_GET_RELEVANCE}='1';
$ENV{AMIGO_CLEVER_MODE}='1';
$ENV{AMIGO_OBSOLETE_BEHAVIOUR}='include_commented';
$ENV{AMIGO_TERM2TERM_METADATA_LOADED}='0';
$ENV{AMIGO_TERM_REGEXP}='GO\:[0-9]{7}';
$ENV{AMIGO_VERBOSE}='0';
$ENV{AMIGO_BETA}='0';

Finally, because of script compatibility on our production servers, add a link from your perl of choice into local. Some things look there for the interpreter.

sudo ln -s /usr/bin/perl /usr/local/bin/perl

Enjoy your AmiGO: http://localhost/cgi-bin/amigo/go

Contacts

If you are still having problems installing the AmiGO software, you can contact the developers directly :

  • Seth at LBNL (sjcarbon) (berkeleybop dot org)
  • Amelia at EBI (aji) (ebi dot ac dot uk)

Good Luck

Good luck!