N-Browse Installation & Interaction Data

From WormBaseWiki
Revision as of 14:54, 21 May 2008 by Tharris (talk | contribs)
Jump to navigationJump to search

N-Browse (http://www.gnetbrowse.org ) is a Java-based interaction viewer developed by Huey-Ling Kao at Kris Gunsalus' group at NYU. This tool is used by Wormbase to display Wormbase interaction data.

The application does not have an automated installer at this time and is installed manually. After it is installed, Wormbase interaction data needs to be dumped from AceDB and loaded to MySQL. Finally, the data in the MySQL database needs to be processed to be used by N-Browse.

N-Browse was provided to Wormbase in multiple packages along with documentation. Some patches were provided and changes were made to the code along the way. The original packages that were provided to Wormbase are archived in the following location.


Please refer to the following README file for installation instructions by Huey-Ling Kao.


The components we use for Wormbase are re-arranged and placed in the following location. This directory contains 4 components. Out of these 4 components, 3 of them need to be customized for the site where the application will be installed. These directories contain a directory for dev.wormbase.org, a directory for gene.wormbase.org and a directory for the original source code. You can "diff" directory pairs for identifying config information. Based on the original installation instructions, the following discussion describes the components of N-Browse in the context of the Wormbase installation.

brie3:/usr/local/wormbase/util/import_export/nbrowse/current_source/ (this package is referred to as $SOURCE in this document)

There are Wormbase-specific scripts to dump and format the Wormbase interaction data, developed per descriptions from the N-Browse team. These scripts are described later in the document.


The current form of the N-Browse installation on Wormbase and necessary components are described below. For components that require compilation, note the simple shell scripts named “_build.sh” where commands for Wormbase servers are placed.

N-Browse is installed on brie3 and gene.wormbase.org. On both of these installations, Tomcat runs on port 9022. When configuring the application, Tomcat links should be pointed to dev.wormbase.org:9022 for the brie3 version and www.wormbase.org for the gene.wormbase.org version. Note that the port number is not required for gene.wormbase.org version and the URL points to www.wormbase.org as the request is redirected by squid.

1) Java SDK 1.4.2 or 1.5, Tomcat 5 and MySQL 5 are required:

Installation notes:


  • Installed in: /usr/local/jakarta-tomcat-5.0.28
  • Symlinked from: /usr/local/tomcat
  • You can download Tomcat from http://tomcat.apache.org/ (5.X versions archived at http://archive.apache.org/dist/tomcat/tomcat-5/). The binary package is a tarball which can simply be unpacked into the directory.
  • Startup script: $TOMCAT/bin/startup.sh
  • Shutdown script: $TOMCATbin/shutdown.sh
  • $TOMCAT/webapps is the directory where all the web projects are located (somewhat equivalent of a document root in Apache, but webapps contains multiple web projects, each project stored in a separate directory. For Wormbase, a symlink within this directory points to the Wormbase N-Browse installation, which is located in the Wormbase root directory (details on this later in the document).
  • To startup/shutdown Tomcat, JAVA_HOME environment variable that points to the JDK installation must be defined (JDK installation described in the next section).


  • Installed in: /opt/jdk1.5.0_09 (gene.wormbase.org), /usr/local/jdk1.5.0_09/ (brie3)
  • Symlinked from: /usr/local/tomcat
  • JDK stands for the Java Development Kit, contains JRE (Java Runtime Environment) and additional development tools. The package we have contains Netbeans, a Java IDE, which is not required).
  • JDK comes with an automated installer, /opt is the default location.
  • Version 5 (1.5) archived at http://java.sun.com/javase/downloads/index_jdk5.jsp.

2) Tomcat web project (JSP) component:

The source for this component are stored in: $SOURCE/nbrowse_t (dev and gene versions)
  • On the server, installed in: $WORMBASE/tomcat/webapps/nbrowse_t/
  • This is symlinked from: $TOMCAT/webapps.
  • If you need to change the MySQL database or server that the application runs on, the following parameters need to be changed and the WEB-INF/classes/* Java files need to recompiled.
    • /WEB-INF/classes/databaseProcess/Database_Connection.java (port number, database, user, password)
    • /WEB-INF/classes/databaseProcess/Schema.java (server location)
  • Note the $SOURCE/nbrowse_t/nbrowse_t.*/WEB-INF/classes/_build.sh file.

3) Java Applet component:

The source for this component: $SOURCE/source_ws (dev and gene versions)
  • This component is prepared as a jar file, the jar file is moved into the Tomcat web project directory.
  • You need to:
    • customize local_config file with the server name
    • compile Java files
    • package Java classes and local_config into a jar file named "gNetBrowser.jar"
    • sign the jar file
    • move the jar file into webapps/nbrowse_t/ directory
  • Note the $SOURCE/source_ws/source_ws.*/_build.sh file.

4) Apache/cgi-perl component:

The source for this component: $SOURCE/nbrowse (dev and gene versions)

5) Database component:

N-Browse uses a MySQL database. The database needs to be readable and writable by the user specified in the config files.

The code base for setting up the Wormbase MySQL database: $WORMBASE/util/import_export/nbrowse/
  • dump_interaction_data.pl: Dumps interaction data from Wormbase as an XML file
  • process_interactions.pl: Processes the XML file and generates a mysqldump
  • nbrowse_template.sql: Template used by process_interactions.pl
  • nbrowse_wormbase_db.sql: MySQL schema

Steps to build a new Wormbase interaction database:

  • Use dump_interaction_data.pl to dump interaction data as an XML file (run script with no params for usage info).

./dump_interaction_data.pl WS190-nbrowse.xml brie3.cshl.org 2005

  • Use process_interactions.pl to generate a mysqldump from the XML file (run script with no params for usage info).

./process_interactions.pl WS190-nbrowse.xml > WS190-nbrowse.sql

  • Create schema in database (nbrowse_wormbase_db.sql).

  • Load the mysqldump into MySQL.

mysql -u root -p < WS190-nbrowse.sql

  • Process the MySQL database to prepare it for use by N-Browse (see next component).

5) Database processing component:

The source for this component: $SOURCE/process_db (one version only)
  • Update databaseProcess/Database_Connection.java with the database access params and compile it.
  • Run classes/databaseProcess/LoadGNBGenericInteractionAll
  • Note the $SOURCE/process_db/classes/_build.sh file.
  • Preferably load the database with a release id and symnlink from the nbrowse_wormbase database. However, you will need to load and process the database in the server that it is installed in (versus making a mysqldump and sourcing it).