Installing BioQuery on a custom server.

Overview

BioQuery is a client-server application in which the GUI runs on each user's computer, but file storage and automated Query submissions are made from a central server. Some organizations may want to host the BioQuery application locally for their own private use. This can provide advantages such as lower traffic, improved server performance, increased security of user files, or exclusive intranet access. The BioQuery application can be installed at no cost.

This document describes the installation of the BioQuery application onto a server for access by multiple users. This does not explain how to install and use the user-interface for an individual user. If you are user trying to install the BioQuery application on a client, please see Download BioQuery.

To run the BioQuery app from your own server you must have a java-capable web container installed that can run servlets (such as Tomcat 3.2 or above). You will need to create a bioquery directory under webapps and create a Tomcat context that maps a URL to the bioquery directory. Instructions can be found at:
Jakarta-Tomcat
OOP-Research

Required Components

The server portion contains these parts:

A set of 5 .class files (Servlets and supporting classes).
A set of 7 jar files (BioQuery app and utilities)
File web.xml
File querys.xml

The files can be placed on the server like this:


    webapps
       |____bioquery
               |____WEB-INF
                       |____web.xml
                       |
                       |____classes
                       |      |____AccountFileManger.class
                       |      |____AutoSubmitEngine.class
                       |      |____FileManagerServlet.class
                       |      |____ServerLog.class
                       |      |____UpdateServlet.class
                       |
                       |____lib
                              |____bioquery.jar
                              |____synaptocode.jar
                              |____update.jar
                              |____activation.jar
                              |____mailapi.jar
                              |____jdom.jar
                              |____xerces.jar

querys.xml goes in a special location described below

The server application is not packaged into a WAR file to facilitate modifications to the web.xml file, which are described below. Administrators can package the entire directory into a WAR file for deployment if they wish.

All of these files are available as a zip file at the end of this page. The files will be packaged as shown above starting with the bioquery dir, that is, unpack them into the webapps dir.

Installion Instructions

Download the zip file from the bottom of this page.
Unpack the contents directly into the webapps directory of your server. This should create a bioquery directory under your webapps directory.
Modify the server.xml file for your servlet engine to map a URL to the bioquery directory, and to set the docBase="webapps/bioquery"
Create a 'bioquery-users' directory. You can name this whatever you want and place it anywhere where the server classes will have access to it if they have it's absolute directory path.
Set permissions on the bioquery-users directory so that it cannot be accessed directly over the web. Only the AccountFileManager.class should access this directory.
Open the web.xml file and add the path locations to the bioquery-users and the bioquery->WEB-INF->lib directories. You may also need to adjust the url-mapping to ensure your server can find the Servlets. See Changes to web.xml below.
Test the Servlets by entering the FileManagerServlet address into a web browser on a client machine, i.e.: http://www.mydomain.com/bioquery/FileManagerServlet
You should get back a message like this:
The BioQuery FileManagerServlet This servlet is intended to be used by the BioQuery application only. Please visit www.bioquery.org to learn how to use this program.
Download the installation program for your users from www.bioquery.org/download
Install the program on a client machine.
Modify the bq.xml file on the Client machine to point to the address of your FileManagerServlet. The program is distributed with this file pointing to bioquery.org's server, so unless this file is modified, the client will connect to the wrong server. The file must be modified for every client. See Modifying bq.xml below.
Test the client by creating a new account. Confirm this worked on your server (not ours) by making sure a subdirectory under bioquery-users was created with the username of the account.

That's it. The program should now work.

Details and Troubleshooting

Location of querys.xml

The file querys.xml goes in a special location and is thus distributed separately within the querys-config.zip file. It belongs in the the META-INF directory in the base directory of the virtual machine. Where this is varies depending on how your servlet container is configured. It may be in the webapps directory, or in a bin directory. There is an easy way to find this directory: the BioQuery servlets log activity in this same directory in the file bioquery.log. The easiest way to install the querys.xml file is to do this:

