AmiGO Manual: Installation 1.7

From GO Wiki
Revision as of 12:23, 28 July 2009 by Sjcarbon (talk | contribs)

Jump to: navigation, search


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:

  • : 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.
  • : similar to (and a likely replacement of) 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.
  • : an installation script that asks questions about the user's environment and tries to catch the biggest errors that one can make during installation.
  • : 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 ( 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.


The most recent stable version of AmiGO should be available as part of the go-dev repository on the GO CVS site at

The sourceforge CVS repository can be found at: 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).


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/ Usage and examples are given by:

go-dev/go-db-perl/scripts/ -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/ -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/ -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 ; 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 :
  • 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 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/ .

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 ./ -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 ./ -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.


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.


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


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.

There is a script in go-dev/amigo called 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.

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

Once you have the software and requirements met, you just go to the amigo directory and type (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 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 "" file will be created in the same directory as during a successful installation run and is the basis for all future installation attempts after the first.

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

The "-i" option will ignore 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, 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 manually and rerunning with no arguments at all--by default, it will use whatever is in 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:


Example files

While you can construct a 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.


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_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. Useful for debugging.
  • AMIGO_BETA : Whether of not to make the experimental version of AmiGO visible (used with the -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 started

First, we'll install cvs and checkout the development repository.

sudo apt-get -u install cvs
cvs -z3 co -P go-dev

Next, using the

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 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.

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


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

cd go-dev/amigo

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:


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 would give a different set.

This method may be better for people upgrading their installation.


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:


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


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).

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 and 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 bioperl libgraph-perl sudo apt-get -u install libxml-xpath-perl libxml-writer-perl libxml-libxml-perl libxml-libxslt-perl

Next, we

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_amd64.deb 

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

Installation and final

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:

./ -v

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



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!