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

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Running an Arvados workflow"
   5 ...
   6
   7 {% include 'what_is_cwl' %}
   8
   9 {% include 'tutorial_expectations' %}
  10
  11 {% include 'notebox_begin' %}
  12
  13 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.":#setup
  14
  15 {% include 'notebox_end' %}
  16
  17 This tutorial will demonstrate how to submit a workflow at the command line using @arvados-cwl-runner@.
  18
  19 h3. Get the example files
  20
  21 The tutorial files are located in the "documentation section of the Arvados source repository:":https://github.com/curoverse/arvados/tree/master/doc/user/cwl/bwa-mem
  22
  23 <notextile>
  24 <pre><code>~$ <span class="userinput">git clone https://github.com/curoverse/arvados</span>
  25 ~$ <span class="userinput">cd arvados/doc/user/cwl/bwa-mem</span>
  26 </code></pre>
  27 </notextile>
  28
  29 The tutorial data is hosted on "https://cloud.curoverse.com":https://cloud.curoverse.com (also referred to by the identifier *qr1hi*).  If you are using a different Arvados instance, you may need to copy the data to your own instance.  The easiest way to do this is with "arv-copy":{{site.baseurl}}/user/topics/arv-copy.html (this requires signing up for a free cloud.curoverse.com account).
  30
  31 <notextile>
  32 <pre><code>~$ <span class="userinput">arv-copy --src qr1hi --dst settings 2463fa9efeb75e099685528b3b9071e0+438</span>
  33 ~$ <span class="userinput">arv-copy --src qr1hi --dst settings ae480c5099b81e17267b7445e35b4bc7+180</span>
  34 ~$ <span class="userinput">arv-copy --src qr1hi --dst settings 655c6cd07550151b210961ed1d3852cf+57</span>
  35 </code></pre>
  36 </notextile>
  37
  38 If you do not wish to create an account on "https://cloud.curoverse.com":https://cloud.curoverse.com, you may download the files anonymously and upload them to your local Arvados instance:
  39
  40 "https://cloud.curoverse.com/collections/2463fa9efeb75e099685528b3b9071e0+438":https://cloud.curoverse.com/collections/2463fa9efeb75e099685528b3b9071e0+438
  41
  42 "https://cloud.curoverse.com/collections/ae480c5099b81e17267b7445e35b4bc7+180":https://cloud.curoverse.com/collections/ae480c5099b81e17267b7445e35b4bc7+180
  43
  44 "https://cloud.curoverse.com/collections/655c6cd07550151b210961ed1d3852cf+57":https://cloud.curoverse.com/collections/655c6cd07550151b210961ed1d3852cf+57
  45
  46 h2. Submitting a workflow to an Arvados cluster
  47
  48 h3. Submit a workflow and wait for results
  49
  50 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.
  51
  52 *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.
  53
  54 <notextile>
  55 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner bwa-mem.cwl bwa-mem-input.yml</span>
  56 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  57 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
  58 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
  59 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
  60 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
  61 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
  62 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
  63 {
  64     "aligned_sam": {
  65         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
  66         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
  67         "class": "File",
  68         "size": 30738986
  69     }
  70 }
  71 </code></pre>
  72 </notextile>
  73
  74 h3. Submit a workflow with no waiting
  75
  76 To submit a workflow and exit immediately, use the @--no-wait@ option.  This will submit the workflow to Arvados, print out the UUID of the job that was submitted to standard output, and exit.
  77
  78 <notextile>
  79 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --no-wait bwa-mem.cwl bwa-mem-input.yml</span>
  80 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  81 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Upload local files: "bwa-mem.cwl"
  82 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Uploaded to qr1hi-4zz18-eqnfwrow8aysa9q
  83 2016-06-30 15:07:52 arvados.cwl-runner[12480] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
  84 qr1hi-8i9sb-fm2n3b1w0l6bskg
  85 </code></pre>
  86 </notextile>
  87
  88 h2. Work reuse
  89
  90 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@.
  91
  92 h2. Referencing files
  93
  94 When running a workflow on an Arvados cluster, the input files must be stored in Keep.  There are several ways this can happen.
  95
  96 A URI reference to Keep uses the @keep:@ scheme followed by the portable data hash, collection size, and path to the file inside the collection.  For example, @keep:2463fa9efeb75e099685528b3b9071e0+438/19.fasta.bwt@.
  97
  98 If you reference a file in "arv-mount":{{site.baseurl}}/user/tutorials/tutorial-keep-mount.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.
  99
 100 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.
 101
 102 You can also execute CWL files directly from Keep:
 103
 104 <notextile>
 105 <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>
 106 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 107 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
 108 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
 109 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
 110 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
 111 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 112 {
 113     "aligned_sam": {
 114         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 115         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 116         "class": "File",
 117         "size": 30738986
 118     }
 119 }
 120 </code></pre>
 121 </notextile>
 122
 123 h2(#setup). Setting up arvados-cwl-runner
 124
 125 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@:
 126
 127 <notextile>
 128 <pre><code>~$ <span class="userinput">virtualenv ~/venv</span>
 129 ~$ <span class="userinput">. ~/venv/bin/activate</span>
 130 ~$ <span class="userinput">pip install -U setuptools</span>
 131 ~$ <span class="userinput">pip install arvados-cwl-runner</span>
 132 </code></pre>
 133 </notextile>
 134
 135 h3. Check Docker access
 136
 137 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 Aravdos.
 138
 139 You can determine if you have access to Docker by running @docker version@:
 140
 141 <notextile>
 142 <pre><code>~$ <span class="userinput">docker version</span>
 143 Client:
 144  Version:      1.9.1
 145  API version:  1.21
 146  Go version:   go1.4.2
 147  Git commit:   a34a1d5
 148  Built:        Fri Nov 20 12:59:02 UTC 2015
 149  OS/Arch:      linux/amd64
 150
 151 Server:
 152  Version:      1.9.1
 153  API version:  1.21
 154  Go version:   go1.4.2
 155  Git commit:   a34a1d5
 156  Built:        Fri Nov 20 12:59:02 UTC 2015
 157  OS/Arch:      linux/amd64
 158 </code></pre>
 159 </notextile>
 160
 161 If this returns an error, contact the sysadmin of your cluster for assistance.