=== Chimera Web Services at RBVI ===

The [http://rbvi.ucsf.edu RBVI] hosts several web services used by Chimera, eg [http://www.ncbi.nlm.nih.gov/bookshelf/br.fcgi?book=handbook&part=ch16 blast] against [http://www.rcsb.org PDB] and fetching mmCIF [http://www.wwpdb.org/ccd.html chemical component dictionaries] that were not distributed as part of Chimera.  These web services are built on top of the [http://www.nbcr.net/software/opal/ 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 [http://webservices.cgl.ucsf.edu/opal/ 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 [http://webservices.cgl.ucsf.edu/opal2/ 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 [http://www.nbcr.net/software/opal/docs/2.X/index.html 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 [http://tomcat.apache.org/connectors-doc/ 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/opal-ws-1.9.5 and /usr/local/opal-ws-2.2.  The installation directory for Tomcat is /usr/local/tomcat (actually that's a symbolic link to /usr/local/jakarta-tomcat-5_0_30).  The configuration file for webservices.rbvi.ucsf.edu is /usr/local/www/webservices-conf.d/VirtualHosts/webservices.conf.

== Web Services ==

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.