AmiGO Manual: Installation 1.8

From GO Wiki
Jump to: navigation, search

Overview

This document is intended for AmiGO_1_8 (the current production 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 and can be used for cleaning and maintenance of your AmiGO installation. Required (as opposed to recommended, but technically optional) caches are also created during the installation process by install.pl calling this script behind the scenes. This script is useful for many things and pretty much necessary for the Reference Genome subsystems (which aren'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 10.04 desktop system.

Download

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

The SourceForge SVN repository can be found at: geneontology.svn.sourceforge.net/svnroot/geneontology geneontology (this is a change from the old CVS as of 5/15/2010). For AmiGO, the current branch is located in "amigo_1_8". I do not think that you need any subdirectories of geneontology/go-dev other than go-perl, go-db-perl, and amigo, but you will need gobo-dbic and javascript as well. A quick way to get all of these is to simply download from svn using the following commands:

svn co https://geneontology.svn.sourceforge.net/svnroot/geneontology/go-dev/branches/amigo_1_8 geneontology
svn co https://geneontology.svn.sourceforge.net/svnroot/geneontology/gobo-dbic geneontology/gobo-dbic
svn co https://geneontology.svn.sourceforge.net/svnroot/geneontology/javascript geneontology/javascript

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

Operating System/Environment

AmiGO is designed on, and developed for, Unix-style environments. The last time we attempted to install AmiGO in a non-Unix-style environment (a version of Windows), we ran into significant difficulties with the perl environment; we tried both Active Perl and the Cygwin environments. Since then, the perl dependencies have only gotten more complicated and I don't believe that the perl situation in Windows has improved--it is unlikely that you would be able to run AmiGO directly in a Windows environment without a significant time investment.

My best suggestion for installing AmiGO in a Windows environment would be to install Linux onto a virtual machine on Windows and run it from there.

Also, if you are interested, a Live CD version of AmiGO has been developed that may be of some help to you (although its development lags behind the main development--contact the AmiGO developers if you are interested).

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): geneontology/go-dev/go-db-perl/scripts/go_db_install.pl. Usage and examples are given by:

geneontology/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:

geneontology/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:

geneontology/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_20XXXXXX-seqdblite-data.gz.
  • Unzip the database dump file.
  • Using your favorite MySQL client, create a database. In this example we'll call it go_20XXXXXX. Using the default MySQL client, the command would be :
CREATE DATABASE go_20XXXXXX;
  • From the command line, load the database dump file into the database:
mysql go_20XXXXXX < go_20XXXXXX-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/geneontology/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/genontology/go-dev perl -I /path_to/geneontology/go-dev/go-db-perl -I /path_to/geneontology/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

Due to perl compatibility issues between different servers in our production environments (custom perl installations), AmiGO defaults to a different interpreter than usual. This shouldn't be an issue in some Apache environments, but you may need to add the following link:

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

This is especially useful when testing scripts from the command line.

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 (although they should not be necessary for most standard uses):

export GO_ROOT <path to geneontology/go-dev source dir>
export PATH ${PATH}:${GO_ROOT}/go-perl/scripts
export 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.

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

This is the file used by one of the developer's at Berkeley.

config.pl

############################
##
## User Changeable Variables
##
## You may alter the install template by changing the
## variable below.
##
############################

$ENV{GO_SVN_ROOT}='/home/sjcarbon/local/src/svn/geneontology';
$ENV{GO_DBNAME}='go_latest_lite';
$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_PUBLIC_CGI_PARTIAL_URL}='http://amigo.geneontology.org/cgi-bin';
$ENV{AMIGO_SHOW_GP_OPTIONS}='1';
$ENV{AMIGO_SHOW_GRAPHVIZ}='1';
$ENV{AMIGO_DOT_PATH}='/usr/bin/dot';
$ENV{AMIGO_SHOW_BLAST}='0';
$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}='all|GO\:[0-9]{7}';
$ENV{AMIGO_GO_ONLY_GRAPHICS}='1';
$ENV{AMIGO_VERSION}='1.8';
$ENV{AMIGO_VERBOSE}='1';
$ENV{AMIGO_TROUBLE_SWITCH}='0';
$ENV{AMIGO_TROUBLE_MESSAGE}='<h2 style="text-align: center;">AmiGO is currently experiencing some difficulty.<br />You may want to temporarily try <a href="http://amigo.berkeleybop.org/cgi-bin/amigo/go.cgi" title="Go to AmiGO Labs">AmiGO Labs</a> instead.</h2>';
$ENV{AMIGO_BETA}='1';
$ENV{AMIGO_GOOGLE_ANALYTICS_ID}='';

