This document is designed to help you get Ergatis up and running. For those of you who like to jump right in and do it yourself you can skip down the the quick install guide. For a more detailed explanation of the requirements, architecture, best practices, etc. read on.
Getting the requirements up and running will take far more time than actually setting up Ergatis
itself. This is a software package designed to allow users to easily build and manage pipelines
on a compute grid, after all, so actually
The Workflow Engine contains a test suite that allows you to ensure that you can successfully submit and track jobs on your grid. With these, a web server and perl modules in place you are ready to install Ergatis.
Ergatis is freely available under the open-source Artistic License and can be loaded from from the file release page on SourceForge. You'll notice several different packages available on that page and each are described below. Depending on your anticipated usage you may only need one of them.
If you just want the basic descriptions of the steps involved this is the section for you. If you want a detailed guide skip to the next section, 'detailed install'
The sections below provide more information and background.
A bit of planning can save you a lot of grief when you layout your directory structure. Most paths in Ergatis are configurable and most institutions usually find a directory convention that works for them. Here I'll describe the core directories you'll need to create with examples at the end of each description. As you read through the ergatis.ini file you'll find descriptions for all needed files, directories and parameters.
Using these example directories, we'll now go through an example install. If you've downloaded the current version from the SourceForge site you should have a tarball named like ergatis-v2rNbN.tar.gz where the Ns are some version numbers. From here on in the guide you'll need to replace this with the name of the file you downloaded. You should be able to extract it like this:
tar -xvzf ergatis-v2rNbN.tar.gz
This will create a directory called ergatis-v2rNbN. Change into that directory:
Here you should see several files and directories, among them the Makefile.PL. Using the directory examples above, we'll perform the install with these three commands:
/usr/local/bin/perl Makefile.PL INSTALL_BASE=/opt/ergatis make make install
Next you'll need to copy the interface files into your web server's directory structure. This involves one simple copy command. In this example I'm using apache and my html directory is under /var/www/ . From the same directory as we've executed the previous commands we'll now do:
cp htdocs /var/www/html/ergatis
This takes the htdocs directories within the package and moves them into place, renaming both 'ergatis' at the same time. You can name this directory anything or, optionally, place the files directory under your server root. Because the CGI scripts are also stored under the htdocs, you'll need to modify your apache configuration to allow execution of these scripts and to prevent some files within the system from being displayed.
<Directory "/var/www/html/ergatis"> Options +ExecCGI AllowOverride Limit DirectoryIndex index.html index.cgi AddHandler cgi-script .cgi <FilesMatch "\.ini"> Deny from all </FilesMatch> </Directory>
With the interface code now in place you'll want to edit the ergatis.ini file located at:
It is pretty heavily documented so you'll have information about every variable you need to set. Once finished you can point your browser to
Many components in Ergatis execute external binaries such as blastall, glimmer3, etc. that can be installed anywhere on your filesystem. You'll need to tell Ergatis where each of these are by editing the software.config file under your ergatis directory:
If you don't have access to some of these binaries or don't want them available you can edit the disabled component list in your ergatis.ini file. This will prevent that component from being available when users build a pipeline.
Before we proceed you should run the installation verification script, passing the ergatis.ini file you just configured. It performs a host of checks to ensure that the software is set up and configured correctly.
Now that you have the software and interface set up you're ready to create a project area. This will be where your pipelines and data are stored for any particular project. In our example we decided to creating a project area for the annotation of the E. coli, so we start by creating that directory:
You can then use the interface to create all the subdirectories and files necessary for a project area. Start by clicking the 'admin' tab followed by the 'create project' link. Next enter the project directory path in the text box. If there are any problems populating the area with the necessary files the interface will give a warning and allow you to try again until it's successful. Once the area is made you'll be prompted to edit the project's config file. Here you'll be able to specify which temp area and which ergatis directory you want to use (some sites have several.) Most of the options on this form should be filled out automatically for you based on the values in the ergatis.ini file. The only one you'll need to be sure to change is the first - the project abbreviation.
Once finished this will create the project are and all needed files and subdirectories. Currently, it will not add your new project to the global project list visible on the left side of the home page. Those are controlled by the entries at the bottom of the ergatis.ini file. You can add an entry for it there, else to go to your new project, enter the path (like /usr/local/projects/ecoli) into the text box at the bottom of the page labeled 'project area'.
The primary support mechanism is the mailing lists hosted by sourceforge. The link is found below and this should be the first place you write if you have problems. There are several developers watching that list to assist when necessary. If you find a bug or want to request a feature, please use the tracker link.