website/man_serverwar.html

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE html PUBLIC "XHTML 1.0 Strict"\r
   3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\r
   4 <html xmlns="http://www.w3.org/1999/xhtml">\r
   5 <head>\r
   6 <meta name="Last-modified" content="Mon, 4 Apr 2011 12:00:00 GMT"/>\r
   7 <title>Java Bioinformatics Analyses Web Services (JABAWS) Server Web Aplication aRchive manual</title>\r
   8 <link href="ws.css" rel="stylesheet" type="text/css" media=\r
   9 "screen, projection, handheld, tv" />\r
  10 <link rel="stylesheet" type="text/css" media="print" href=\r
  11 "print.css" />\r
  12 <script type="text/javascript" src="prototype-1.6.0.3.js"></script>\r
  13 </head>\r
  14 <body>\r
  15 <div id="page">\r
  16 <div id="banner">\r
  17 <table> \r
  18 <tr><td style="width:158px;"><a href="http://www.dundee.ac.uk"><img src="images/uod_lt_long.gif"  alt="University of Dundee" width="158" height="90" class="logo"  title="University of Dundee" longdesc="http://www.dundee.ac.uk"/></a></td>\r
  19 <td class="bg"><img src="images/jabaws2.png" alt="JABAWS-2.0" title="Java Bioinformatics Analysis Web Services version 2.0"/></td>\r
  20 <td class="bg"><img src="images/banner_right.png" alt="Disorder" width="200" height="80"/></td>\r
  21 </tr>\r
  22 </table>\r
  23 </div><!-- banner end-->\r
  24 \r
  25 <div id="wrapper">\r
  26 <div id="panel"><a href="index.html">Home</a> \r
  27          <a href="quick_start.html">Getting Started</a> \r
  28     <a class="selected" href="man_about.html">Manual</a> \r
  29         <div id="submenu">\r
  30                 <a href="man_about.html">About</a>\r
  31                 <a href="man_servervm.html" title="JABAWS Server as Virtual Appliance">Server VA</a>\r
  32                 <a href="man_awscloud.html" title="JABAWS Server in the Amazon EC2 Cloud">Server in the Cloud</a>\r
  33                 <a class="selected" href="man_serverwar.html" title="JABAWS Server as Web Application aRchive">Server WAR</a>\r
  34                 <a href="man_configuration.html" >Server<br/>\r
  35                 Configuration</a>\r
  36                 <a href="man_client.html" title="JABAWS Command Line Client">CMD Client</a>\r
  37                 <a href="man_stats.html" title="JABAWS Usage Statistics">Usage Statistics</a>\r
  38                 <a href="man_dev.html" title="Accessing JABAWS from your program">Accessing<br/>\r
  39                 JABAWS</a>      \r
  40                 <a href="man_server_dev.html" >JABAWS Development</a>\r
  41         </div>\r
  42 <a href="http://www.compbio.dundee.ac.uk/downloads/jabaws">Download</a> \r
  43 <a href="PublicAnnualStat" title="JABAWS server usage statistics">Usage Statistics</a>\r
  44  <a href="ServiceStatus" title="JABAWS webservices status. Click to test all web services. Please be patient while the services are being checked">Services Status</a>\r
  45 <a href="contacts.html">Contact Us</a>\r
  46 <a href="http://www.compbio.dundee.ac.uk" title="University of Dundee, The Barton Group" >Barton Group</a></div>\r
  47 \r
  48 <!-- panel end-->\r
  49 <div id="content">\r
  50 <h2 id="headtitle">JABAWS MANUAL</h2>\r
  51 \r
  52 <h2>JABAWS Server Web Application aRchive (WAR) </h2>\r
  53 <ul>\r
  54   <li><a href="#sysreq">System Requirements</a></li>\r
  55   <li><a href="#instwar">Installing the JABAWS WAR file</a></li>\r
  56   <li><a href="#prepexec">Preparing executables for use with JABAWS</a></li>\r
  57   <li><a href="#useprebin">Using the pre-compiled i386 binaries on Linux</a></li>\r
  58   <li><a href="#recompbinaries">Recompiling the bundled\r
  59     programs for your system</a></li>\r
  60   <li><a href="#haveexec">Reuse the binaries that are\r
  61     already in your system</a></li>\r
  62   <li><a href="#obtainexec">Obtaining command line binaries </a><a href="#obtainexec">for your operating system</a></li>\r
  63   <li><a href="#usingWsTester">Testing JABAWS Server</a></li>\r
  64   <li><a href="#diffcontexts">Running many JABAWS instances on the same server</a> </li>\r
  65   <li><a href="#nocluster">JABAWS on a single server</a></li>\r
  66   <li><a href="#clustsubsys">JABAWS supported cluster batch management systems </a></li>\r
  67   <li><a href="#tomstopundeploy">Manually deploying JABAWS application on Apache-Tomcat </a></li>\r
  68 </ul>\r
  69 <p><strong>Troubleshooting</strong></p>\r
  70 <ul>\r
  71   <li><a href="#tomdeploy">Apache-Tomcat fails to deploy the jabaws.war file</a></li>\r
  72   </ul>\r
  73 <h3><a name="sysreq" id="sysreq"></a>System Requirements</h3>\r
  74 <p>JABAWS requires a Java web application server compliant with\r
  75 version 2.4 of the Java Servlet specification, and a Java 6 runtime\r
  76 environment. We recommend using an official Oracle Java 6 runtime\r
  77 environment, and <a\r
  78 href="http://tomcat.apache.org/download-70.cgi">Apache-Tomcat</a> web application server version 7, but older Tomcat versions above 5.5 would work too.<br/>\r
  79 <span class="attention">Please Note:</span> The JABAWS WAR is not generally compatible with older Mac systems based on the PowerPC architecture, since Java 1.6 is not available to run JABAWS.</p>\r
  80 \r
  81 <p>JABAWS Web Application aRchive can run on any host operating system that supports Java 1.6. However JABAWS depends on a number of third party programs which are not available for all operating systems. In particular, not all web services are currently available for MS Windows platform.\r
  82   <!-- todo: link to help about obtaining and installing tomcat -->\r
  83 </p>\r
  84 <p>JABAWS comes with pre-compiled MS Windows and Linux x86 binaries, as well as the source code and build scripts necessary to recompile them.</p>\r
  85 <p>To run JABAWS on the cluster you must have shared disk space accessible from all cluster nodes. </p>\r
  86 <h3><a name="instwar" id="instwar"></a>Installing the JABAWS WAR file</h3>\r
  87 <p>JABAWS is distributed as a web application archive (WAR). To\r
  88 deploy JABAWS in Apache-Tomcat - simply drop the war file into the\r
  89 <span class="highlight">webapps</span> directory of a running\r
  90 Tomcat, and it will do the rest. If you used this deployment procedure, <span class="attention">do not remove</span> the jabaws WAR file, otherwise Tomcat will undeploy your application! The context path for your deployed application will be the same as the name of the war file. For example, assuming the Tomcat server is running on the <span class="hightlight">localhost:8080</span> and <strong>jaba.war</strong> file is put into the <span class="hightlight">&lt;tomcat server root&gt;/webapps</span> directory, the deployed application from the jaba.war file then can be accessed by this URL http://localhost:8080/<strong>jaba</strong>. </p>\r
  91 <p>For any other web application\r
  92   server, please follow your server's specific deployment procedure\r
  93   for 'WAR' files. If you install JABAWS on a MS Windows machine, then\r
  94   at this point your JABAWS installation will already be up and\r
  95   running, and you can try its services out <a href=\r
  96 "#usingWsTester">as described here</a>. If you install JABAWS on Linux you will need to set an executable flag for binaries. This is described  <a href="#useprebin">here</a>. If your host operating system is different from Windows or Linux then read on. </p>\r
  97 <h3><a name="prepexec" id="prepexec"></a>Preparing executables for use with JABAWS</h3>\r
  98 \r
  99 <p>JABAWS's web services use command line programs to do\r
 100 the actual analysis, so it must have access to programs\r
 101 which can be executed on your platform. The native executables\r
 102 bundled with JABAWS for Windows (32-bit) and Linux (i386, 32-bit) should be\r
 103 OK for those systems. The source code for these \r
 104 programs is also provided so you can <a href="#recompbinaries">recompile for your own\r
 105 architecture</a> and exploit any optimizations that your system can\r
 106 provide. Alternately, if you have already got binaries on your\r
 107 system, then you can simply <a href="#haveexec">change the paths in JABAWS's\r
 108 configuration files</a> so these are used instead.</p>\r
 109 \r
 110 <h3><a name="useprebin" id="useprebin"></a>Using the pre-compiled i386 binaries on Linux</h3>\r
 111 \r
 112 <p>JABAWS comes with pre-compiled x86 Linux binaries, thus on such systems JABAWS should work straight out of the box. If you are in any doubts or experience problems you may want to make sure that the binaries supplied work under your OS. To do this just execute each binary, without any command line options or\r
 113 input files. If you see an error message complaining about missing\r
 114 libraries or other problems, then you probably need to <a href=\r
 115 "#recompbinaries">recompile the binaries</a>.</p>\r
 116 \r
 117 You can try the JABAWS functionality with the JABAWS<a\r
 118 href="#usingWsTester"> test client</a>  or have a look at <a href="http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html">deploying on Tomcat</a> tips if you experience any problems.<br />\r
 119  <em>Note: You may want to enable logging, <a href="man_configuration.html#logfiles"> as described here</a></em>.<br />\r
 120  \r
 121 \r
 122 <h3><a name="recompbinaries">Recompiling the bundled\r
 123 programs for your system</a></h3>\r
 124 \r
 125 <p>If you have a fully equipped build environment on your\r
 126 (POSIX-like) system, then you should be able to recompile the\r
 127 programs from the source distributions which are included\r
 128 in the JABAWS war file. A script called 'compilebin.sh' is provided\r
 129 to automate this task.</p>\r
 130 \r
 131 <ol>\r
 132 <li>In a terminal window, change the working directory to <span\r
 133 class="hightlight">binaries/src</span></li>\r
 134 \r
 135 <li>execute the <span class="highlight">compilebin.sh</span>\r
 136 script,<br />\r
 137  either use: <span class="hightlight">chmod +x compilebin.sh;\r
 138 compilebin.sh &gt; compilebin.out;</span><br />\r
 139  or: <span class="hightlight">sh compilebin.sh &gt;\r
 140 compilebin.out</span></li>\r
 141 \r
 142 <li>Now run <span class="hightlight">sh setexecflag.sh</span><br />\r
 143  If any of the binaries was not recompiled, then a 'file not found'\r
 144 error will be raised.</li>\r
 145 \r
 146 <li>Finally, restart your Tomcat server (or JABAWS application only), and <a href="#usingWsTester">test JABAWS</a> to\r
 147 check that it can use the new binaries.</li>\r
 148 </ol>\r
 149 \r
 150 <p>If you couldn't compile everything, then it may be that your system does\r
 151 not have all the tools required for compiling the programs. At the very\r
 152 least check that you have gcc, g++ and make installed in your\r
 153 system. If not install these packages and repeat the compilation\r
 154 steps again. You should also review the compilebin.sh output -\r
 155 which was redirected to compilebin.out, and any errors output to\r
 156 the terminal. Finally, try obtaining the <a href="#obtainexec">pre\r
 157 compiled binaries</a> for your OS.</p>\r
 158 \r
 159 <h3><a name="haveexec" id="haveexec">Reuse the binaries that are\r
 160 already in your system</a></h3>\r
 161 \r
 162 <p>If you would like to use the binaries you already have then you\r
 163 just need to let JABAWS know there they are. To do this, edit:\r
 164 <span class="code">conf/Executable.properties</span></p>\r
 165 <p>When specifying paths to executables that already exist on your system, make sure you provide an absolute path, or one relative to the JABAWS directory inside <span class="highlight">webapps</span>. For example, the default path for clustalw is defined\r
 166 as<span class=\r
 167 "code">local.clustalw.bin=binaries/src/clustalw/src/clustalw2</span>\r
 168 Alternatively, instead of changing <span class=\r
 169 "hightlight">Executable.properties</span> you could also replace\r
 170 the executables bundled with JABAWS with the ones that you have, or make symbolic links to them.\r
 171 Then the default configuration will work for you. More information\r
 172 about <span class="hightlight">the\r
 173 Executable.properties</span> file is given in the <a href="man_configuration.html#exec">JABAWS Configuration chapter.</a></p>\r
 174 \r
 175 <h3><a name="obtainexec" id="obtainexec">Obtaining command line binaries for your operating system</a></h3>\r
 176 \r
 177 <p>You could search for pre-packaged compiled executable in your\r
 178 system package repository or alternately, download pre-compiled\r
 179 binaries from each alignment program's home page. Then, either\r
 180 replace the executables supplied with the downloaded ones, or\r
 181 modify the paths in <span class=\r
 182 "hightlight">executable.properties</span> as described above. Below are some suggestions on where you may be able to get the binaries for your system. </p>\r
 183 <ul>\r
 184   <li><a href="http://www.clustal.org/omega/#Download">Clustal Omega </a></li>\r
 185   <li><a href="ftp://ftp.ebi.ac.uk/pub/software/clustalw2/2.0.12/">ClustalW</a></li>\r
 186   <li><a href="http://mafft.cbrc.jp/alignment/software/">Mafft</a></li>\r
 187   <li><a href="http://www.drive5.com/muscle/download3.6.html">Muscle</a></li>\r
 188   <li><a href="http://www.tcoffee.org/Packages/Binaries/">Tcoffee</a></li>\r
 189   <li>Probcons (Linux <a href="http://www.compbio.dundee.ac.uk/jabaws/archive/binaries/linux_x86/probcons">x86</a> | <a href="http://www.compbio.dundee.ac.uk/jabaws/archive/binaries/linux_x64/probcons">x64</a> | <a href="http://www.compbio.dundee.ac.uk/jabaws/archive/binaries/mac/probcons">Mac</a>)</li>\r
 190   <li>IUPred (Linux <a href="http://www.compbio.dundee.ac.uk/jabaws/archive/binaries/linux_x86/iupred">x86</a> | <a href="http://www.compbio.dundee.ac.uk/jabaws/archive/binaries/linux_x64/iupred">x64</a> | <a href="http://www.compbio.dundee.ac.uk/jabaws/archive/binaries/mac/iupred">Mac</a>)</li>\r
 191 </ul>\r
 192 <h3><a name="usingWsTester" id="usingWsTester"></a>Testing JABAWS Server </h3>\r
 193 <p>First of all make sure that Tomcat server is started successfully. If this was the case, then you should see JABAWS home page when you navigate to your Tomcat JABAWS context path e.g. <span class="code">http://myhost.compbio.ac.uk:8080/jabaws</span></p>\r
 194 <p><strong>Using JABAWS service status checker</strong></p>\r
 195 <p>If you see it, then it is time to make sure that web services are working too. The easiest way to do so is to access Services Status page available from the main JABAWS web page menu. </p>\r
 196 <p>If you need to monitor web service health automatically when the best option is to use service checker that responds with the standard HTTP status code. To access this checker use the following URL: <span class="code">&lt;jabaws_server&gt;/HttpCodeResponseServiceStatus</span>  This page returns code 200, and no page context if all services are operational, 503 if one of the services have problems. You can also check each web service individually by providing the name of the web service to check at the end of the service  checker URL like this: <span class="code">&lt;jabaws_server&gt;/HttpCodeResponseServiceStatus/ClustalWS</span></p>\r
 197 <p>Upon request, the service status checker will examine the health of the ClustalWS web service only. If the service name is not valid, then the service checker will return code 400. </p>\r
 198 <p><strong>Using command line client</strong> </p>\r
 199 <p>Alternatively, you should be able to use the test program which can be found in &lt;webapplicationpath&gt;/WEB-INF/lib/jabaws-client.jar file. To run the tests type:<span class="code"> java -jar jabaws-client.jar -h=&lt;Your web application server host name, port and JABAWS context path&gt;</span></p>\r
 200 <p>For example to test all JABAWS web services on host myhost.compbio.ac.uk type: </p>\r
 201 <p class="code">java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws </p>\r
 202 <p>You can choose a particular web server using -s option like this <span class="code">java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws -s=ClustalWS </span>This command line assumes that java executable is in your path and jabaws-client.jar is located in the current directory.</p>\r
 203 <p>An example of the report testing tool produces for operating web service looks like this: </p>\r
 204 <p><span class="code"> Connecting to service MuscleWS on http://myhost.compbio.ac.uk:8080/jabaws ... OK<br />\r
 205   Testing alignment with default parameters:<br />\r
 206   Queering job status...OK<br />\r
 207   Retrieving results...OK<br />\r
 208   Testing alignment with presets:<br />\r
 209   Aligning with preset 'Protein alignment(Fastest speed)'... OK<br />\r
 210   Aligning with preset 'Nucleotide alignment(Fastest speed)'... OK<br />\r
 211   Aligning with preset 'Huge alignments (speed-oriented)'... OK<br />\r
 212   Queering presets...OK<br />\r
 213   Queering Parameters...OK<br />\r
 214   Queering Limits...OK<br />\r
 215   Queering Local Engine Limits...OK<br />\r
 216   Check is completed service MuscleWS IS WORKING</span>An example of the response of a web service which is deployed but is not operating is below: </p>\r
 217 <p><span class="code">Connecting to service ProbconsWS on http://localhost:8080/ws ... OK<br />\r
 218   Testing alignment with default parameters:FAILED<br />\r
 219   Service ProbconsWS IS NOT FUNCTIONAL</span>If the web server did not respond the message looks like following: <span class="code">Connecting to service TcoffeeWS on http://localhost:8080/ws ... FAILED</span></p>\r
 220 <h3><a name="diffcontexts" id="diffcontexts"/></a></a>Running many JABAWS instances on the same server</h3>\r
 221 <p> JABAWS is supplied as a Web Application aRchive which can be dealt with as any other web applications. So it is perfectly possible to run two JABAWS instances from the same server. Just make two different contexts on your application server and unpack JABAWS in both of them. For example if your server name is http://www.align.ac.uk, and the context names are public and private. Than one group of users could be given a URL http://www.align.ac.uk/public and another http://www.align.ac.uk/private. These contexts will be served by two independent JABAWS instances, and could be configured differently. If you keep local engine enabled, make sure you reduce the number of threads local engine is allowed to use to avoid overloading the server. Alternatively two completely separate web application server instances (e.g. Apache-Tomcat) could be used. This will give you a better resilience and more flexibility in memory settings. </p>\r
 222 <h3><a name="nocluster" id="nocluster"></a>JABAWS on a single server</h3>\r
 223 <p>You can run  JABAWS on a single server. Obviously the capacity will be limited, but may be sufficient for a small lab. Installed on a single server, JABAWS executes tasks in parallel, so the more cores the server has the more requests it will be able to handle. </p>\r
 224 <h3><a name="clustsubsys" id="clustsubsys"></a>JABAWS supported cluster batch management systems </h3>\r
 225 <p>JABAWS uses <a href="http://drmaa.org/">DRMAA</a> v. 1.0 library to send and manage jobs on the cluster. DRMAA supports many different cluster job management systems. Namely Sun Grid Engine, Condor, PBS, GridWay, Globus 2/4, PBSPro, LSF. For up to date information please consult DRMAA web site. We found that DRMAA implementation differ from platform to platform and were trying to use only the basic functions. We have only tested JABAWS on Sun Grid Engine v 6.2. Please let use know if you have any experience of running JABAWS on other platforms.</p>\r
 226 <h3><a name="tomstopundeploy" id="tomstopundeploy"></a>Manually deploying JABAWS application on Apache-Tomcat </h3>\r
 227 <p>To stop Tomcat from automatically undeploying your application if the war file is removed use an explicit application descriptor. It could come in different flavors, the one I prefer if to drop a context descriptor file into <span class="hightlight">&lt;tomcatRoot&gt;conf/Catalina/localhost</span> directory. Name your context file the same as your application folder e.g. if you JABAWS resides in webappl/jabaws folder, then call the context file jabaws.xml. Below is an example of content this file might have.</p>\r
 228 <p class="code">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;<br />\r
 229   &lt;Context antiResourceLocking=&quot;false&quot; privileged=&quot;true&quot;  /&gt;</p>\r
 230 <p>This should be sufficient to prevent Tomcat from removing your JABAWS from WEBAPPS. For more information about the Tomcat deployer <a href="http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html">read this documentation on the Apache-Tomcat web site</a>.</p>\r
 231 <h3><a name="tomdeploy" id="tomdeploy"></a>Apache-Tomcat fails to deploy jabaws.war file </h3>\r
 232 <ul>\r
 233   <li>Make sure Tomcat have sufficient access rights to read your war file. </li>\r
 234   <li>Restart the Tomcat, sometimes it will not since that the new war file is added without restart</li>\r
 235   <li>If Tomcat still refuses to unpack the war file, unpack it manually into web application folder (the war file is just a zip archive). Restart the Tomcat.</li>\r
 236 </ul>\r
 237 </div>\r
 238 \r
 239 <!-- content end-->\r
 240 <div id="copyright">Last update: 16 September 2011<br />\r
 241  Peter Troshin, Jim Procter and Geoff Barton, The Barton Group, University of\r
 242 Dundee, UK</div>\r
 243 </div>\r
 244 \r
 245 <!-- wrapper end-->\r
 246 </div>\r
 247 <!-- page end-->\r
 248 \r
 249 <!-- Google analitics -->\r
 250 <script type="text/javascript">\r
 251 var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");\r
 252 document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));\r
 253 </script>\r
 254 <script type="text/javascript">\r
 255 try{\r
 256 var pageTracker = _gat._getTracker("UA-5356328-1");\r
 257 pageTracker._trackPageview();\r
 258 } catch(err) {}\r
 259 </script>\r
 260 </body>\r
 261 </html>\r
 262 \r