############################
##
## Synthetic Variables
##
## Changing these accomplishes nothing,
## they are here for debugging purposes.
##
############################

$ENV{AMIGO_TESTS_DIR}='/srv/www/htdocs/amigo/tests';
$ENV{AMIGO_SCRATCH_DIR}='/srv/www/cgi-bin/amigo/sessions/scratch';
$ENV{AMIGO_INDEX_DIR}='/srv/www/cgi-bin/amigo/index';
$ENV{AMIGO_PRE_RENDER_URL}='http://localhost/amigo/pre_render';
$ENV{AMIGO_IMAGE_DIR}='/srv/www/htdocs/amigo/images';
$ENV{AMIGO_IMAGE_URL}='http://localhost/amigo/images';
$ENV{AMIGO_LOG_DIR}='/srv/www/cgi-bin/amigo/log';
$ENV{AMIGO_TESTS_URL}='http://localhost/amigo/tests';
$ENV{AMIGO_TEMP_IMAGE_DIR}='/srv/www/htdocs/amigo/tmp_images';
$ENV{GO_ROOT}='/home/sjcarbon/local/src/svn/geneontology/go-dev';
$ENV{AMIGO_INDEX_DIR_GENE_PRODUCT}='/srv/www/cgi-bin/amigo/index/lucene/gene_product';
$ENV{AMIGO_SERVICE_URL}='http://localhost/cgi-bin/amigo/aserve';
$ENV{AMIGO_CACHE_DIR}='/srv/www/cgi-bin/amigo/cache';
$ENV{AMIGO_PUBLIC_CGI_URL}='http://amigo.geneontology.org/cgi-bin/amigo';
$ENV{AMIGO_INDEX_DIR_GENERAL}='/srv/www/cgi-bin/amigo/index/lucene/general';
$ENV{AMIGO_HTDOCS_ROOT_DIR}='/srv/www/htdocs/amigo';
$ENV{AMIGO_INDEX_DIR_TERM}='/srv/www/cgi-bin/amigo/index/lucene/term';
$ENV{AMIGO_CGI_ROOT_DIR}='/srv/www/cgi-bin/amigo';
$ENV{AMIGO_HTML_URL}='http://localhost/amigo';
$ENV{AMIGO_CGI_URL}='http://localhost/cgi-bin/amigo';
$ENV{AMIGO_PRE_RENDER_DIR}='/srv/www/htdocs/amigo/pre_render';
$ENV{AMIGO_SESSIONS_ROOT_DIR}='/srv/www/cgi-bin/amigo/sessions';
$ENV{AMIGO_TEMP_IMAGE_URL}='http://localhost/amigo/tmp_images';

1;

Variable Meanings

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

  • GO_SVN_ROOT : The location of the local geneontology repository.
  • 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_DOT_PATH : Location of the dot binary
  • AMIGO_FASTA_DB : The location of the downloaded FASTA file.
  • AMIGO_VERBOSE : Whether or not to output tons of debugging information. The value should be '1' or '0'. Specifically, when the value is set to '1' and the file kvetch.log is universally readable and writeable in the amigo cgi-bin log directory (see the value of the synthetic variable AMIGO_LOG_DIR in config.pl), AmiGO will dump all debugging information to this file.
  • 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, etc.) for other flavors of *nix.

