License|Download
|Requirements|Installation

Before continuing, please make sure the hardware, software, and configuration requirements have been met.

Cluster-side Installation

In this guide, we will call the collection of OGE compute nodes, the “cluster”.

Setting up the environment

On a cluster node, select a directory with the following two requirements:

  1. it must be visible to the whole cluster
  2. it must be accessible via password-free SSH from the webserver machine

This directory is referred as CLUSTER_HOME in this guide.

Create the following two directories in the CLUSTER_HOME:

  • mkdir ${CLUSTER_HOME}/GOBYWEB_SGE_JOBS
  • mkdir ${CLUSTER_HOME}/GOBYWEB_FILES

Here, you can decide if GOBYWEB_FILES should have Fanouts (Fanouts are defined in the ClusterNodeConfig.groovy configuration file, see below). Fanouts are a mechanism to help store data on systems that must aggregate multiple filesystems to provide the needed storage capacity.

Webserver-side Installation

Extract the web application, make directories

Extract the gobyweb binary distribution in the home directory of a selected account (we refer this directory as WEBSERVER_HOME in this guide):

  • cd ${WEBSERVER_HOME}
  • tar zxvf gobyweb-VERSION-webapp.tar.gz

Then, Create the required webserver-side directories using the commands:

  • cd ${WEBSERVER_HOME}
  • mkdir GOBYWEB_FILES
  • mkdir GOBYWEB_RESULTS
  • mkdir GOBYWEB_UPLOADS
  • mkdir GOBYWEB_UPLOAD_STAGING
  • mkdir QUEUE_MESSAGES

Here, you can decide if GOBYWEB_RESULTS should have Fanouts (created Fanouts have to be defined in the WebAppConfig-production.groovy, see below).

At this point, the files in the WEBSERVER_HOME should look as follows:

WEBSERVER_HOME/
     GOBYWEB_FILES/
     GOBYWEB_RESULTS/
     GOBYWEB_UPLOADS/
     GOBYWEB_UPLOAD_STAGING/
     QUEUE_MESSAGES/
     webapp/
       gobyweb_home/
          gobyweb-cmd.sh
          accounting/
          logs/
          conf/
              WebAppConfig.groovy-template
              DataSource.groovy-template
              ClusterNodeConfig.groovy
              GrailsPluginsConfig.groovy
              LoggersConfig.groovy
              MigrationMappings.groovy
              OrganismConfig.groovy
              server.xml
              tomcat-users.xml
              web.xml
          webapps/
               ROOT/
                    index.thml
               gobyweb.war

Installing Tomcat

Download the latest version of Apache Tomcat 7.0.x from  http://tomcat.apache.org/download-70.cgi to the WEBSERVER_HOME directory on the web server then extract its contents:

  • cd ${WEBSERVER_HOME}
  • tar zxvf apache-tomcat-7.0.xx.tar.gz

To make upgrading to new versions of Apache Tomcat easier, GobyWeb does not use the “webapps” or “conf” directories within the WEBSERVER_HOME/apache-tomcat directory. Instead, GobyWeb uses WEBSERVER_HOME/webapp/gobyweb_home/webapps/ and WEBSERVER_HOME/webapp/gobyweb_home/conf/.

Configure GobyWeb

The GobyWeb configuration files are:

${WEBSERVER_HOME}/webapp/gobyweb_home/conf/WebAppConfig-production.groovy

${WEBSERVER_HOME}/webapp/gobyweb_home/conf/DataSource.groovy

${WEBSERVER_HOME}/webapp/gobyweb_home/conf/ClusterNodeConfig.groovy

WebAppConfigConfig-production.groovy configures application options, directories, etc. on the webserver machine.

DataSource.groovy configures how to connect to your database.

ClusterNodeConfig.groovy provides a description of the CLUSTER_HOME. If you followed the instructions in this guide you should not need to modify this file.

For the first two of these configuration files, we have provided “-template” versions that contain documentation describing the configuration options. Templates have to be renamed with their definitive name by executing:

  • mv WebAppConfig.groovy-template WebAppConfig-production.groovy
  • mv DataSource.groovy-template DataSource

These files are written in Groovy. Groovy is a JVM-based language that is very similar to Java. Please note that you shouldn’t need any Groovy experience to edit these files if you follow the syntax. You can learn more about Groovy at

http://groovy.codehaus.org/
http://groovy.codehaus.org/Beginners+Tutorial

If you intend to use a database server other than Oracle (this is not recommended because mostly untested), you will need to install that database servers jdbc .jar file. This jar file should be placed in

WEBSERVER_HOME/webapp/gobyweb_home/lib/

Configure Tomcat

To configure the instance of Apache Tomcat, you need to edit the following files:

${WEBSERVER_HOME}/webapp/gobyweb_home/conf/server.xml
${WEBSERVER_HOME}/webapp/gobyweb_home/conf/tomcat-users.xml

The server.xml that comes with the GobyWeb distribution specifies that GobyWeb will run on port 8080. Change this port to any port number suitable for your local network, such as the standard port 80 that is used by most web servers.

As far as GobyWeb is concerned, there is very little that needs to be different from a “stock” Tomcat server.xml file, so you may prefer to use the server.xml that comes from the Tomcat distribution. One possible exception is the line

 <Host name=”localhost”  appBase=”webapps”
