website/man_serverwar.jsp

   1 <%--<?xml version="1.0" encoding="ISO-8859-1" ?>--%>
   2 <%--<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>--%>
   3
   4 <%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
   5 <%@ taglib uri="http://java.sun.com/jsp/jstl/functions" prefix="fn" %>
   6 <%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt" %>
   7 <%@ taglib uri="http://displaytag.sf.net" prefix="dt" %>
   8
   9
  10 <c:import url="template_header.jsp" >
  11     <c:param name="title">Documentation</c:param>
  12 </c:import>
  13
  14 <ol class="breadcrumb">
  15     <li><a href="${pageContext.request.contextPath}/index.jsp">Home</a></li>
  16     <li><a href="man_docs.jsp">Documentation</a></li>
  17     <li class="active"><a href="man_server_dev.jsp">Develop JABAWS</a></li>
  18 </ol>
  19 <div class="row">
  20     <div class="col-md-12">
  21         <div class="panel panel-default">
  22             <div class="panel panel-heading">
  23                 <h1 class="panel-title">Web Application Archive</h1>
  24             </div>
  25             <div class="panel-body">
  26                 <ul>
  27                     <li><a href="#sysreq">System Requirements</a></li>
  28                     <li><a href="#instwar">Installing the JABAWS WAR file</a></li>
  29                     <li><a href="#prepexec">Preparing executables for use with JABAWS</a></li>
  30                     <li><a href="#useprebin">Using the pre-compiled i386 binaries on Linux</a></li>
  31                     <li><a href="#recompbinaries">Recompiling the bundled programs for your system</a></li>
  32                     <li><a href="#haveexec">Reuse the binaries that are already in your system</a></li>
  33                     <li><a href="#obtainexec">Obtaining command line binaries </a><a href="#obtainexec">for your operating system</a></li>
  34                     <li><a href="#usingWsTester">Testing JABAWS Server</a></li>
  35                     <li><a href="#diffcontexts">Running many JABAWS instances on the same server</a> </li>
  36                     <li><a href="#nocluster">JABAWS on a single server</a></li>
  37                     <li><a href="#clustsubsys">JABAWS supported cluster batch management systems </a></li>
  38                     <li><a href="#tomstopundeploy">Manually deploying JABAWS application on Apache-Tomcat </a></li>
  39                     <li><a href="#tomdeploy">Apache-Tomcat fails to deploy the jabaws.war file</a></li>
  40                 </ul>
  41                 <!--<p class="justify">-->
  42                 <!--</p>-->
  43             </div>
  44         </div>
  45     </div>
  46 </div>
  47 <div class="row" id="sysreq">
  48     <div class="col-md-12">
  49         <div class="panel panel-default">
  50             <div class="panel panel-heading">
  51                 <h1 class="panel-title">System Requirements</h1>
  52             </div>
  53             <div class="panel-body">
  54                 <p class="justify">JABAWS requires a Java web application server compliant with
  55                     version 2.4 of the Java Servlet specification, and a Java 6 runtime
  56                     environment. We recommend using an official Oracle Java 6 runtime
  57                     environment, and <a
  58                             href="http://tomcat.apache.org/download-70.cgi">Apache-Tomcat</a>
  59                     web application server version 7, but older Tomcat versions above 5.5 will
  60                     work too.<br/>
  61                     <span class="attention">Please Note:</span>
  62                     The JABAWS WAR is not generally compatible with older Mac systems based
  63                     on the PowerPC architecture, since Java 1.6 is not available to run JABAWS.
  64                 </p>
  65                 <p class="justify">
  66                     JABAWS Web Application aRchive can run on any host operating system that supports
  67                     Java 1.6. However JABAWS depends on a number of third party programs which are
  68                     not available for all operating systems. In particular, not all web services
  69                     are currently available for MS Windows platform. To install Tomcat follow the
  70                     intructions provided in the following
  71                     <a href="http://tomcat.apache.org/tomcat-7.0-doc/">documentation</a>.
  72                 </p>
  73                 <p class="justify">
  74                     JABAWS comes with pre-compiled MS Windows and Linux x86 binaries, as well as the
  75                     source code and build scripts necessary to recompile them.
  76                 </p>
  77                 <p class="justify">
  78                     To run JABAWS on the cluster you must have shared disk space accessible from
  79                     all cluster nodes.
  80                 </p>
  81
  82                 <p class="text-right">
  83                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
  84                 </p>
  85             </div>
  86         </div>
  87     </div>
  88 </div>
  89 <div class="row" id="instwar">
  90     <div class="col-md-12">
  91         <div class="panel panel-default">
  92             <div class="panel panel-heading">
  93                 <h1 class="panel-title">Installing the JABAWS WAR file</h1>
  94             </div>
  95             <div class="panel-body">
  96                 <p class="justify">
  97                     JABAWS is distributed as a web application archive (WAR). To
  98                     deploy JABAWS in Apache-Tomcat - simply drop the war file into the
  99                     <em2>webapps</em2> directory of a running
 100                     Tomcat, and it will do the rest. If you used this deployment procedure,
 101                     <span class="attention">do not remove</span> the Jabaws WAR file,
 102                     otherwise Tomcat will undeploy your application! The context path
 103                     for your deployed application will be the same as the name of the
 104                     war file. For example, assuming the Tomcat server is running on
 105                     the <em2>localhost:8080</em2> and
 106                     <strong>jaba.war</strong> file is put into the
 107                     <em2>&lt;tomcat server root&gt;/webapps</em2> directory,
 108                     the deployed application from the jaba.war file then can be accessed by this
 109                     URL http://localhost:8080/<strong>jaba</strong>.
 110                 </p>
 111                 <p class="justify">For any other web application
 112                     server, please follow your server's specific deployment procedure
 113                     for 'WAR' files. If you install JABAWS on a MS Windows machine, then
 114                     at this point your JABAWS installation will already be up and
 115                     running, and you can try its services out
 116                     <a href="#usingWsTester">as described here</a>. If you
 117                     install JABAWS on Linux you will need to set an executable
 118                     flag for binaries. This is described  <a href="#useprebin">here</a>.
 119                     If your host operating system is different from Windows or Linux
 120                     then read on.
 121                 </p>
 122                 <p class="text-right">
 123                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 124                 </p>
 125             </div>
 126         </div>
 127     </div>
 128 </div>
 129 <div class="row" id="prepexec">
 130     <div class="col-md-12">
 131         <div class="panel panel-default">
 132             <div class="panel panel-heading">
 133                 <h1 class="panel-title">Preparing executables for use with JABAWS</h1>
 134             </div>
 135             <div class="panel-body">
 136                 <p class="justify">
 137                     JABAWS's web services use command line programs to do
 138                     the actual analysis, so it must have access to programs
 139                     which can be executed on your platform. The native executables
 140                     bundled with JABAWS for Windows (32-bit) and Linux (i386, 32-bit) should be
 141                     OK for those systems. The source code for these
 142                     programs is also provided so you can <a href="#recompbinaries">recompile for
 143                     your own architecture</a> and exploit any optimizations that your system can
 144                     provide. Alternately, if you have already got binaries on your
 145                     system, then you can simply <a href="#haveexec">change the paths in JABAWS's
 146                         configuration files</a> so these are used instead.
 147                 </p>
 148                 <p class="text-right">
 149                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 150                 </p>
 151             </div>
 152         </div>
 153     </div>
 154 </div>
 155 <div class="row" id="useprebin">
 156     <div class="col-md-12">
 157         <div class="panel panel-default">
 158             <div class="panel panel-heading">
 159                 <h1 class="panel-title">Using the pre-compiled i386 binaries on Linux</h1>
 160             </div>
 161             <div class="panel-body">
 162                 <p class="justify">
 163                     JABAWS comes with pre-compiled x86 Linux binaries, thus on such systems
 164                     JABAWS should work straight out of the box. If you are in any doubts or
 165                     experience problems you may want to make sure that the binaries supplied
 166                     work under your OS. To do this just execute each binary, without any
 167                     command line options or
 168                     input files. If you see an error message complaining about missing
 169                     libraries or other problems, then you probably need to
 170                     <a href="#recompbinaries">recompile the binaries</a>.
 171                 </p>
 172                 <p class="justify">
 173                     You can try the JABAWS functionality with the JABAWS<a
 174                         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 />
 175                     <em2>Note: You may want to enable logging,
 176                         <a href="man_configuration.jsp#logfiles"> as described here</a></em2>.
 177                 </p>
 178                 <p class="text-right">
 179                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 180                 </p>
 181             </div>
 182         </div>
 183     </div>
 184 </div>
 185 <div class="row" id="recompbinaries">
 186     <div class="col-md-12">
 187         <div class="panel panel-default">
 188             <div class="panel panel-heading">
 189                 <h1 class="panel-title">Recompiling the bundled
 190                     programs for your system</h1>
 191             </div>
 192             <div class="panel-body">
 193                 <p class="justify">
 194                     If you have a fully equipped build environment on your
 195                     (POSIX-like) system, then you should be able to recompile the
 196                     programs from the source distributions which are included
 197                     in the JABAWS war file. A script called 'compilebin.sh' is provided
 198                     to automate this task.
 199                 </p>
 200
 201                 <ol>
 202                     <li>In a terminal window, change the working directory to <em2>binaries/src</em2>
 203                     </li>
 204
 205                     <li>execute the <em2>compilebin.sh</em2> script,<br />
 206                         either use:
 207                         <pre><code class="bash">chmod +x compilebin.sh; compilebin.sh &gt; compilebin.out;</code></pre>
 208                         or:
 209                         <pre><code class="bash">sh compilebin.sh &gt; compilebin.out</code></pre>
 210                     </li>
 211
 212                     <li>Now run <pre><code class="bash">sh setexecflag.sh</code></pre>
 213                         If any of the binaries was not recompiled, then a 'file not found'
 214                         error will be raised.
 215                     </li>
 216
 217                     <li>Finally, restart your Tomcat server (or JABAWS application only), and
 218                         <a href="#usingWsTester">test JABAWS</a> to
 219                         check that it can use the new binaries.
 220                     </li>
 221                 </ol>
 222
 223                 <p class="justify">
 224                     If you couldn't compile everything, then it may be that your system does
 225                     not have all the tools required for compiling the programs. At the very
 226                     least check that you have gcc, g++ and make installed in your
 227                     system. If not install these packages and repeat the compilation
 228                     steps again. You should also review the compilebin.sh output -
 229                     which was redirected to compilebin.out, and any errors output to
 230                     the terminal. Finally, try obtaining the <a href="#obtainexec">pre
 231                     compiled binaries</a> for your OS.
 232                 </p>
 233                 <p class="text-right">
 234                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 235                 </p>
 236             </div>
 237         </div>
 238     </div>
 239 </div>
 240 <div class="row" id="haveexec">
 241     <div class="col-md-12">
 242         <div class="panel panel-default">
 243             <div class="panel panel-heading">
 244                 <h1 class="panel-title">Reuse the binaries that are
 245                     already in your system</h1>
 246             </div>
 247             <div class="panel-body">
 248                 <p class="justify">
 249                     If you would like to use the binaries you already have, then you
 250                     just need to let JABAWS know where they are. To do this, edit:
 251                     <em2>conf/Executable.properties</em2>
 252                 </p>
 253                 <p class="justify">
 254                     When specifying paths to executables that already exist on your system,
 255                     make sure you provide an absolute path, or one relative to the JABAWS
 256                     directory inside <em2>webapps</em2>. For example,
 257                     the default path for clustalw is defined
 258                     as <em2>local.clustalw.bin=binaries/src/clustalw/src/clustalw2</em2>
 259                     Alternatively, instead of changing
 260                     <em2>Executable.properties</em2>
 261                     you could also replace
 262                     the executables bundled with JABAWS with the ones that you have, or make
 263                     symbolic links to them.
 264                     Then the default configuration will work for you. More information
 265                     about the <em2>Executable.properties</em2> file is given in the
 266                     <a href="man_configuration.jsp#exec">JABAWS Configuration chapter.</a>
 267                 </p>
 268                 <p class="text-right">
 269                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 270                 </p>
 271             </div>
 272         </div>
 273     </div>
 274 </div>
 275 <div class="row" id="obtainexec">
 276     <div class="col-md-12">
 277         <div class="panel panel-default">
 278             <div class="panel panel-heading">
 279                 <h1 class="panel-title">Obtaining command line binaries for
 280                     your operating system</h1>
 281             </div>
 282             <div class="panel-body">
 283                 <p class="justify">
 284                     You could search for pre-packaged compiled executable in your
 285                     system package repository or alternately, download pre-compiled
 286                     binaries from each alignment program's home page. Then, either
 287                     replace the executables supplied with the downloaded ones, or
 288                     modify the paths in <em2>executable.properties</em2>
 289                     as described above. Below are some suggestions on where you may be able to
 290                     get the binaries for your system.
 291                 </p>
 292                 <ul>
 293                     <li><a href="http://www.clustal.org/omega/#Download">Clustal Omega </a></li>
 294                     <li><a href="http://www.clustal.org/clustal2/#Download">ClustalW </a></li>
 295                     <li><a href="http://mafft.cbrc.jp/alignment/software/">Mafft</a></li>
 296                     <li><a href="http://www.drive5.com/muscle/downloads.htm">Muscle</a></li>
 297                     <li><a href="http://www.tcoffee.org/Projects/tcoffee/#DOWNLOAD">Tcoffee</a></li>
 298                 </ul>
 299             </div>
 300         </div>
 301     </div>
 302 </div>
 303 <div class="row" id="usingWsTester">
 304     <div class="col-md-12">
 305         <div class="panel panel-default">
 306             <div class="panel panel-heading">
 307                 <h1 class="panel-title">Testing JABAWS Server</h1>
 308             </div>
 309             <div class="panel-body">
 310                 <p class="justify">
 311                     First of all make sure that Tomcat server is started successfully. If this was the case,
 312                     then you should see JABAWS home page when you navigate to your Tomcat JABAWS context
 313                     path e.g. <pre>http://myhost.compbio.ac.uk:8080/jabaws</pre>
 314                 <p>
 315                     <strong>Using JABAWS service status checker</strong>
 316                 </p>
 317                 <p class="justify">If you see it, then it is time to make sure that web services are
 318                     working too. The easiest way to do this is to access Services Status page available
 319                     from the main JABAWS web page menu.
 320                 </p>
 321                 <p class="justify">
 322                     If you need to monitor web service health automatically when the
 323                     best option is to use service checker that responds with the standard HTTP status
 324                     code. To access this checker use the following
 325                     URL: <pre><code class="bash">&lt;jabaws_server&gt;/HttpCodeResponseServiceStatus</code></pre>
 326                     This page returns code 200, and no page context if all services are operational, 503
 327                     if one of the services have problems. You can also check each web service individually
 328                     by providing the name of the web service to check at the end of the service  checker URL
 329                 like this: <pre><code class="bash">&lt;jabaws_server&gt;/HttpCodeResponseServiceStatus/ClustalWS</code></pre>
 330                 </pre>
 331                 <p class="justify">
 332                     Upon request, the service status checker will examine the health of the ClustalWS web
 333                     service only. If the service name is not valid, then the service checker will return code 400.
 334                 </p>
 335                 <p class="justify">
 336                     <strong>Using command line client</strong>
 337                 </p>
 338                 <p class="justify">
 339                     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>
 340                 <p class="justify">
 341                     For example to test all JABAWS web services on host myhost.compbio.ac.uk type:
 342                 </p>
 343                 <pre><code class="bash">java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws</code></pre>
 344                 <p class="justify">
 345                     You can choose a particular web server using -s option like
 346                     this <span class="code">java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws -s=ClustalWS </span>
 347                     This command line assumes that java executable is in your path and jabaws-client.jar is
 348                     located in the current directory.
 349                 </p>
 350                 <p class="justify">
 351                     An example of the report testing tool produces for operating web service looks like this:
 352                 </p>
 353                 <p class="justify">
 354                     <pre><code class="bash">Connecting to service MuscleWS on http://myhost.compbio.ac.uk:8080/jabaws ... OK
 355 Testing alignment with default parameters:
 356 Queering job status...OK
 357 Retrieving results...OK
 358 Testing alignment with presets:
 359 Aligning with preset 'Protein alignment(Fastest speed)'... OK
 360 Aligning with preset 'Nucleotide alignment(Fastest speed)'... OK
 361 Aligning with preset 'Huge alignments (speed-oriented)'... OK
 362 Queering presets...OK
 363 Queering Parameters...OK
 364 Queering Limits...OK
 365 Queering Local Engine Limits...OK
 366 Check is completed service MuscleWS IS WORKING</code></pre>
 367                 <p>
 368                     An example of the response of a web service which is deployed but is not operating is below:
 369                 </p>
 370                 <p class="justify">
 371                     <pre><code class="bash">Connecting to service ProbconsWS on http://localhost:8080/ws ... OK
 372 Testing alignment with default parameters:FAILED
 373 Service ProbconsWS IS NOT FUNCTIONAL</code></pre>
 374                 </p>
 375                 <p>If the web server did not respond the message looks like following:
 376                     <pre>Connecting to service TcoffeeWS on http://localhost:8080/ws ... FAILED</pre>
 377                 </p>
 378             </div>
 379         </div>
 380     </div>
 381 </div>
 382 <div class="row" id="diffcontexts">
 383     <div class="col-md-12">
 384         <div class="panel panel-default">
 385             <div class="panel panel-heading">
 386                 <h1 class="panel-title">Running many JABAWS instances on the same server</h1>
 387             </div>
 388             <div class="panel-body">
 389                 <p class="justify">
 390                     JABAWS is supplied as a Web Application aRchive which can be dealt with
 391                     as any other web applications. So it is perfectly possible to run two
 392                     JABAWS instances from the same server. Just make two different contexts
 393                     on your application server and unpack JABAWS in both of them. For example
 394                     if your server name is http://www.align.ac.uk, and the context names are
 395                     public and private. Than one group of users could be given a URL
 396                     http://www.align.ac.uk/public and another http://www.align.ac.uk/private.
 397                     These contexts will be served by two independent JABAWS instances, and
 398                     could be configured differently. If you keep local engine enabled, make
 399                     sure you reduce the number of threads local engine is allowed to use to
 400                     avoid overloading the server. Alternatively two completely separate web
 401                     application server instances (e.g. Apache-Tomcat) could be used. This will
 402                     give you a better resilience and more flexibility in memory settings.
 403                 </p>
 404             </div>
 405         </div>
 406     </div>
 407 </div>
 408 <div class="row" id="nocluster">
 409     <div class="col-md-12">
 410         <div class="panel panel-default">
 411             <div class="panel panel-heading">
 412                 <h1 class="panel-title">JABAWS on a single server</h1>
 413             </div>
 414             <div class="panel-body">
 415                 <p class="justify">
 416                     You can run  JABAWS on a single server. Obviously the capacity will be
 417                     limited, but it may be sufficient for a small lab. Installed on a single
 418                     server, JABAWS executes tasks in parallel, so the more cores the server has
 419                     the more requests it will be able to handle.
 420                 </p>
 421             </div>
 422         </div>
 423     </div>
 424 </div>
 425 <div class="row" id="clustsubsys">
 426     <div class="col-md-12">
 427         <div class="panel panel-default">
 428             <div class="panel panel-heading">
 429                 <h1 class="panel-title">JABAWS supported cluster batch management systems</h1>
 430             </div>
 431             <div class="panel-body">
 432                 <p class="justify">
 433                     JABAWS uses <a href="http://drmaa.org/">DRMAA</a> v. 1.0 library to send and manage jobs
 434                     on the cluster. DRMAA supports many different cluster job management systems. Namely Sun
 435                     Grid Engine, Condor, PBS, GridWay, Globus 2/4, PBSPro, LSF. For up to date information
 436                     please consult DRMAA web site. We found that DRMAA implementation differ from platform
 437                     to platform and were trying to use only the basic functions. We have only tested JABAWS
 438                     on Sun Grid Engine v 6.2. Please let use know if you have any experience of running JABAWS
 439                     on other platforms.
 440                 </p>
 441             </div>
 442         </div>
 443     </div>
 444 </div>
 445 <div class="row" id="tomstopundeploy">
 446     <div class="col-md-12">
 447         <div class="panel panel-default">
 448             <div class="panel panel-heading">
 449                 <h1 class="panel-title">Manually deploying JABAWS application on Apache-Tomcat</h1>
 450             </div>
 451             <div class="panel-body">
 452                 <p class="justify">
 453                     To stop Tomcat from automatically undeploying your application if the war file is
 454                     removed use an explicit application descriptor. It could come in different flavors,
 455                     the one I prefer is to drop a context descriptor file into
 456                     <em2>&lt;tomcatRoot&gt;conf/Catalina/localhost</em2> directory.
 457                     Name your context file the same as your application folder e.g. if your
 458                     JABAWS resides in webappl/jabaws folder, then call the context file jabaws.xml.
 459                     Below is an example of content this file might have.
 460                 </p>
 461                 <pre><code class="xml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
 462 &lt;Context antiResourceLocking=&quot;false&quot; privileged=&quot;true&quot; /&gt;</code></pre>
 463                 <p class="justify">
 464                     This should be sufficient to prevent Tomcat from removing your JABAWS from WEBAPPS.
 465                     For more information about the Tomcat deployer
 466                     <a href="http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html">read
 467                         this documentation on the Apache-Tomcat web site</a>.
 468                 </p>
 469             </div>
 470         </div>
 471     </div>
 472 </div>
 473 <div class="row" id="tomdeploy">
 474     <div class="col-md-12">
 475         <div class="panel panel-default">
 476             <div class="panel panel-heading">
 477                 <h1 class="panel-title">Apache-Tomcat fails to deploy jabaws.war file</h1>
 478             </div>
 479             <div class="panel-body">
 480                 <ul>
 481                     <li>Make sure Tomcat has sufficient access rights to read your war file. </li>
 482                     <li>Restart the Tomcat, sometimes it will not restart after the new war file
 483                         is added without restart</li>
 484                     <li>If Tomcat still refuses to unpack the war file, unpack it manually into
 485                         web application folder (the war file is just a zip archive). Restart the
 486                         Tomcat.</li>
 487                 </ul>
 488             </div>
 489         </div>
 490     </div>
 491 </div>
 492
 493 <jsp:include page="template_footer.jsp" />