1 <%--<?xml version="1.0" encoding="ISO-8859-1" ?>--%>
2 <%--<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>--%>
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" %>
10 <c:import url="../template_header.jsp" >
11 <c:param name="title">Documentation</c:param>
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>
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>
25 <div class="panel-body">
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>
41 <!--<p class="justify">-->
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>
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
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
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.
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>.
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.
78 To run JABAWS on the cluster you must have shared disk space accessible from
82 <p class="text-right">
83 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
95 <div class="panel-body">
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><tomcat server root>/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>.
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
122 <p class="text-right">
123 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
135 <div class="panel-body">
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.
148 <p class="text-right">
149 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
161 <div class="panel-body">
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>.
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>.
180 <p class="text-right">
181 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
194 <div class="panel-body">
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.
204 <li>In a terminal window, change the working directory to <em2>binaries/src</em2>
207 <li>execute the <em2>compilebin.sh</em2> script,<br />
209 <pre><code class="bash">chmod +x compilebin.sh; compilebin.sh > compilebin.out;</code></pre>
211 <pre><code class="bash">sh compilebin.sh > compilebin.out</code></pre>
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.
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.
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.
235 <p class="text-right">
236 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
249 <div class="panel-body">
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>
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>
270 <p class="text-right">
271 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
284 <div class="panel-body">
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.
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>
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>
311 <div class="panel-body">
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>
317 <strong>Using JABAWS service status checker</strong>
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.
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"><jabaws_server>/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"><jabaws_server>/HttpCodeResponseServiceStatus/ClustalWS</code></pre>
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.
338 <strong>Using command line client</strong>
341 Alternatively, you should be able to use the test program which can be found in <webapplicationpath>/WEB-INF/lib/jabaws-client.jar file. To run the tests type:<span class="code"> java -jar jabaws-client.jar -h=<Your web application server host name, port and JABAWS context path></span></p>
343 For example to test all JABAWS web services on host myhost.compbio.ac.uk type:
345 <pre><code class="bash">java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws</code></pre>
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.
353 An example of the report testing tool produces for operating web service looks like this:
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
367 Queering Local Engine Limits...OK
368 Check is completed service MuscleWS IS WORKING</code></pre>
370 An example of the response of a web service which is deployed but is not operating is below:
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>
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>
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>
390 <div class="panel-body">
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.
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>
416 <div class="panel-body">
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.
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>
433 <div class="panel-body">
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
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>
453 <div class="panel-body">
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><tomcatRoot>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.
463 <pre><code class="xml"><?xml version="1.0" encoding="UTF-8"?>
464 <Context antiResourceLocking="false" privileged="true" /></code></pre>
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>.
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>
481 <div class="panel-body">
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
495 <jsp:include page="../template_footer.jsp" />