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

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Starting a Workflow at the Command Line"
   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 # "Get the tutorial files":#get-files
  19 # "Submitting a workflow to an Arvados cluster":#submitting
  20 # "Registering a workflow to use in Workbench":#registering
  21 # "Make a workflow file directly executable":#executable
  22
  23 h2(#get-files). Get the tutorial files
  24
  25 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/main/doc/user/cwl/bwa-mem
  26
  27 <notextile>
  28 <pre><code>~$ <span class="userinput">git clone https://git.arvados.org/arvados.git</span>
  29 ~$ <span class="userinput">cd arvados/doc/user/cwl/bwa-mem</span>
  30 </code></pre>
  31 </notextile>
  32
  33 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).
  34
  35 <notextile>
  36 <pre><code>~$ <span class="userinput">arv-copy --src pirca --dst settings 2463fa9efeb75e099685528b3b9071e0+438</span>
  37 ~$ <span class="userinput">arv-copy --src pirca --dst settings ae480c5099b81e17267b7445e35b4bc7+180</span>
  38 </code></pre>
  39 </notextile>
  40
  41 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:
  42
  43 "https://collections.pirca.arvadosapi.com/c=2463fa9efeb75e099685528b3b9071e0+438/":https://collections.pirca.arvadosapi.com/c=2463fa9efeb75e099685528b3b9071e0+438/
  44
  45 "https://collections.pirca.arvadosapi.com/c=ae480c5099b81e17267b7445e35b4bc7+180/":https://collections.pirca.arvadosapi.com/c=ae480c5099b81e17267b7445e35b4bc7+180/
  46
  47 h2(#submitting). Submitting a workflow to an Arvados cluster
  48
  49 h3. Submit a workflow and wait for results
  50
  51 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.
  52
  53 *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.
  54
  55 <notextile>
  56 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner bwa-mem.cwl bwa-mem-input.yml</span>
  57 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  58 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
  59 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to zzzzz-4zz18-h7ljh5u76760ww2
  60 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job zzzzz-8i9sb-fm2n3b1w0l6bskg
  61 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Running
  62 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Complete
  63 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
  64 {
  65     "aligned_sam": {
  66         "location": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
  67         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
  68         "class": "File",
  69         "size": 30738986
  70     }
  71 }
  72 </code></pre>
  73 </notextile>
  74
  75 h3. Referencing files
  76
  77 When running a workflow on an Arvados cluster, the input files must be stored in Keep.  There are several ways this can happen.
  78
  79 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@.
  80
  81 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.
  82
  83 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.
  84
  85 You can also execute CWL files that have been uploaded Keep:
  86
  87 <notextile>
  88 <pre><code>
  89 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-put --portable-data-hash --name "bwa-mem.cwl" bwa-mem.cwl</span>
  90 2020-08-20 13:40:02 arvados.arv_put[12976] INFO: Collection saved as 'bwa-mem.cwl'
  91 f141fc27e7cfa7f7b6d208df5e0ee01b+59
  92 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner keep:f141fc27e7cfa7f7b6d208df5e0ee01b+59/bwa-mem.cwl bwa-mem-input.yml</span>
  93 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  94 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to zzzzz-4zz18-h7ljh5u76760ww2
  95 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job zzzzz-8i9sb-fm2n3b1w0l6bskg
  96 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Running
  97 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Complete
  98 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
  99 {
 100     "aligned_sam": {
 101         "location": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 102         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 103         "class": "File",
 104         "size": 30738986
 105     }
 106 }
 107 </code></pre>
 108 </notextile>
 109
 110 Note: uploading a workflow file to Keep is _not_ the same as registering the workflow for use in Workbench.  See "Registering a workflow to use in Workbench":#registering below.
 111
 112 h3. Work reuse
 113
 114 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@.
 115
 116 h3(#docker). Docker images
 117
 118 Docker images referenced by the workflow must be uploaded to Arvados.  This requires @docker@ to be installed and usable by the user running @arvados-cwl-runner@.  If the image is not present in the local Docker instance, @arvados-cwl-runner@ will first attempt to pull the image using @docker pull@, then upload it.
 119
 120 If there is already a Docker image in Arvados with the same name, it will use the existing image.  In this case, the submitter will not use Docker.
 121
 122 The @--match-submitter-images@ option will check the id of the image in the local Docker instance and compare it to the id of the image already in Arvados with the same name and tag.  If they are different, it will choose the image matching the local image id, which will be uploaded it if necessary.  This helpful for development, if you locally rebuild the image with the 'latest' tag, the @--match-submitter-images@ will ensure that the newer version is used.
 123
 124 h3. Command line options
 125
 126 See "arvados-cwl-runner options":{{site.baseurl}}/user/cwl/cwl-run-options.html
 127
 128 h2(#registering). Registering a workflow to use in Workbench
 129
 130 Use @--create-workflow@ to register a CWL workflow with Arvados.  This enables you to share workflows with other Arvados users, and run them by clicking the <span class="btn btn-sm btn-primary"><i class="fa fa-fw fa-gear"></i> Run a process...</span> button on the Workbench Dashboard and on the command line by UUID.
 131
 132 <notextile>
 133 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --create-workflow bwa-mem.cwl</span>
 134 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 135 2016-07-01 12:21:01 arvados.arv-run[15796] INFO: Upload local files: "bwa-mem.cwl"
 136 2016-07-01 12:21:01 arvados.arv-run[15796] INFO: Uploaded to zzzzz-4zz18-7e0hedrmkuyoei3
 137 2016-07-01 12:21:01 arvados.cwl-runner[15796] INFO: Created template zzzzz-p5p6p-rjleou1dwr167v5
 138 zzzzz-p5p6p-rjleou1dwr167v5
 139 </code></pre>
 140 </notextile>
 141
 142 You can provide a partial input file to set default values for the workflow input parameters.  You can also use the @--name@ option to set the name of the workflow:
 143
 144 <notextile>
 145 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --name "My workflow with defaults" --create-workflow bwa-mem.cwl bwa-mem-template.yml</span>
 146 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 147 2016-07-01 14:09:50 arvados.arv-run[3730] INFO: Upload local files: "bwa-mem.cwl"
 148 2016-07-01 14:09:50 arvados.arv-run[3730] INFO: Uploaded to zzzzz-4zz18-0f91qkovk4ml18o
 149 2016-07-01 14:09:50 arvados.cwl-runner[3730] INFO: Created template zzzzz-p5p6p-0deqe6nuuyqns2i
 150 zzzzz-p5p6p-zuniv58hn8d0qd8
 151 </code></pre>
 152 </notextile>
 153
 154 h3. Running registered workflows at the command line
 155
 156 You can run a registered workflow at the command line by its UUID:
 157
 158 <notextile>
 159 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner pirca-7fd4e-3nqbw08vtjl8ybz --help</span>
 160 INFO /home/peter/work/scripts/venv3/bin/arvados-cwl-runner 2.1.0.dev20200814195416, arvados-python-client 2.1.0.dev20200814195416, cwltool 3.0.20200807132242
 161 INFO Resolved 'pirca-7fd4e-3nqbw08vtjl8ybz' to 'arvwf:pirca-7fd4e-3nqbw08vtjl8ybz#main'
 162 usage: pirca-7fd4e-3nqbw08vtjl8ybz [-h] [--PL PL] [--group_id GROUP_ID]
 163                                    [--read_p1 READ_P1] [--read_p2 READ_P2]
 164                                    [--reference REFERENCE]
 165                                    [--sample_id SAMPLE_ID]
 166                                    [job_order]
 167
 168 positional arguments:
 169   job_order             Job input json file
 170
 171 optional arguments:
 172   -h, --help            show this help message and exit
 173   --PL PL
 174   --group_id GROUP_ID
 175   --read_p1 READ_P1     The reads, in fastq format.
 176   --read_p2 READ_P2     For mate paired reads, the second file (optional).
 177   --reference REFERENCE
 178                         The index files produced by `bwa index`
 179   --sample_id SAMPLE_ID
 180 </code></pre>
 181 </notextile>
 182
 183 h2(#executable). Make a workflow file directly executable
 184
 185 You can make a workflow file directly executable (@cwl-runner@ should be an alias to @arvados-cwl-runner@) by adding the following line to the top of the file:
 186
 187 <notextile>
 188 <pre><code>#!/usr/bin/env cwl-runner
 189 </code></pre>
 190 </notextile>
 191
 192 <notextile>
 193 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem.cwl bwa-mem-input.yml</span>
 194 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 195 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 196 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to zzzzz-4zz18-h7ljh5u76760ww2
 197 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job zzzzz-8i9sb-fm2n3b1w0l6bskg
 198 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Running
 199 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Complete
 200 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 201 {
 202     "aligned_sam": {
 203         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 204         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 205         "class": "File",
 206         "size": 30738986
 207     }
 208 }
 209 </code></pre>
 210 </notextile>
 211
 212 You can even make an input file directly executable the same way with the following two lines at the top:
 213
 214 <notextile>
 215 <pre><code>#!/usr/bin/env cwl-runner
 216 cwl:tool: <span class="userinput">bwa-mem.cwl</span>
 217 </code></pre>
 218 </notextile>
 219
 220 <notextile>
 221 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem-input.yml</span>
 222 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 223 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 224 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to zzzzz-4zz18-h7ljh5u76760ww2
 225 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job zzzzz-8i9sb-fm2n3b1w0l6bskg
 226 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Running
 227 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Complete
 228 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 229 {
 230     "aligned_sam": {
 231         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 232         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 233         "class": "File",
 234         "size": 30738986
 235     }
 236 }
 237 </code></pre>
 238 </notextile>
 239
 240 h2(#setup). Setting up arvados-cwl-runner
 241
 242 See "Arvados CWL Runner":{{site.baseurl}}/sdk/python/arvados-cwl-runner.html