Chimera Web Services at RBVI

The ​RBVI hosts several web services used by Chimera, eg ​blast against ​PDB and fetching mmCIF ​chemical component dictionaries that were not distributed as part of Chimera. These web services are built on top of the ​Opal Toolkit and hosted on the RBVI cluster plato.cgl.ucsf.edu.

Opal Setup

When we started providing these web services with Chimera 1.4, we started with ​Opal 1.9.5 running on top of Tomcat 5.0.30 that we obtained from the Opal web site. With Chimera 1.5, we moved to ​Opal 2.2 (still on Tomcat 5.0.30). However, since Chimera 1.4 is still out in the field, Opal 1.9.5 services are still available.

Setting up Opal is very straightforward. The documentation in the ​Opal Toolkit Reference Guide are excellent, and the Opal developers are very helpful. The step-by-step instructions in the guide works perfectly. The only pitfall to avoid is installing from a different user account (eg root) than the account used for executing the Tomcat server (eg apache); the Tomcat server needs to be able to write into the Opal directories created during installation.

We wanted to make our web services available on the standard HTTP port (80) at web address webservices.rbvi.ucsf.edu. On the plato cluster, we use the Apache web server to provide service for a number of virtual web hosts, including webservices.rbvi.ucsf.edu. However, since Apache already uses the standard HTTP port, the Tomcat server must listen on a different port (8080). Fortunately, we can use ​mod_jk to connect HTTP requests to the Tomcat server. Unfortunately, Opal only knows about the Tomcat server and returns URLs that include the non-HTTP Tomcat port; so we need to investigate how to make Opal use a different URL prefix than its Tomcat URL.

All these servers (Opal, Tomcat, Apache) are hosted on plato.cgl.ucsf.edu. The installation directories for Opal are /usr/local/opal1 and /usr/local/opal2 (which are actually symbolic links to directories with full version numbers). The installation directory for Tomcat is /usr/local/tomcat (which is also a symbolic link). The configuration file for webservices.rbvi.ucsf.edu is /usr/local/www/webservices-conf.d/VirtualHosts/webservices.conf.

Web Services Setup

The Opal configuration files for the RBVI web services are in /usr/local/opal-local/configs. Currently, we have

• blastprotein_config.xml - used by Blast Protein tool
• ccd_config.xml - used by mmCIF molecule connectivity generator
• saxs_config.xml - used by Small-Angle X-Ray Profile tool
• blastpdb_config.xml - used by very old Blast PDB tool that is no longer distributed

These configuration files refer to executables. Some are custom-made for Chimera (eg blastprotein.py) and are located in /usr/local/opal-local/bin; others are experimental tools located in developers' directories (eg the SAXS profile program). These web service files were kept separate from the standard Opal distribution to make upgrading Opal software easier.

In /usr/local/opal-local, there are files named deploy_X.Y and undeploy_X.Y. These are shell scripts for managing the RBVI web services on an running Opal installation. The X.Y refer to the target Opal version. These scripts should not be version specific. However, the service naming we used for Opal 1.9.5 left much to be desired due to some misconception early on. When we moved to Opal 2.2, we updated the service names to make them more logical and consistent. Note that the web service names that clients use (eg BlastProteinService) are actually defined in the deploy scripts, not in the appName attributes in the configuration files.

Adding a New Web Service

Deploying and undeploying new web services is fairly straightforward. Below is an example of how to deploy the SAXS service. For a new service, the string "saxs" (in upper or lower case) should be replaced with the name of the new service. For this discussion, we will use Opal 2 and ignore Opal 1.9.5 since that is a legacy service.

To deploy a service, the first step is to construct an Opal web service configuration file. We started with /usr/local/opal2/configs/pdb2pqr_config.xml and modified it for our SAXS profile program. We install the resulting sax_config.xml file into the RBVI web service configuration directory:

cp saxs_config.xml /usr/local/opal-local/configs

(/usr/local/opal-local is writable by group staff. If you are not in group staff, you will need to make arrangements with RBVI staff.)

For the SAXS web service, we are using an existing executable program (which is referenced in the configuration file), so we do not need to write anything else. If the new service requires special handling of parameters, or consists of running several programs instead of just one, you will need to write a handler program or script that is invoked by Opal. The program or script should be installed in /usr/local/opal-local/bin.

Once the Opal configuration file and handler program are in place, we install the service with:

audit opal2 deploy -DserviceName=SAXSService -DappConfig=/usr/local/opal-local/configs/saxs_config.xml

This command will generate some output from which you should be able to tell whether it worked or not.

If you want to disable an Opal service, you can undeploy it with something like:

audit opal2 undeploy -DserviceName=SAXSService

Finally, we edit the deploy and undeploy scripts to include the new service so that it will be reinstalled when we upgrade Opal.

These steps work most of the time. Every once in a while, the entire web service server stops working. For example, you might no longer be able to connect to the Opal Dashboard. If that happens, the entire "WebServices" service on plato needs to be restarted. Contact RBVI staff and they can restart the service. The command for restarting the service is:

clusvcadm -d WebServices
clusvcadm -e WebServices

After deploying the service, it will appear in the ​Opal Dashboard.