Make sure the FileManagerServlet is installed correctly, and that you can have successfully contacted it from your web browser.
Search for the file bioquery.log in your webapps, bin, and jakarta-tomcat (or other servlet container) directories.
Unpack the file querys-config.zip into the same directory as bioquery.log.

Your should have a directory structure something like this:


    bin
     |____bioquery.log
     |
     |____META-INF
              |____querys.xml

querys.xml is now in place and ready to go.

querys.xml is located external to the program to allow developers to add new databases to the code without recompiling, as documented here

If querys.xml is in the wrong location and bioquery cannot find it, the AutoSubmitEngine will not work correctly (and will log some exceptions in bioquery.log). It may take some time to see the first problem, so be aware that until the first automatic update comes through, the AutoSubmitEngine may not be working correctly. To help test it, finish your installation and run the client application. Create a new account, and create and save a new Search that retrieves many results (such as 'rna[ALL]'). Turn on the Auto-Update feature and have the results e-mailed to you every day. If it works, there should be an email waiting for you the next day. If it did not work, there should be an exception logged in bioquery.log.

Modifying bq.xml for each client

The file bq.xml is installed on the client under the bioquery->META-INF directory as shown:


    bioquery
       |____META-INF
                |____bq.xml
                |____querys.xml

The easiest way to change it for every client is to modify and test it up front, then save the working copy as a template. Have users install the program, and then run a simple script or batch file that overwrites the original bq.xml with your modified template.

There is only one line you must change in bq.xml: The FileManagerServlet address.
Here is what the installed file looks like:


<BioQueryProperties>
    <ServletAddresses>
        <FileManagerServlet address="http://www.bioquery.org/servlet/FileManagerServlet" />
        <UpdateServlet      address="http://www.bioquery.org/servlet/UpdateServlet"      />
    </ServletAddresses>

The address you want to enter is the same address that your tests show finds your copy of the FileManagerServet when entered into a standard web browser.

You may or may not want to change the UpdateServlet address, see below:

Do I use the UpdateServlet?

The UpdateServlet is what allows the BioQuery client application to check for updated versions of itself and download them upon startup. This may or may not be desirable.

If the UpdateServlet address points to OUR server (http://www.bioquery.org/servlet/UpdateServlet) your users can download upgrades and bug fixes when we make them. Your users have the latest version, fewer bugs, and little effort for you. However, there is a chance that an upgrade on the client side without an upgrade on the server side might cause problems (such as a new Query type that works on the client, but the update service on the server does not know about).

If you change the UpdateServlet address to point to YOUR server, then your users can only receive upgrades if YOU make them. This stabilizes the program so that your server version is the same as your client version. If you do this you can make your own changes to the program, or (more likely) download periodic upgrades from us to your server, which will then become available to your clients.

Changes to web.xml

The web.xml file contains information about the 2 servlets: the FileManagerServlet and the UpdateServlet. The only parameters you need to change are the <init-param><param-value> and possibly the <servlet-mapping><url-pattern>.

Change the <init-param><param-value> of the FileManagerServlet to the absolute path to the bioquery-users directory.

Change the <init-param><param-value> of the UpdateServlet to the absolute path to the WEB-INF/lib directory. This is not necessary if you are not using the UpdateServlet, but it will have no effect unless a client's bq.xml file is also set to point at this Servlet.

The <servlet-mapping><url-pattern> is probably ok, but this depends on your servlet container, the context settings and docBase in your container configuration file (server.xml in Tomcat). Ultimately the container's context settings combine with the url-pattern to determine the URL to these servlets. They are easy to test: simply put the URL to the servlet (such as: http://www.mydomain.com/bioquery/FileManagerServlet) into a web browser and see if it finds it. Depending on your container settings, you may or may not have to restart the container each time you change an setting (hopefully not!).

When you have an address that can find the Servlets from a web browser, put that SAME address into each client's bq.xml file.

API for BioQuery server classes

The API for all of the server classes is available here

Download the BioQuery Servlets

Click here:
Download BioQuery Server Files.

Developer Guide.

BioQuery Home.