Ubuntu 10.04 Desktop

We are going to assume that you have full administrative privileges on the machine as user "bbop" and that you are working from a fully up-to-date Ubuntu 10.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

We'll overwrite the default configuration in /etc/apache2/sites-available/default with the following configuration:

<VirtualHost *:80>
   ServerAdmin webmaster@localhost

   DocumentRoot /srv/www/htdocs

   <Directory />
      Options FollowSymLinks
      AllowOverride None
   </Directory>

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

   ScriptAlias /cgi-bin/ /srv/www/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
   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>

Make sure that the directories mentioned are created permissive for your install user and restart the server (sudo /etc/init.d/apache2 restart).

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 described above go database 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. This is just an example, you might want to check for a more recent database.

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

Getting the Code

This is as simple as downloading the most current release from the project's download page or installing subversion and checking out the repository. For this example, we'll check out the development version from the repository.

mkdir -p ~/local/src/svn
cd ~/local/src/svn
sudo apt-get -u install subversion
svn co https://geneontology.svn.sourceforge.net/svnroot/geneontology/go-dev/branches/amigo_1_8 geneontology/go-dev

There is also a required related GO library: GOBO::DBIC::GODBModel (libgobo-dbic-godbmodel-perl) that you will need to run AmiGO. Since this is also part of the geneontology subversion repository you can get it the same way:

svn co https://geneontology.svn.sourceforge.net/svnroot/geneontology/gobo-dbic geneontology/gobo-dbic

It is also occasionally released separately on CPAN, but may well already be out of date. If you choose to use it directly out of SVN in this way, your AmiGO installation will try to detect it automatically. From here on out, we'll assume that you've done one of these.

Again, you will now also need the separate JavaScript repository now as well:

svn co https://geneontology.svn.sourceforge.net/svnroot/geneontology/javascript geneontology/javascript

Installing Libraries

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

cd geneontology/go-dev/amigo

Running version.pl

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
File::Slurp
GO::TermFinder
Graph::Directed
Graph::TransitiveClosure
GraphViz
IO::Scalar
JSON
JSON::PP
Template
Template::Constants
Test::WWW::Mechanize::CGIApp
WWW::Mechanize
XML::Writer
YAML

While this list seems complete, it is the product of hard-wired searches and is therefore 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.

Running simulate.pl

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

./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::PP
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 listed libraries are installed, rerunning simulate.pl would give a different set. When installing, iterating using this method until simulate.pl finds no more problems will satisfy all of AmiGO's requirements.

This method is more "correct" than version.pl, but obviously can be a bit of a pain to use. It may be better for people upgrading their installation.

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 libfile-type-perl libcgi-application-perl libcgi-application-basic-plugin-bundle-perl libcgi-application-extra-plugin-bundle-perl libgraphviz-perl graphviz libdbix-class-perl libdbd-sqlite3-perl libtest-www-mechanize-cgiapp-perl libossp-uuid-perl libfile-slurp-perl libhtml-highlight-perl bioperl perl-doc libjson-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 allow them).

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

If your package manager doesn't have the perl packages for GO::TermFinder or Lucene, you will have to create them yourself. Some people prefer to use CPAN directly, but for this example we'll go through the Ubuntu/Debian package manager.

First, we need to make sure that we have the proper build tools:

sudo apt-get -u install g++ dh-make-perl

After moving to a different directory for building, the first package we'll do is Lucene. We'll need to get the dev libs and then create the package.

sudo apt-get -u install libclucene-dev
dh-make-perl --build --cpan Lucene
sudo dpkg -i liblucene-perl_0.18-1_amd64.deb

Next, we'll install the GO::TermFinder module. There may be problems with the tests of GO-TermFinder and the (mistaken) requirement that you have libgd-perl installed (unnecessary as we are not using the GO::View module). You may have to fix or force these manually. People without problems can just try this:

