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 to 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 jabaws.war file then can be accessed by this
 109                     URL http://localhost:8080/<strong>jabaws</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 to 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
 175                     <a href="http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html">deploying on Tomcat</a>
 176                     tips if you experience any problems.<br />
 177                     <em>Note: You may want to enable logging,
 178                         <a href="man_configuration.jsp#logfiles"> as described here</a></em>.
 179                 </p>
 180                 <p class="text-right">
 181                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 182                 </p>
 183             </div>
 184         </div>
 185     </div>
 186 </div>
 187 <div class="row" id="recompbinaries">
 188     <div class="col-md-12">
 189         <div class="panel panel-default">
 190             <div class="panel panel-heading">
 191                 <h1 class="panel-title">Recompiling the bundled
 192                     programs for your system</h1>
 193             </div>
 194             <div class="panel-body">
 195                 <p class="justify">
 196                     If you have a fully equipped build environment on your
 197                     (POSIX-like) system, then you should be able to recompile the
 198                     programs from the source distributions which are included
 199                     in the JABAWS war file. A script called 'compilebin.sh' is provided
 200                     to automate this task.
 201                 </p>
 202
 203                 <ol>
 204                     <li>In a terminal window, change the working directory to <em2>binaries/src</em2>
 205                     </li>
 206
 207                     <li>execute the <em2>compilebin.sh</em2> script,<br />
 208                         either use:
 209                         <pre><code class="bash">chmod +x compilebin.sh; compilebin.sh &gt; compilebin.out;</code></pre>
 210                         or:
 211                         <pre><code class="bash">sh compilebin.sh &gt; compilebin.out</code></pre>
 212                     </li>
 213
 214                     <li>Now run <pre><code class="bash">sh setexecflag.sh</code></pre>
 215                         If any of the binaries was not recompiled, then a 'file not found'
 216                         error will be raised.
 217                     </li>
 218
 219                     <li>Finally, restart your Tomcat server (or JABAWS application only), and
 220                         <a href="#usingWsTester">test JABAWS</a> to
 221                         check that it can use the new binaries.
 222                     </li>
 223                 </ol>
 224
 225                 <p class="justify">
 226                     If you couldn't compile everything, then it may be that your system does
 227                     not have all the tools required for compiling the programs. At the very
 228                     least check that you have gcc, g++ and make installed in your
 229                     system. If not install these packages and repeat the compilation
 230                     steps again. You should also review the compilebin.sh output -
 231                     which was redirected to compilebin.out, and any errors output to
 232                     the terminal. Finally, try obtaining the <a href="#obtainexec">pre
 233                     compiled binaries</a> for your OS.
 234                 </p>
 235                 <p class="text-right">
 236                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 237                 </p>
 238             </div>
 239         </div>
 240     </div>
 241 </div>
 242 <div class="row" id="haveexec">
 243     <div class="col-md-12">
 244         <div class="panel panel-default">
 245             <div class="panel panel-heading">
 246                 <h1 class="panel-title">Reuse the binaries that are
 247                     already in your system</h1>
 248             </div>
 249             <div class="panel-body">
 250                 <p class="justify">
 251                     If you would like to use the binaries you already have, then you
 252                     just need to let JABAWS know where they are. To do this, edit:
 253                     <em2>conf/Executable.properties</em2>
 254                 </p>
 255                 <p class="justify">
 256                     When specifying paths to executables that already exist on your system,
 257                     make sure you provide an absolute path, or one relative to the JABAWS
 258                     directory inside <em2>webapps</em2>. For example,
 259                     the default path for clustalw is defined
 260                     as <em2>local.clustalw.bin=binaries/src/clustalw/src/clustalw2</em2>
 261                     Alternatively, instead of changing
 262                     <em2>Executable.properties</em2>
 263                     you could also replace
 264                     the executables bundled with JABAWS with the ones that you have, or make
 265                     symbolic links to them.
 266                     Then the default configuration will work for you. More information
 267                     about the <em2>Executable.properties</em2> file is given in the
 268                     <a href="man_configuration.jsp#exec">JABAWS Configuration page.</a>
 269                 </p>
 270                 <p class="text-right">
 271                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 272                 </p>
 273             </div>
 274         </div>
 275     </div>
 276 </div>
 277 <div class="row" id="obtainexec">
 278     <div class="col-md-12">
 279         <div class="panel panel-default">
 280             <div class="panel panel-heading">
 281                 <h1 class="panel-title">Obtaining command line binaries for
 282                     your operating system</h1>
 283             </div>
 284             <div class="panel-body">
 285                 <p class="justify">
 286                     You could search for pre-packaged compiled executable in your
 287                     system package repository or alternately, download pre-compiled
 288                     binaries from each alignment program's home page. Then, either
 289                     replace the executables supplied with the downloaded ones, or
 290                     modify the paths in <em2>executable.properties</em2>
 291                     as described above. Below are some suggestions on where you may be able to
 292                     get the binaries for your system.
 293                 </p>
 294                 <ul>
 295                     <li><a href="http://www.clustal.org/omega/#Download">Clustal Omega </a></li>
 296                     <li><a href="http://www.clustal.org/clustal2/#Download">ClustalW </a></li>
 297                     <li><a href="http://mafft.cbrc.jp/alignment/software/">Mafft</a></li>
 298                     <li><a href="http://www.drive5.com/muscle/downloads.htm">Muscle</a></li>
 299                     <li><a href="http://www.tcoffee.org/Projects/tcoffee/#DOWNLOAD">Tcoffee</a></li>
 300                 </ul>
 301             </div>
 302         </div>
 303     </div>
 304 </div>
 305 <div class="row" id="usingWsTester">
 306     <div class="col-md-12">
 307         <div class="panel panel-default">
 308             <div class="panel panel-heading">
 309                 <h1 class="panel-title">Testing JABAWS Server</h1>
 310             </div>
 311             <div class="panel-body">
 312                 <p class="justify">
 313                     First of all make sure that Tomcat server is started successfully. If this was the case,
 314                     then you should see JABAWS home page when you navigate to your Tomcat JABAWS context
 315                     path e.g. <pre>http://myhost.compbio.ac.uk:8080/jabaws</pre>
 316                 <p>
 317                     <strong>Using JABAWS service status checker</strong>
 318                 </p>
 319                 <p class="justify">If you see it, then it is time to make sure that web services are
 320                     working too. The easiest way to do this is to access Services Status page available
 321                     from the main JABAWS web page menu.
 322                 </p>
 323                 <p class="justify">
 324                     If you need to monitor web service health automatically when the
 325                     best option is to use service checker that responds with the standard HTTP status
 326                     code. To access this checker use the following
 327                     URL: <pre><code class="bash">&lt;jabaws_server&gt;/HttpCodeResponseServiceStatus</code></pre>
 328                     This page returns code 200, and no page context if all services are operational, 503
 329                     if one of the services have problems. You can also check each web service individually
 330                     by providing the name of the web service to check at the end of the service  checker URL
 331                 like this: <pre><code class="bash">&lt;jabaws_server&gt;/HttpCodeResponseServiceStatus/ClustalWS</code></pre>
 332                 </pre>
 333                 <p class="justify">
 334                     Upon request, the service status checker will examine the health of the ClustalWS web
 335                     service only. If the service name is not valid, then the service checker will return code 400.
 336                 </p>
 337                 <p class="justify">
 338                     <strong>Using command line client</strong>
 339                 </p>
 340                 <p class="justify">
 341                     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>
 342                 <p class="justify">
 343                     For example to test all JABAWS web services on host myhost.compbio.ac.uk type:
 344                 </p>
 345                 <pre><code class="bash">java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws</code></pre>
 346                 <p class="justify">
 347                     You can choose a particular web server using -s option like
 348                     this <span class="code">java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws -s=ClustalWS </span>
 349                     This command line assumes that java executable is in your path and jabaws-client.jar is
 350                     located in the current directory.
 351                 </p>
 352                 <p class="justify">
 353                     An example of the report testing tool produces for operating web service looks like this:
 354                 </p>
 355                 <p class="justify">
 356                     <pre><code class="bash">Connecting to service MuscleWS on http://myhost.compbio.ac.uk:8080/jabaws ... OK
 357 Testing alignment with default parameters:
 358 Queering job status...OK
 359 Retrieving results...OK
 360 Testing alignment with presets:
 361 Aligning with preset 'Protein alignment(Fastest speed)'... OK
 362 Aligning with preset 'Nucleotide alignment(Fastest speed)'... OK
 363 Aligning with preset 'Huge alignments (speed-oriented)'... OK
 364 Queering presets...OK
 365 Queering Parameters...OK
 366 Queering Limits...OK
 367 Queering Local Engine Limits...OK
 368 Check is completed service MuscleWS IS WORKING</code></pre>
 369                 <p>
 370                     An example of the response of a web service which is deployed but is not operating is below:
 371                 </p>
 372                 <p class="justify">
 373                     <pre><code class="bash">Connecting to service ProbconsWS on http://localhost:8080/ws ... OK
 374 Testing alignment with default parameters:FAILED
 375 Service ProbconsWS IS NOT FUNCTIONAL</code></pre>
 376                 </p>
 377                 <p>If the web server did not respond the message looks like following:
 378                     <pre>Connecting to service TcoffeeWS on http://localhost:8080/ws ... FAILED</pre>
 379                 </p>
 380             </div>
 381         </div>
 382     </div>
 383 </div>
 384 <div class="row" id="diffcontexts">
 385     <div class="col-md-12">
 386         <div class="panel panel-default">
 387             <div class="panel panel-heading">
 388                 <h1 class="panel-title">Running many JABAWS instances on the same server</h1>
 389             </div>
 390             <div class="panel-body">
 391                 <p class="justify">
 392                     JABAWS is supplied as a Web Application aRchive which can be dealt with
 393                     as any other web applications. So it is perfectly possible to run two
 394                     JABAWS instances from the same server. Just make two different contexts
 395                     on your application server and unpack JABAWS in both of them. For example
 396                     if your server name is http://www.align.ac.uk, and the context names are
 397                     public and private. Than one group of users could be given a URL
 398                     http://www.align.ac.uk/public and another http://www.align.ac.uk/private.
 399                     These contexts will be served by two independent JABAWS instances, and
 400                     could be configured differently. If you keep local engine enabled, make
 401                     sure you reduce the number of threads local engine is allowed to use to
 402                     avoid overloading the server. Alternatively two completely separate web
 403                     application server instances (e.g. Apache-Tomcat) could be used. This will
 404                     give you a better resilience and more flexibility in memory settings.
 405                 </p>
 406             </div>
 407         </div>
 408     </div>
 409 </div>
 410 <div class="row" id="nocluster">
 411     <div class="col-md-12">
 412         <div class="panel panel-default">
 413             <div class="panel panel-heading">
 414                 <h1 class="panel-title">JABAWS on a single server</h1>
 415             </div>
 416             <div class="panel-body">
 417                 <p class="justify">
 418                     You can run  JABAWS on a single server. Obviously the capacity will be
 419                     limited, but it may be sufficient for a small lab. Installed on a single
 420                     server, JABAWS executes tasks in parallel, so the more cores the server has
 421                     the more requests it will be able to handle.
 422                 </p>
 423             </div>
 424         </div>
 425     </div>
 426 </div>
 427 <div class="row" id="clustsubsys">
 428     <div class="col-md-12">
 429         <div class="panel panel-default">
 430             <div class="panel panel-heading">
 431                 <h1 class="panel-title">JABAWS supported cluster batch management systems</h1>
 432             </div>
 433             <div class="panel-body">
 434                 <p class="justify">
 435                     JABAWS uses <a href="http://drmaa.org/">DRMAA</a> v. 1.0 library to send and manage jobs
 436                     on the cluster. DRMAA supports many different cluster job management systems. Namely Sun
 437                     Grid Engine, Condor, PBS, GridWay, Globus 2/4, PBSPro, LSF. For up to date information
 438                     please consult DRMAA web site. We found that DRMAA implementation differ from platform
 439                     to platform and were trying to use only the basic functions. We have only tested JABAWS
 440                     on Sun Grid Engine v 6.2. Please let use know if you have any experience of running JABAWS
 441                     on other platforms.
 442                 </p>
 443             </div>
 444         </div>
 445     </div>
 446 </div>
 447 <div class="row" id="tomstopundeploy">
 448     <div class="col-md-12">
 449         <div class="panel panel-default">
 450             <div class="panel panel-heading">
 451                 <h1 class="panel-title">Manually deploying JABAWS application on Apache-Tomcat</h1>
 452             </div>
 453             <div class="panel-body">
 454                 <p class="justify">
 455                     To stop Tomcat from automatically undeploying your application if the war file is
 456                     removed use an explicit application descriptor. It could come in different flavors,
 457                     the one we prefer is to drop a context descriptor file into
 458                     <em2>&lt;tomcatRoot&gt;conf/Catalina/localhost</em2> directory.
 459                     Name your context file the same as your application folder e.g. if your
 460                     JABAWS resides in webapps/jabaws folder, then call the context file jabaws.xml.
 461                     Below is an example of content this file might have.
 462                 </p>
 463                 <pre><code class="xml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
 464 &lt;Context antiResourceLocking=&quot;false&quot; privileged=&quot;true&quot; /&gt;</code></pre>
 465                 <p class="justify">
 466                     This should be sufficient to prevent Tomcat from removing your JABAWS from WEBAPPS.
 467                     For more information about the Tomcat deployer
 468                     <a href="http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html">read
 469                         this documentation on the Apache-Tomcat web site</a>.
 470                 </p>
 471             </div>
 472         </div>
 473     </div>
 474 </div>
 475 <div class="row" id="tomdeploy">
 476     <div class="col-md-12">
 477         <div class="panel panel-default">
 478             <div class="panel panel-heading">
 479                 <h1 class="panel-title">Apache-Tomcat fails to deploy jabaws.war file</h1>
 480             </div>
 481             <div class="panel-body">
 482                 <ul>
 483                     <li>Make sure Tomcat has sufficient access rights to read your war file. </li>
 484                     <li>Restart the Tomcat, sometimes it will not restart after the new war file
 485                         is added without restart</li>
 486                     <li>If Tomcat still refuses to unpack the war file, unpack it manually into
 487                         web application folder (the war file is just a zip archive). Restart the
 488                         Tomcat.</li>
 489                 </ul>
 490             </div>
 491         </div>
 492     </div>
 493 </div>
 494
 495 <jsp:include page="template_footer.jsp" />