website/docs/_sources/getting_started.rst.txt

   1 Getting Started
   2 ===============
   3
   4 *JABAWS* is a collection of web services for bioinformatics, and currently provides services that make it easy to access well-known multiple sequence alignment and protein disorder prediction programs (see the list of `currently supported programs`_). Future versions of JABAWS will incorporate other tools.
   5
   6 JABAWS consists of a server and a client, but unlike most bioinformatics web-service systems, you can download and run both parts on your own computer! If you want a server just for yourself, then download and install the `JABAWS Virtual Appliance (VA)`_. It requires no configuration and is simple to install. If you want to install JABAWS for your lab or institution then download the `JABAWS Web Application aRchive (WAR)`_. It is slightly more complicated to configure but is very straightforward too. Finally, if you want to script against any version of JABAWS or are interested in writing your own client, the `JABAWS Command Line Interface (CLI)`_ client is what you need.
   7
   8 The public server based on JABAWS 2.1 at the `University of Dundee`_ has been in production since October 2013 and serviced over 442,000 jobs for users worldwide.
   9
  10 **New:** You can now run JABAWS with `Docker`_. `Click here to learn more`_.
  11
  12 ------------
  13
  14 .. _benefits:
  15
  16 JABAWS Benefits
  17 ---------------
  18
  19 * Can be deployed on most operating systems, as a VMware or compatible Virtual Appliance, as well as a Tomcat Java Web Application.
  20 * Comes complete with sources and binaries for all the bioinformatics programs that it runs.
  21 * Can operate as a stand alone server or one that submits jobs to a cluster via `DRMAA`.
  22 * Easy to access from `Jalview`_ using its graphical client, or using the JABAWS command line client.
  23 * Clients can submit jobs to any JABAWS servers that they might want to access, such as the one running on your local computer, your lab's server, or the publicly available services at the `University of Dundee`_.
  24 * Local or intranet installation eliminates any security concerns you might have about sending sensitive data over the internet.
  25 * Wide range of configuration options to control size of jobs accepted by a server, and the command line options available for the program run by a service.
  26
  27
  28 ------------
  29
  30 .. _distributions:
  31
  32 JABAWS Distributions
  33 --------------------
  34
  35 .. tip:: To help you choose the JABAWS distribution that better suits your needs read on the quickstart guides below.
  36
  37 **I want to use JABAWS for...**
  38
  39 * :ref:`jabaws-jalview-public` - Running JABAWS services through Jalview on the JABAWS *public* server
  40 * :ref:`jabaws-cli` - Accessing a *public* or *private* JABAWS server using the JABAWS client
  41 * :ref:`jabaws-war` - Running JABAWS for my group, lab, or organization on the *local* infrastructure
  42 * :ref:`jabaws-va` - Running JABAWS services through Jalview or the CLI client on a *private* virtual machine server
  43
  44
  45 ------------
  46
  47 .. _jabaws-jalview-public:
  48
  49 Jalview and the JABAWS Public Server
  50 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  51
  52 `Jalview`_, a multiple sequence alignment and analysis application, is a good example of a graphical JABAWS client. This client uses the same functionality as the `JABAWS Command Line Interface (CLI)`_ client, but instead allows JABAWS services to be accessed in a more user-friendly manner, through a graphical user interface. In this way, this is the easiest way to run JABAWS web services. Simply launch `Jalview`_ and run any of the methods provided under the 'Web Service' menu. Jalview uses the public JABAWS server by default. If you are concerned about privacy or want to run sensitive analysis on your own hardware, you can either setup a local `JABAWS Virtual Appliance (VA)`_ or configure the `JABAWS Web Application aRchive (WAR)`_ in your infrastructure.
  53
  54 .. image:: ../../website/static/img/aligment.png
  55    :height: 318
  56    :width: 608
  57    :scale: 100 %
  58    :align: left
  59
  60 ------------
  61
  62 .. _jabaws-cli:
  63
  64 Command Line Client (CLI)
  65 ~~~~~~~~~~~~~~~~~~~~~~~~~
  66
  67 This is a single Java archive which contains the JABAWS command line interface (CLI) client. It allows anyone who wants to connect to the JABAWS web-services running at the University of Dundee's Public Server, or to run a local private JABAWS server from their own software. You can read more about how to use JABAWS command line (CLI) client given in the `CLI documentation pages`_, but a brief instructions are given below:
  68
  69 1. Download the `Client Jar file`_
  70 2. Download and install `Java`_ (version 1.7)
  71 3. Provided that you have the Java ready to run, you can get command line help by changing to the directory where you downloaded the client jar, and typing:
  72
  73       .. code:: bash
  74
  75             java -jar jabaws-full-client-2.2.0.jar
  76
  77
  78 The JABA Web Services are WS-I compliant. This means that you can access them from any language that has libraries or functions for consuming interoperable SOAP web services. More information on how to develop software that access JABAWS services is provided in the `documentation pages`_.
  79
  80
  81 ------------
  82
  83 .. _jabaws-war:
  84
  85 Web Application aRchive (WAR)
  86 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  87
  88 The JABAWS Web Application aRchive (WAR) is for anyone who wants to run JABAWS for their group, lab or organization, or wants to enable their local JABAWS server to use the cluster or perform very large tasks. Complete documentation is provided in the `WAR documentation pages`_, but brief instructions are given below:
  89
  90 1. Download the `JABAWS WAR file`_
  91 2. Download and install `Apache-Tomcat`_
  92
  93       You will need at least Tomcat version 5.5 of (we would recommend version 8.5) and at least `Java` 1.7 (i.e. JAVA 7).
  94 3. Drop the JABAWS WAR file into ``tomcat/webapps`` directory.
  95 4. (Re)start the Tomcat.
  96 5. Once the tomcat has started, it should automatically unpack the WAR into the webapps directory (if it doesn't, simply unpack the WAR archive).
  97 6. If you are on Mac or other unix-like architecture with GNU compilers available or you'd like to get a maximum performance
  98
  99     ``cd`` to ``webapps/jabaws/binaries/src/`` and execute ``./compilebin.sh`` script to compile all binaries JABAWS depends on.
 100
 101 **Testing**
 102
 103 You can test that your JABAWS server is working in several ways.
 104
 105 1. Visit Services Status page available from the JABAWS main page using your web browser.
 106 2. If you are working on the command line, then use the command line client shipped with the JABAWS war to test it by running:
 107
 108       .. code:: bash
 109
 110             java -jar <Path to tomcat WebApp directory>/jabaws/WEB-INF/lib/jabaws-client.jar -h=http://localhost:8080/jabaws
 111
 112     In this example we assumed that your JABAWS server URL is ``http://localhost:8080`` and JABAWS context path is *jabaws*
 113 3. Alternately, you can point Jalview at your new server:
 114
 115     1. Launch the desktop version of `Jalview`_
 116     2. Open the Jalview desktop's preferences panel (from the Tools->Preferences menu option), elect the Webservices panel and press the New Service URL button.
 117     3. Enter the URL for the tomcat server, including the context path for the JABAWS web app (e.g. http://localhost:8080/jabaws).
 118
 119
 120 ------------
 121
 122 .. _jabaws-va:
 123
 124 Virtual Appliance (VA)
 125 ~~~~~~~~~~~~~~~~~~~~~~
 126
 127 The Virtual Appliance (VA) package allows you to run a JABAWS server installed on `TurnKey Linux`_ as a virtual machine on your laptop or desktop computer. A complete guide to the JABAWS VA is given in the `VA documentation pages`_, but for the impatient, brief instructions are given below:
 128
 129 If you work on Windows, Linux or Unix:
 130
 131 1. Download `JABAWS Virtual Appliance`_
 132 2. Download and install `VMWare Player`_
 133 3. Unpack the JABAWS virtual appliance and open it with VMware Player
 134
 135 If you work on Mac do the same using `VMware Fusion`_.
 136
 137 **Testing**
 138
 139 To check that your JABAWS virtual appliance is working visit the Services Status page available from the main JABAWS menu. For this enter the JABAWS URL for your new server into a web browser. This is shown once the appliance is booted up.
 140
 141 Alternatively you can use Jalview to complete the testing.
 142
 143 1. Launch the desktop version of `Jalview`_
 144 2. Open the Jalview desktop's preferences panel (from the Tools->Preferences menu option), select the ``Webservices`` panel and press the ``New Service URL`` button.
 145 3. Enter the JABAWS URL for your new server. This is shown once the appliance is booted up.
 146
 147
 148 .. links
 149 .. _Jalview: http://www.jalview.org/
 150 .. _currently supported programs: included_tools.html
 151 .. _JABAWS Virtual Appliance (VA): va.html
 152 .. _JABAWS Web Application aRchive (WAR): war.html
 153 .. _JABAWS Command Line Interface (CLI): client.html
 154 .. _TurnKey Linux: https://www.turnkeylinux.org/tomcat
 155 .. _DRMAA: http://www.drmaa.org/
 156 .. _University of Dundee: http://www.compbio.dundee.ac.uk/
 157 .. _Java: http://www.oracle.com/technetwork/java/javase/downloads/jre7-downloads-1880261.html
 158 .. _Client Jar file: ../download.jsp#client
 159 .. _documentation pages: develop.html#accessing-jabaws-from-your-program
 160 .. _CLI documentation pages: client.html
 161 .. _JABAWS WAR file: ../download.jsp#war
 162 .. _Apache-Tomcat: http://tomcat.apache.org/download-80.cgi
 163 .. _WAR documentation pages: war.html
 164 .. _JABAWS Virtual Appliance: ../download.jsp#va
 165 .. _VMWare Player: http://www.vmware.com/products/player
 166 .. _VMWare Fusion: http://www.vmware.com/products/fusion/overview.html
 167 .. _VA documentation pages: va.html
 168 .. _Docker: https://www.docker.com/
 169 .. _Click here to learn more: docker.html