dh-make-perl --build --cpan GO::TermFinder
sudo dpkg -i libgo-termfinder-perl_0.85-1_i386.deb

However, for people who do have issues, the sequence to fix the dependency will look like:

dh-make-perl --build --cpan GO::TermFinder
dpkg-deb --extract libgo-termfinder-perl_0.85-1_amd64.deb ./foo
dpkg-deb --control libgo-termfinder-perl_0.85-1_amd64.deb ./foo/DEBIAN
YOUR_FAVORITE_EDITOR foo/DEBIAN/control
dpkg-deb --build foo
sudo dpkg -i foo.deb

Where the libgd-perl dependency is removed when using the text editor.

To force the installation of this package, try:

sudo dpkg -i --force-depends libgo-termfinder-perl_0.85-1_amd64.deb

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

Link to perl

Because of script compatibility, add a link from your perl of choice into local.

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

Lying About BLAST (optional)

For out test installation, we are going to ignore adding BLAST functionality. However, the installer requires that BLAST and the data are installed somewhere. To get around this, we are going to add the following workaround. If you have BLAST and the data installed, ignore this section.

mkdir /srv/www/data
touch /srv/www/data/go.fasta
touch /srv/www/data/blastp
touch /srv/www/data/blastx
chmod 755 /srv/www/data/blastp
chmod 755 /srv/www/data/blastx

Installation and Final config.pl

The final piece of installation is:

./install.pl -v

Most of the default arguments should be fine. The Q&A process and further refinements are hard to show here, but the final config.pl file of this example machine looks like:

$ENV{GO_DEV_ROOT}='/home/bbop/local/src/svn/geneontology/go-dev';
$ENV{GO_JS_ROOT}='/home/bbop/local/src/svn/geneontology/javascript';
$ENV{GOBO_ROOT}='/home/bbop/local/src/svn/geneontology/gobo-dbic';
$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_PUBLIC_CGI_PARTIAL_URL}='http://amigo.geneontology.org/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}='/srv/www/data/go.fasta';
$ENV{AMIGO_BLASTP}='/srv/www/data/blastp';
$ENV{AMIGO_BLASTX}='/srv/www/data/blastp';
$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_all';
$ENV{AMIGO_TERM2TERM_METADATA_LOADED}='0';
$ENV{AMIGO_TERM_REGEXP}='all|GO\:[0-9]{7}';
$ENV{AMIGO_GO_ONLY_GRAPHICS}='1';
$ENV{AMIGO_VERSION}='1.8';
$ENV{AMIGO_VERBOSE}='0';
$ENV{AMIGO_TROUBLE_SWITCH}='0';
$ENV{AMIGO_TROUBLE_MESSAGE}='<h2 style="text-align: center;">AmiGO is currently experiencing some difficulty.<br />You may want to temporarily try <a href="http://amigo.berkeleybop.org/cgi-bin/amigo/go.cgi" title="Go to AmiGO Labs">AmiGO Labs</a> instead.</h2>';
$ENV{AMIGO_BETA}='0';
$ENV{AMIGO_GOOGLE_ANALYTICS_ID}=;

refresh.pl

If you are going to use the fast search services, items from the Reference Genome project, or clean the cruft of user sessions and temporary files generated by AmiGO automatically, you'll need to get familiar with this script.

It's simplest, longest running usage (no kidding--we're talking hours here), and comprehensive usage is:

./refresh.pl

Please see the main wiki documentation and refresh.pl's documentation for more information.

Cruft Removal

This script can also be used to remove the files that build up in AmiGO's various directories over time. As a concrete example, here is how it's called on a testing server:

0 0,4,8,12,16,20 * * * cd /home/sjcarbon/local/src/svn/geneontology/go-dev/amigo; perl refresh.pl -r

Google Analytics

