doc/user/cwl/cwl-runner.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Running an Arvados workflow"
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 {% include 'what_is_cwl' %}
  13
  14 {% include 'tutorial_expectations' %}
  15
  16 This tutorial will demonstrate how to submit a workflow at the command line using @arvados-cwl-runner@.
  17
  18 h2. Running arvados-cwl-runner
  19
  20 h3. Get the example files
  21
  22 The tutorial files are located in the documentation section of the Arvados source repository, which can be found on "git.arvados.org":https://git.arvados.org/arvados.git/tree/HEAD:/doc/user/cwl/bwa-mem or "github":https://github.com/arvados/arvados/tree/master/doc/user/cwl/bwa-mem
  23
  24 <notextile>
  25 <pre><code>~$ <span class="userinput">git clone https://git.arvados.org/arvados.git</span>
  26 ~$ <span class="userinput">cd arvados/doc/user/cwl/bwa-mem</span>
  27 </code></pre>
  28 </notextile>
  29
  30 The tutorial data is hosted on "https://playground.arvados.org":https://playground.arvados.org (also referred to by the identifier *pirca*).  If you are using a different Arvados instance, you may need to copy the data to your own instance.  One way to do this is with "arv-copy":{{site.baseurl}}/user/topics/arv-copy.html (this requires signing up for a free playground.arvados.org account).
  31
  32 <notextile>
  33 <pre><code>~$ <span class="userinput">arv-copy --src pirca --dst settings 2463fa9efeb75e099685528b3b9071e0+438</span>
  34 ~$ <span class="userinput">arv-copy --src pirca --dst settings ae480c5099b81e17267b7445e35b4bc7+180</span>
  35 </code></pre>
  36 </notextile>
  37
  38 If you do not wish to create an account on "https://playground.arvados.org":https://playground.arvados.org, you may download the files anonymously and upload them to your local Arvados instance:
  39
  40 "https://collections.pirca.arvadosapi.com/c=2463fa9efeb75e099685528b3b9071e0+438/":https://collections.pirca.arvadosapi.com/c=2463fa9efeb75e099685528b3b9071e0+438/
  41
  42 "https://collections.pirca.arvadosapi.com/c=ae480c5099b81e17267b7445e35b4bc7+180/":https://collections.pirca.arvadosapi.com/c=ae480c5099b81e17267b7445e35b4bc7+180/
  43
  44 h2. Submitting a workflow to an Arvados cluster
  45
  46 h3. Submit a workflow and wait for results
  47
  48 Use @arvados-cwl-runner@ to submit CWL workflows to Arvados.  After submitting the job, it will wait for the workflow to complete and print out the final result to standard output.
  49
  50 *Note:* Once submitted, the workflow runs entirely on Arvados, so even if you log out, the workflow will continue to run.  However, if you interrupt @arvados-cwl-runner@ with control-C it will cancel the workflow.
  51
  52 <notextile>
  53 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner bwa-mem.cwl bwa-mem-input.yml</span>
  54 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  55 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
  56 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to zzzzz-4zz18-h7ljh5u76760ww2
  57 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job zzzzz-8i9sb-fm2n3b1w0l6bskg
  58 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Running
  59 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Complete
  60 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
  61 {
  62     "aligned_sam": {
  63         "location": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
  64         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
  65         "class": "File",
  66         "size": 30738986
  67     }
  68 }
  69 </code></pre>
  70 </notextile>
  71
  72 h3. Referencing files
  73
  74 When running a workflow on an Arvados cluster, the input files must be stored in Keep.  There are several ways this can happen.
  75
  76 A URI reference to Keep uses the @keep:@ scheme followed by either the portable data hash or UUID of the collection and then the location of the file inside the collection.  For example, @keep:2463fa9efeb75e099685528b3b9071e0+438/19.fasta.bwt@ or @keep:zzzzz-4zz18-zzzzzzzzzzzzzzz/19.fasta.bwt@.
  77
  78 If you reference a file in "arv-mount":{{site.baseurl}}/user/tutorials/tutorial-keep-mount-gnu-linux.html, such as @/home/example/keep/by_id/2463fa9efeb75e099685528b3b9071e0+438/19.fasta.bwt@, then @arvados-cwl-runner@ will automatically determine the appropriate Keep URI reference.
  79
  80 If you reference a local file which is not in @arv-mount@, then @arvados-cwl-runner@ will upload the file to Keep and use the Keep URI reference from the upload.
  81
  82 You can also execute CWL files directly from Keep:
  83
  84 <notextile>
  85 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner keep:655c6cd07550151b210961ed1d3852cf+57/bwa-mem.cwl bwa-mem-input.yml</span>
  86 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  87 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to zzzzz-4zz18-h7ljh5u76760ww2
  88 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job zzzzz-8i9sb-fm2n3b1w0l6bskg
  89 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Running
  90 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Complete
  91 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
  92 {
  93     "aligned_sam": {
  94         "location": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
  95         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
  96         "class": "File",
  97         "size": 30738986
  98     }
  99 }
 100 </code></pre>
 101 </notextile>
 102
 103 h3. Work reuse
 104
 105 Workflows submitted with @arvados-cwl-runner@ will take advantage of Arvados job reuse.  If you submit a workflow which is identical to one that has run before, it will short cut the execution and return the result of the previous run.  This also applies to individual workflow steps.  For example, a two step workflow where the first step has run before will reuse results for first step and only execute the new second step.  You can disable this behavior with @--disable-reuse@.
 106
 107 h3. Command line options
 108
 109 See "Using arvados-cwl-runner":{{site.baseurl}}/user/cwl/cwl-run-options.html
 110
 111 h2(#setup). Setting up arvados-cwl-runner
 112
 113 By default, the @arvados-cwl-runner@ is installed on Arvados shell nodes.  If you want to submit jobs from somewhere else, such as your workstation, you may install @arvados-cwl-runner@ using @pip@:
 114
 115 <notextile>
 116 <pre><code>~$ <span class="userinput">virtualenv ~/venv</span>
 117 ~$ <span class="userinput">. ~/venv/bin/activate</span>
 118 ~$ <span class="userinput">pip install -U setuptools</span>
 119 ~$ <span class="userinput">pip install arvados-cwl-runner</span>
 120 </code></pre>
 121 </notextile>
 122
 123 h3. Check Docker access
 124
 125 In order to pull and upload Docker images, @arvados-cwl-runner@ requires access to Docker.  You do not need Docker if the Docker images you intend to use are already available in Arvados.
 126
 127 You can determine if you have access to Docker by running @docker version@:
 128
 129 <notextile>
 130 <pre><code>~$ <span class="userinput">docker version</span>
 131 Client:
 132  Version:      1.9.1
 133  API version:  1.21
 134  Go version:   go1.4.2
 135  Git commit:   a34a1d5
 136  Built:        Fri Nov 20 12:59:02 UTC 2015
 137  OS/Arch:      linux/amd64
 138
 139 Server:
 140  Version:      1.9.1
 141  API version:  1.21
 142  Go version:   go1.4.2
 143  Git commit:   a34a1d5
 144  Built:        Fri Nov 20 12:59:02 UTC 2015
 145  OS/Arch:      linux/amd64
 146 </code></pre>
 147 </notextile>
 148
 149 If this returns an error, contact the sysadmin of your cluster for assistance.