Changes between Version 1 and Version 2 of WebServices

Timestamp:

Feb 10, 2010, 11:05:50 AM (16 years ago)

Author:

Conrad Huang

Comment:

--

WebServices

@@ -11 +11 @@
 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.
+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 ==
+== Web Services Setup ==
 
 The Opal configuration files for the RBVI web services are in /usr/local/opal-local/configs.  Currently, we have
@@ -25 +25 @@
 
 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
+}}}