Optionally, to enable Google Analyics in your AmiGO installation, edit the config.pl line below and reinstall.

$ENV{AMIGO_GOOGLE_ANALYTICS_ID}='UA-XXXXXXX-X';

Done

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

Maintenance and Upgrading

These are topics outside the focus of this manual. Please see the main wiki documentation.

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!

Appendices

Full Detected Libraries from version.pl

5.003
5.008
5.6.0
5.8.0
CGI
CGI::Application
CGI::Application::Plugin::Redirect
CGI::Application::Plugin::Session
CGI::Application::Plugin::TT
CGI::Carp
Carp
Config
Cwd
DBD::SQLite
DBI
DBIx::Class
DBIx::Class::Schema
Data::Dumper
Data::Dumper;
Data::FormValidator
Data::UUID
Date::Format
Digest::MD5
Digest::SHA
DirHandle
DynaLoader
Exporter
ExtUtils::MakeMaker
File::Basename
File::Find
File::Path
File::Slurp
File::Temp
File::stat
FileHandle
FreezeThaw
GO::TermFinder
GOBO::DBIC::GODBModel
GOBO::DBIC::GODBModel::Graph
GOBO::DBIC::GODBModel::Modify
GOBO::DBIC::GODBModel::Query
GOBO::DBIC::GODBModel::Schema
Getopt::Long
Getopt::Std
Graph::Directed
Graph::TransitiveClosure
GraphViz
HTML::Entities
HTTP::Cookies
HTTP::Request
IO::File
IO::Scalar
IO::Socket
IO::Uncompress::AnyUncompress
JSON
JSON::PP
LWP::Simple
LWP::UserAgent
List::Util
Lucene
Math::BigInt
Math::Trig
Memoize
POSIX
Pod::Usage
Storable
Template
Template::Constants
Term::ReadLine
Test
Test::More
Test::WWW::Mechanize::CGIApp
Text::Balanced
Text::Wrap
Time::HiRes
Time::localtime
URI::Escape
WWW::Mechanize
XML::Writer
XML::XPath
YAML
diagnostics
warnings

Full Detected Libraries from simulate.pl

