website/docs/v_2_2_0/getting_started.html

   1
   2
   3 <!DOCTYPE html>
   4 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
   5 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
   6 <head>
   7   <meta charset="utf-8">
   8
   9   <meta name="viewport" content="width=device-width, initial-scale=1.0">
  10
  11   <title>Getting Started &mdash; JABAWS 2.2 documentation</title>
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29     <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  30
  31
  32
  33
  34
  35         <link rel="index" title="Index"
  36               href="genindex.html"/>
  37         <link rel="search" title="Search" href="search.html"/>
  38     <link rel="top" title="JABAWS 2.2 documentation" href="index.html"/>
  39         <link rel="next" title="Included Tools" href="included_tools.html"/>
  40         <link rel="prev" title="Welcome to JABAWS’s documentation!" href="index.html"/>
  41
  42
  43   <script src="_static/js/modernizr.min.js"></script>
  44
  45 </head>
  46
  47 <body class="wy-body-for-nav" role="document">
  48
  49
  50   <div class="wy-grid-for-nav">
  51
  52
  53     <nav data-toggle="wy-nav-shift" class="wy-nav-side">
  54       <div class="wy-side-scroll">
  55         <div class="wy-side-nav-search">
  56
  57
  58
  59             <a href="index.html" class="icon icon-home"> JABAWS
  60
  61
  62
  63           </a>
  64
  65
  66
  67
  68               <div class="version">
  69                 2.2
  70               </div>
  71
  72
  73
  74
  75 <div role="search">
  76   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
  77     <input type="text" name="q" placeholder="Search docs" />
  78     <input type="hidden" name="check_keywords" value="yes" />
  79     <input type="hidden" name="area" value="default" />
  80   </form>
  81 </div>
  82
  83
  84         </div>
  85
  86         <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
  87
  88
  89
  90
  91
  92
  93               <p class="caption"><span class="caption-text">Contents:</span></p>
  94 <ul class="current">
  95 <li class="toctree-l1 current"><a class="current reference internal" href="#">Getting Started</a><ul>
  96 <li class="toctree-l2"><a class="reference internal" href="#jabaws-benefits">JABAWS Benefits</a></li>
  97 <li class="toctree-l2"><a class="reference internal" href="#jabaws-distributions">JABAWS Distributions</a><ul>
  98 <li class="toctree-l3"><a class="reference internal" href="#jalview-and-the-jabaws-public-server">Jalview and the JABAWS Public Server</a></li>
  99 <li class="toctree-l3"><a class="reference internal" href="#command-line-client-cli">Command Line Client (CLI)</a></li>
 100 <li class="toctree-l3"><a class="reference internal" href="#web-application-archive-war">Web Application aRchive (WAR)</a></li>
 101 <li class="toctree-l3"><a class="reference internal" href="#virtual-appliance-va">Virtual Appliance (VA)</a></li>
 102 </ul>
 103 </li>
 104 </ul>
 105 </li>
 106 <li class="toctree-l1"><a class="reference internal" href="included_tools.html">Included Tools</a></li>
 107 <li class="toctree-l1"><a class="reference internal" href="client.html">Command Line Client (CLI)</a></li>
 108 <li class="toctree-l1"><a class="reference internal" href="war.html">Web Application Archive (WAR)</a></li>
 109 <li class="toctree-l1"><a class="reference internal" href="va.html">Virtual Appliance (VA)</a></li>
 110 <li class="toctree-l1"><a class="reference internal" href="advanced.html">Advanced Usage</a></li>
 111 <li class="toctree-l1"><a class="reference internal" href="develop.html">For Developers</a></li>
 112 <li class="toctree-l1"><a class="reference internal" href="stats.html">Usage Statistics</a></li>
 113 <li class="toctree-l1"><a class="reference internal" href="citations.html">Citations</a></li>
 114 <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
 115 </ul>
 116
 117
 118
 119         </div>
 120       </div>
 121     </nav>
 122
 123     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
 124
 125
 126       <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
 127
 128           <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
 129           <a href="index.html">JABAWS</a>
 130
 131       </nav>
 132
 133
 134
 135       <div class="wy-nav-content">
 136         <div class="rst-content">
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153 <div role="navigation" aria-label="breadcrumbs navigation">
 154
 155   <ul class="wy-breadcrumbs">
 156
 157       <li><a href="index.html">Docs</a> &raquo;</li>
 158
 159       <li>Getting Started</li>
 160
 161
 162       <li class="wy-breadcrumbs-aside">
 163
 164
 165             <!-- <a href="_sources/getting_started.rst.txt" rel="nofollow"> View page source</a> -->
 166             <a href="../../">Return to the JABAWS homepage</a>
 167
 168
 169       </li>
 170
 171   </ul>
 172
 173
 174   <hr/>
 175 </div>
 176           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
 177            <div itemprop="articleBody">
 178
 179   <div class="section" id="getting-started">
 180 <h1>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h1>
 181 <p><em>JABAWS</em> 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 <a class="reference external" href="included_tools.html">currently supported programs</a>). Future versions of JABAWS will incorporate other tools.</p>
 182 <p>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 <a class="reference external" href="va.html">JABAWS Virtual Appliance (VA)</a>. It requires no configuration and is simple to install. If you want to install JABAWS for your lab or institution then download the <a class="reference external" href="war.html">JABAWS Web Application aRchive (WAR)</a>. 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 <a class="reference external" href="client.html">JABAWS Command Line Interface (CLI)</a> client is what you need.</p>
 183 <p>The public server based on JABAWS 2.0 at the <a class="reference external" href="http://www.compbio.dundee.ac.uk/">University of Dundee</a> has been in production since November 2013 and serviced over 430,000 jobs for users worldwide.</p>
 184 <hr class="docutils" />
 185 <div class="section" id="jabaws-benefits">
 186 <span id="benefits"></span><h2>JABAWS Benefits<a class="headerlink" href="#jabaws-benefits" title="Permalink to this headline">¶</a></h2>
 187 <ul class="simple">
 188 <li>Can be deployed on most operating systems, as a VMware or compatible Virtual Appliance, as well as a Tomcat Java Web Application.</li>
 189 <li>Comes complete with sources and binaries for all the bioinformatics programs that it runs.</li>
 190 <li>Can operate as a stand alone server or one that submits jobs to a cluster via <cite>DRMAA</cite>.</li>
 191 <li>Easy to access from <a class="reference external" href="http://www.jalview.org/">Jalview</a> using its graphical client, or using the JABAWS command line client.</li>
 192 <li>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&#8217;s server, or the publicly available services at the <a class="reference external" href="http://www.compbio.dundee.ac.uk/">University of Dundee</a>.</li>
 193 <li>Local or intranet installation eliminates any security concerns you might have about sending sensitive data over the internet.</li>
 194 <li>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.</li>
 195 </ul>
 196 <hr class="docutils" />
 197 </div>
 198 <div class="section" id="jabaws-distributions">
 199 <span id="distributions"></span><h2>JABAWS Distributions<a class="headerlink" href="#jabaws-distributions" title="Permalink to this headline">¶</a></h2>
 200 <div class="admonition tip">
 201 <p class="first admonition-title">Tip</p>
 202 <p class="last">To help you choose the JABAWS distribution that better suits your needs read on the quickstart guides below.</p>
 203 </div>
 204 <p><strong>I want to use JABAWS for...</strong></p>
 205 <ul class="simple">
 206 <li><a class="reference internal" href="#jabaws-jalview-public"><span class="std std-ref">Jalview and the JABAWS Public Server</span></a> - Running JABAWS services through Jalview on the JABAWS <em>public</em> server</li>
 207 <li><a class="reference internal" href="#jabaws-cli"><span class="std std-ref">Command Line Client (CLI)</span></a> - Accessing a <em>public</em> or <em>private</em> JABAWS server using the JABAWS client</li>
 208 <li><a class="reference internal" href="#jabaws-war"><span class="std std-ref">Web Application aRchive (WAR)</span></a> - Running JABAWS for my group, lab, or organization on the <em>local</em> infrastructure</li>
 209 <li><a class="reference internal" href="#jabaws-va"><span class="std std-ref">Virtual Appliance (VA)</span></a> - Running JABAWS services through Jalview or the CLI client on a <em>private</em> virtual machine server</li>
 210 </ul>
 211 <hr class="docutils" />
 212 <div class="section" id="jalview-and-the-jabaws-public-server">
 213 <span id="jabaws-jalview-public"></span><h3>Jalview and the JABAWS Public Server<a class="headerlink" href="#jalview-and-the-jabaws-public-server" title="Permalink to this headline">¶</a></h3>
 214 <p><a class="reference external" href="http://www.jalview.org/">Jalview</a>, a multiple sequence alignment and analysis application, is a good example of a graphical JABAWS client. This client uses the same functionality as the <a class="reference external" href="client.html">JABAWS Command Line Interface (CLI)</a> 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 <a class="reference external" href="http://www.jalview.org/">Jalview</a> and run any of the methods provided under the &#8216;Web Service&#8217; 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 <a class="reference external" href="va.html">JABAWS Virtual Appliance (VA)</a> or configure the <a class="reference external" href="war.html">JABAWS Web Application aRchive (WAR)</a> in your infrastructure.</p>
 215 <a class="reference internal image-reference" href="_images/aligment.png"><img alt="_images/aligment.png" class="align-left" src="_images/aligment.png" style="width: 608.0px; height: 318.0px;" /></a>
 216 <hr class="docutils" />
 217 </div>
 218 <div class="section" id="command-line-client-cli">
 219 <span id="jabaws-cli"></span><h3>Command Line Client (CLI)<a class="headerlink" href="#command-line-client-cli" title="Permalink to this headline">¶</a></h3>
 220 <p>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&#8217;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 <a class="reference external" href="client.html">CLI documentation pages</a>, but a brief instructions are given below:</p>
 221 <ol class="arabic">
 222 <li><p class="first">Download the <a class="reference external" href="../download.jsp#client">Client Jar file</a></p>
 223 </li>
 224 <li><p class="first">Download and install <a class="reference external" href="http://www.oracle.com/technetwork/java/javase/downloads/jre7-downloads-1880261.html">Java</a> (version 1.7)</p>
 225 </li>
 226 <li><p class="first">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:</p>
 227 <blockquote>
 228 <div><div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">java</span> <span class="o">-</span><span class="n">jar</span> <span class="n">jabaws</span><span class="o">-</span><span class="n">full</span><span class="o">-</span><span class="n">client</span><span class="o">-</span><span class="mf">2.2</span><span class="o">.</span><span class="mf">0.</span><span class="n">jar</span>
 229 </pre></div>
 230 </div>
 231 </div></blockquote>
 232 </li>
 233 </ol>
 234 <p>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 <a class="reference external" href="develop.html#accessing-jabaws-from-your-program">documentation pages</a>.</p>
 235 <hr class="docutils" />
 236 </div>
 237 <div class="section" id="web-application-archive-war">
 238 <span id="jabaws-war"></span><h3>Web Application aRchive (WAR)<a class="headerlink" href="#web-application-archive-war" title="Permalink to this headline">¶</a></h3>
 239 <p>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 <a class="reference external" href="war.html">WAR documentation pages</a>, but brief instructions are given below:</p>
 240 <ol class="arabic">
 241 <li><p class="first">Download the <a class="reference external" href="../download.jsp#war">JABAWS WAR file</a></p>
 242 </li>
 243 <li><p class="first">Download and install <a class="reference external" href="http://tomcat.apache.org/download-80.cgi">Apache-Tomcat</a></p>
 244 <blockquote>
 245 <div><p>You will need at least Tomcat version 5.5 of (we would recommend version 8.5) and at least <cite>Java</cite> 1.7 (i.e. JAVA 7).</p>
 246 </div></blockquote>
 247 </li>
 248 <li><p class="first">Drop the JABAWS WAR file into <code class="docutils literal"><span class="pre">tomcat/webapps</span></code> directory.</p>
 249 </li>
 250 <li><p class="first">(Re)start the Tomcat.</p>
 251 </li>
 252 <li><p class="first">Once the tomcat has started, it should automatically unpack the WAR into the webapps directory (if it doesn&#8217;t, simply unpack the WAR archive).</p>
 253 </li>
 254 <li><p class="first">If you are on Mac or other unix-like architecture with GNU compilers available or you&#8217;d like to get a maximum performance</p>
 255 <blockquote>
 256 <div><p><code class="docutils literal"><span class="pre">cd</span></code> to <code class="docutils literal"><span class="pre">webapps/jabaws/binaries/src/</span></code> and execute <code class="docutils literal"><span class="pre">./compilebin.sh</span></code> script to compile all binaries JABAWS depends on.</p>
 257 </div></blockquote>
 258 </li>
 259 </ol>
 260 <p><strong>Testing</strong></p>
 261 <p>You can test that your JABAWS server is working in several ways.</p>
 262 <ol class="arabic">
 263 <li><p class="first">Visit Services Status page available from the JABAWS main page using your web browser.</p>
 264 </li>
 265 <li><p class="first">If you are working on the command line, then use the command line client shipped with the JABAWS war to test it by running:</p>
 266 <blockquote>
 267 <div><blockquote>
 268 <div><div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">java</span> <span class="o">-</span><span class="n">jar</span> <span class="o">&lt;</span><span class="n">Path</span> <span class="n">to</span> <span class="n">tomcat</span> <span class="n">WebApp</span> <span class="n">directory</span><span class="o">&gt;/</span><span class="n">jabaws</span><span class="o">/</span><span class="n">WEB</span><span class="o">-</span><span class="n">INF</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">jabaws</span><span class="o">-</span><span class="n">client</span><span class="o">.</span><span class="n">jar</span> <span class="o">-</span><span class="n">h</span><span class="o">=</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span><span class="mi">8080</span><span class="o">/</span><span class="n">jabaws</span>
 269 </pre></div>
 270 </div>
 271 </div></blockquote>
 272 <p>In this example we assumed that your JABAWS server URL is <code class="docutils literal"><span class="pre">http://localhost:8080</span></code> and JABAWS context path is <em>jabaws</em></p>
 273 </div></blockquote>
 274 </li>
 275 <li><p class="first">Alternately, you can point Jalview at your new server:</p>
 276 <blockquote>
 277 <div><ol class="arabic simple">
 278 <li>Launch the desktop version of <a class="reference external" href="http://www.jalview.org/">Jalview</a></li>
 279 <li>Open the Jalview desktop&#8217;s preferences panel (from the Tools-&gt;Preferences menu option), elect the Webservices panel and press the New Service URL button.</li>
 280 <li>Enter the URL for the tomcat server, including the context path for the JABAWS web app (e.g. <a class="reference external" href="http://localhost:8080/jabaws">http://localhost:8080/jabaws</a>).</li>
 281 </ol>
 282 </div></blockquote>
 283 </li>
 284 </ol>
 285 <hr class="docutils" />
 286 </div>
 287 <div class="section" id="virtual-appliance-va">
 288 <span id="jabaws-va"></span><h3>Virtual Appliance (VA)<a class="headerlink" href="#virtual-appliance-va" title="Permalink to this headline">¶</a></h3>
 289 <p>The Virtual Appliance (VA) package allows you to run a JABAWS server installed on <a class="reference external" href="https://www.turnkeylinux.org/tomcat">TurnKey Linux</a> as a virtual machine on your laptop or desktop computer. A complete guide to the JABAWS VA is given in the <a class="reference external" href="va.html">VA documentation pages</a>, but for the impatient, brief instructions are given below:</p>
 290 <p>If you work on Windows, Linux or Unix:</p>
 291 <ol class="arabic simple">
 292 <li>Download <a class="reference external" href="../download.jsp#va">JABAWS Virtual Appliance</a></li>
 293 <li>Download and install <a class="reference external" href="http://www.vmware.com/products/player">VMWare Player</a></li>
 294 <li>Unpack the JABAWS virtual appliance and open it with VMware Player</li>
 295 </ol>
 296 <p>If you work on Mac do the same using <a class="reference external" href="http://www.vmware.com/products/fusion/overview.html">VMware Fusion</a>.</p>
 297 <p><strong>Testing</strong></p>
 298 <p>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.</p>
 299 <p>Alternatively you can use Jalview to complete the testing.</p>
 300 <ol class="arabic simple">
 301 <li>Launch the desktop version of <a class="reference external" href="http://www.jalview.org/">Jalview</a></li>
 302 <li>Open the Jalview desktop&#8217;s preferences panel (from the Tools-&gt;Preferences menu option), select the <code class="docutils literal"><span class="pre">Webservices</span></code> panel and press the <code class="docutils literal"><span class="pre">New</span> <span class="pre">Service</span> <span class="pre">URL</span></code> button.</li>
 303 <li>Enter the JABAWS URL for your new server. This is shown once the appliance is booted up.</li>
 304 </ol>
 305 </div>
 306 </div>
 307 </div>
 308
 309
 310            </div>
 311            <div class="articleComments">
 312
 313            </div>
 314           </div>
 315           <footer>
 316
 317     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 318
 319         <a href="included_tools.html" class="btn btn-neutral float-right" title="Included Tools" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
 320
 321
 322         <a href="index.html" class="btn btn-neutral" title="Welcome to JABAWS’s documentation!" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
 323
 324     </div>
 325
 326
 327   <hr/>
 328
 329   <div role="contentinfo">
 330     <p><a href="../../">JABAWS 2.2</a>
 331         &copy; Copyright 2017, Peter Troshin, Alexander Sherstnev, Jim Procter, Daniel Barton, Fábio Madeira, Alexey Drozdetskiy, Suzanne Duce and Geoff Barton.
 332
 333     </p>
 334   </div>
 335   Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
 336
 337 </footer>
 338         </div>
 339       </div>
 340
 341     </section>
 342
 343   </div>
 344
 345
 346
 347
 348
 349     <script type="text/javascript">
 350         var DOCUMENTATION_OPTIONS = {
 351             URL_ROOT:'./',
 352             VERSION:'2.2',
 353             LANGUAGE:'None',
 354             COLLAPSE_INDEX:false,
 355             FILE_SUFFIX:'.html',
 356             HAS_SOURCE:  true,
 357             SOURCELINK_SUFFIX: '.txt'
 358         };
 359     </script>
 360       <script type="text/javascript" src="_static/jquery.js"></script>
 361       <script type="text/javascript" src="_static/underscore.js"></script>
 362       <script type="text/javascript" src="_static/doctools.js"></script>
 363
 364
 365
 366
 367
 368     <script type="text/javascript" src="_static/js/theme.js"></script>
 369
 370
 371
 372
 373   <script type="text/javascript">
 374       jQuery(function () {
 375           SphinxRtdTheme.StickyNav.enable();
 376       });
 377   </script>
 378
 379
 380 </body>
 381 </html>