docs/war.rst

   1 Web Application Archive (WAR)
   2 =============================
   3
   4 JABAWS Web Application aRchive can run on any host operating system that supports `Java`_ and `Apache-Tomcat`_. JABAWS requires a Java web application server compliant with version 2.4 of the Java Servlet specification, and a `Java`_ 7 runtime environment. We recommend using an official Oracle Java 7 runtime environment, and `Apache-Tomcat`_ web application server version 8.5, but older Tomcat versions above 5.5 will work too.
   5
   6 .. danger:: The JABAWS WAR is not generally compatible with older Mac systems based on the PowerPC architecture, since Java 1.7 is not available to run JABAWS.
   7
   8 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. JABAWS comes with pre-compiled MS Windows and Linux x86 binaries, as well as the source code and build scripts necessary to recompile them.
   9
  10 To run JABAWS on the cluster you must have shared disk space accessible from all cluster nodes.
  11
  12
  13 ------------
  14
  15 .. _war_installing:
  16
  17 Installing
  18 ----------
  19
  20 .. tip:: Check if you are running the recommended versions of Java and Apache-Tomcat.
  21
  22 JABAWS is distributed as a web application archive (WAR). To deploy JABAWS in `Apache-Tomcat`_ - simply drop the war file into the webapps directory of a running Tomcat, and it will do the rest. If you used this deployment procedure, do not remove 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 ``localhost:8080`` and *jaba.war* file is put into the ``<tomcat server root>/webapps`` directory, the deployed application from the jabaws.war file then can be accessed by this URL ``http://localhost:8080/jabaws``.
  23
  24 For any other web application server, please follow your server's specific deployment procedure for 'WAR' files. If you install JABAWS on a MS Windows machine, then at this point your JABAWS installation will already be up and running, and you can try its services out as described here in the `documentation`_. If you install JABAWS on Linux you will need to compile the binaries for your system and set an executable flag for binaries (`more details here`_ and `here`_).
  25
  26
  27 ------------
  28
  29 .. _war_usage:
  30
  31 Usage
  32 -----
  33
  34 **Running many JABAWS instances on the same server**
  35
  36
  37 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.
  38
  39 **JABAWS on a single server**
  40
  41 You can run JABAWS on a single server. Obviously the capacity will be limited, but it 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.
  42
  43
  44 **JABAWS supported cluster batch management systems**
  45
  46 JABAWS uses `DRMAA`_ v1.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.
  47
  48
  49 ------------
  50
  51 .. _war_troubleshooting:
  52
  53 Troubleshooting
  54 ---------------
  55
  56 **If Apache-Tomcat fails to deploy jabaws.war file:**
  57
  58 * Make sure Tomcat has sufficient access rights to read your war file.
  59 * Restart the Tomcat, sometimes it will not restart after the new war file is added without restart
  60 * 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.
  61
  62 **If Tomcat undeployes your application:**
  63
  64 If the war file is automatically removed by Tomcat use an explicit application descriptor. Add a context descriptor file into ``<tomcatRoot>conf/Catalina/localhost`` directory. Name your context file the same as your application folder e.g. if your JABAWS resides in ``webapps/jabaws`` folder, then call the context file jabaws.xml. Below is an example of content this file might have.
  65
  66 .. code-block:: xml
  67
  68     <?xml version="1.0" encoding="UTF-8"?>
  69     <Context antiResourceLocking="false" privileged="true" />
  70
  71 This should be sufficient to prevent Tomcat from removing your JABAWS from WEBAPPS. For more information about the Tomcat deployer read this documentation on the Apache-Tomcat web site.
  72
  73
  74 .. links
  75 .. _Java: http://www.oracle.com/technetwork/java/javase/downloads/jre7-downloads-1880261.html
  76 .. _Apache-Tomcat: http://tomcat.apache.org/download-80.cgi
  77 .. _DRMAA: http://www.drmaa.org/
  78 .. _documentation: advanced.html#testing-the-jabaws-server
  79 .. _more details here: advanced.html#pre-compiled-binaries
  80 .. _here: advanced.html#recompiling-binaries-for-your-system