AutoLoader
B::Deparse
CGI
CGI::Application
CGI::Application::Plugin::Redirect
CGI::Application::Plugin::Session
CGI::Application::Plugin::TT
CGI::Carp
CGI::Session
CGI::Session::ErrorHandler
CGI::Util
Carp
Carp::Assert
Carp::Assert::More
Carp::Clan
Carp::Heavy
Class::Accessor
Class::Accessor::Chained::Fast
Class::Accessor::Fast
Class::Accessor::Grouped
Class::C3
Class::C3::Componentised
Class::ISA
Class::Inspector
Class::Struct
Class::XSAccessor
Class::XSAccessor::Heavy
Compress::Raw::Zlib
Compress::Zlib
Config
Cwd
DBD::SQLite
DBI
DBIx::Class
DBIx::Class::Core
DBIx::Class::Exception
DBIx::Class::InflateColumn
DBIx::Class::PK
DBIx::Class::PK::Auto
DBIx::Class::Relationship
DBIx::Class::Relationship::Accessor
DBIx::Class::Relationship::Base
DBIx::Class::Relationship::BelongsTo
DBIx::Class::Relationship::CascadeActions
DBIx::Class::Relationship::HasMany
DBIx::Class::Relationship::HasOne
DBIx::Class::Relationship::Helpers
DBIx::Class::Relationship::ManyToMany
DBIx::Class::Relationship::ProxyMethods
DBIx::Class::ResultSet
DBIx::Class::ResultSetColumn
DBIx::Class::ResultSource
DBIx::Class::ResultSource::Table
DBIx::Class::ResultSourceHandle
DBIx::Class::ResultSourceProxy
DBIx::Class::ResultSourceProxy::Table
DBIx::Class::Row
DBIx::Class::Schema
DBIx::Class::StartupCheck
Data::Dumper
Data::FormValidator
Data::FormValidator::Constraints
Data::FormValidator::Filters
Data::FormValidator::Results
Data::Page
Data::UUID
Date::Format
Digest::SHA
Digest::base
DirHandle
DynaLoader
Encode
Encode::Alias
Encode::Config
Encode::Encoding
Errno
Exporter
Exporter::Heavy
Fcntl
File::Basename
File::Find
File::Glob
File::GlobMapper
File::Path
File::Slurp
File::Spec
File::Spec::Unix
File::Temp
File::stat
FileHandle
FreezeThaw
GO::TermFinder
Getopt::Std
Graph
Graph::AdjacencyMap
Graph::AdjacencyMap::Heavy
Graph::AdjacencyMap::Light
Graph::AdjacencyMap::Vertex
Graph::AdjacencyMatrix
Graph::Attribute
Graph::BitMatrix
Graph::Directed
Graph::MSTHeapElem
Graph::Matrix
Graph::SPTHeapElem
Graph::TransitiveClosure
Graph::TransitiveClosure::Matrix
Graph::Traversal
Graph::Traversal::DFS
Graph::Undirected
Graph::UnionFind
GraphViz
HTML::Entities
HTML::Form
HTML::Highlight
HTML::Parser
HTML::PullParser
HTML::Tagset
HTML::TokeParser
HTTP::Date
HTTP::Headers
HTTP::Message
HTTP::Request
HTTP::Request::AsCGI
HTTP::Response
HTTP::Status
Heap071::Elem
Heap071::Fibonacci
IO
IO::Compress::Adapter::Deflate
IO::Compress::Base
IO::Compress::Base::Common
IO::Compress::Gzip
IO::Compress::Gzip::Constants
IO::Compress::RawDeflate
IO::Compress::Zlib::Extra
IO::File
IO::Handle
IO::Scalar
IO::Seekable
IO::Uncompress::Adapter::Inflate
IO::Uncompress::Base
IO::Uncompress::Gunzip
IO::Uncompress::RawInflate
IO::WrapTie
IPC::Run
IPC::Run::Debug
IPC::Run::IO
IPC::Run::Timer
JSON
JSON::PP
JSON::PP58
LWP
LWP::MemberMixin
LWP::Protocol
LWP::UserAgent
List::Util
Lucene
MIME::Base64
MRO::Compat
Math::BigInt
Math::BigInt::Calc
Math::BigInt::FastCalc
Math::Complex
Math::Trig
Module::Find
OSSP::uuid
Opcode
POSIX
Perl6::Junction
Perl6::Junction::All
Perl6::Junction::Any
Perl6::Junction::Base
Perl6::Junction::None
Perl6::Junction::One
Safe
Scalar::Util
SelectSaver
Storable
Sub::Name
Symbol
Template
Template::Base
Template::Config
Template::Constants
Template::Document
Template::Exception
Template::Provider
Template::Service
Test::Builder
Test::LongString
Test::WWW::Mechanize
Test::WWW::Mechanize::CGIApp
Tie::Hash
Tie::Scalar
Time::HiRes
Time::Local
Time::Zone
Time::localtime
Time::tm
UNIVERSAL
URI
URI::Escape
WWW::Mechanize
XML::Parser
XML::Parser::Expat
XML::XPath
XML::XPath::Boolean
XML::XPath::Expr
XML::XPath::Function
XML::XPath::Literal
XML::XPath::LocationPath
XML::XPath::Node
XML::XPath::Node::Attribute
XML::XPath::Node::Comment
XML::XPath::Node::Element
XML::XPath::Node::Namespace
XML::XPath::Node::PI
XML::XPath::Node::Text
XML::XPath::NodeSet
XML::XPath::Number
XML::XPath::Parser
XML::XPath::Root
XML::XPath::Step
XML::XPath::Variable
XML::XPath::XMLParser
XSLoader