unpackWARs=”true” autoDeploy=”true” reloadable=”true”>

This line specifies the location of this instances ROOT directory, which in the GobyWeb distribution, contains the single file index.html. This file ensures that if a user visits

http://your_server/

they will be redirected to the running GobyWeb application at

http://your_server/gobyweb

The last file you need to edit is WEBSERVER_HOME/gobyweb_home/webapp/gobyweb-cmd.sh. Look for the line

CATALINA_HOME=${WEBSERVER_HOME}/Library/apache-tomcat-7.0.33/

and edit it so it points to the directory where you installed Tomcat.

GobyWeb Plugins

Starting with version 1.7, GobyWeb supports a plugin architecture. The main benefit of plugins are that they enable you to support additional aligners and analysis packages without having to edit the GobyWeb application. Additionally, the plugin architecture also allows you to add or edit plugins without having to completely restart the GobyWeb application.

GobyWeb supports five kinds of plugins: tasks, filesets, aligners, analyses, and resources. Please, refer to the Plugins SDK section for an overview of these plugins and for how to create your own plugins.

Starting from version 2.1, GobyWeb supports resources with artifacts installation. Previously, each resource plugin had to include all the executables (already pre-built) it was relying on. With artifacts, each resource can download and build such executable(s) on the specific local platform. Moreover, artifacts are cached and reused across resources and job executions. Again, visit the Plugins SDK pages for further details on artifacts.

We’ve provided several sample plugins. Plugin source code and updates can be obtained from GitHub. To use these plugins, clone the repository in your local machine and configure the setting gobyweb.webPluginsRootDir in WebAppConfigConfig-production.groovy file with the absolute location of the folder where the repository has been cloned. The structure of the plugins root folder has to look as follows:

 plugins/
      [GobyWeb provided/sample plugin directories and files here]
 schemas/
     *.xsd

The Git repository also contains few executables pre-built for our system (bound to plugin resources created before the artifacts mechanism). Please note that we cannot guarantee that these executables will function correctly on different servers.

If you develop a new GobyWeb plugin, please consider contributing this plugin to the community (fork the GitHub repository, commit your plugin there and make a pull request to let us know you would like to contribute new code).

Starting and monitoring GobyWeb

To start GobyWeb, execute the following:

  • cd ${WEBSERVER_HOME}/webapp/gobyweb_home/
  • ./gobyweb-cmd.sh start

Once started, GobyWeb logs its activities in the following files:

  • ${WEBSERVER_HOME}/webapp/gobyweb_home/logs/gobyweb.out (daily rotated) records the web application’s activities and errors
  • ${WEBSERVER_HOME}/webapp/gobyweb_home/logs/plugins.out (daily rotated) records plugins initialization and errors
  • ${WEBSERVER_HOME}/webapp/gobyweb_home/accounting/logins.out records users’ logins
  • ${WEBSERVER_HOME}/webapp/gobyweb_home/logs/catalina.out (daily rotated) records Tomcat activities and some GobyWeb activities not yet migrated to Log4J
  • ${WEBSERVER_HOME}/webapp/gobyweb_home/logs/hibernate.out (daily rotated) records what hibernate is doing
  • ${WEBSERVER_HOME}/webapp/gobyweb_home/logs/grailsframework.out (daily rotated) records what grails is doing

Settings related to these log files can be changed in LoggersConfig.groovy

If GobyWeb successfully starts, you should see a message like the following in gobyweb.out:

2013-05-09 12:44:33,074 [localhost-startStop-1] INFO \
    services.GobyWebLifecycleService  - \
    GobyWeb successfully started at 09-May-13 12:44:33. \
    Access to http://gobywebtrial.apps.campagnelab.org/gobyweb

The message also indicates at which URL the application is available. The URL is built using the value assigned to the variable grails.serverURL in ${WEBSERVER_HOME}/webapp/gobyweb_home/conf/WebAppConfig-production.groovy.

If something goes wrong and GobyWeb does not start properly, the listed log files must be searched for error messages.

Logging Into GobyWeb

To login into GobyWeb, open a web browser at the URL reported in gobyweb.out (see previous section). The first time you run a new instance of GobyWeb, an “administrator” account will be created. The default login for this account is

Username: admin
Password: icb

It is recommended that you change the default password immediately (you can do this from the Account tab in the deployed web application).

Congratulations on your installation. Take a look at our video tutorials to learn how to use the installation application.

Installing/changing plugins on the fly

After initial installation, you may find that you need to install a new plugin, or make a quick fix to an already installed plugin. Changing a plugin or installing a new plugin does not require an application restart. Simply adjust directories and files in the plugins directory, navigate to the About page of the running application. Users with the administrator role will see a button labeled “Reload plugin definitions” below the list of currently loaded plugins. Pressing this button will reload the plugins from disk and validate them again. Validation errors will be shown in the plugins.out log file, and plugins with errors will be disabled (GobyWeb continues to run if a plugin has errors when modified at runtime). Check that the plugin was loaded successfully by looking for the plugin name and version number in the list shown on the About page.

Stopping GobyWeb

To stop GobyWeb, execute the following

  • cd ${WEBSERVER_HOME}/webapp/gobyweb_home/
  • ./gobyweb-cmd.sh stop