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 h2. Running arvados-cwl-runner
  20
  21 h3. Get the example files
  22
  23 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
  24
  25 <notextile>
  26 <pre><code>~$ <span class="userinput">git clone https://github.com/curoverse/arvados</span>
  27 ~$ <span class="userinput">cd arvados/doc/user/cwl/bwa-mem</span>
  28 </code></pre>
  29 </notextile>
  30
  31 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).
  32
  33 <notextile>
  34 <pre><code>~$ <span class="userinput">arv-copy --src qr1hi --dst settings 2463fa9efeb75e099685528b3b9071e0+438</span>
  35 ~$ <span class="userinput">arv-copy --src qr1hi --dst settings ae480c5099b81e17267b7445e35b4bc7+180</span>
  36 ~$ <span class="userinput">arv-copy --src qr1hi --dst settings 655c6cd07550151b210961ed1d3852cf+57</span>
  37 </code></pre>
  38 </notextile>
  39
  40 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:
  41
  42 "https://cloud.curoverse.com/collections/2463fa9efeb75e099685528b3b9071e0+438":https://cloud.curoverse.com/collections/2463fa9efeb75e099685528b3b9071e0+438
  43
  44 "https://cloud.curoverse.com/collections/ae480c5099b81e17267b7445e35b4bc7+180":https://cloud.curoverse.com/collections/ae480c5099b81e17267b7445e35b4bc7+180
  45
  46 "https://cloud.curoverse.com/collections/655c6cd07550151b210961ed1d3852cf+57":https://cloud.curoverse.com/collections/655c6cd07550151b210961ed1d3852cf+57
  47
  48 h2. Submitting a workflow to an Arvados cluster
  49
  50 h3. Submit a workflow and wait for results
  51
  52 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.
  53
  54 *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.
  55
  56 <notextile>
  57 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner bwa-mem.cwl bwa-mem-input.yml</span>
  58 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  59 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
  60 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
  61 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
  62 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
  63 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
  64 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
  65 {
  66     "aligned_sam": {
  67         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
  68         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
  69         "class": "File",
  70         "size": 30738986
  71     }
  72 }
  73 </code></pre>
  74 </notextile>
  75
  76 h3. Referencing files
  77
  78 When running a workflow on an Arvados cluster, the input files must be stored in Keep.  There are several ways this can happen.
  79
  80 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@.
  81
  82 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.
  83
  84 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.
  85
  86 You can also execute CWL files directly from Keep:
  87
  88 <notextile>
  89 <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>
  90 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  91 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
  92 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
  93 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
  94 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
  95 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
  96 {
  97     "aligned_sam": {
  98         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
  99         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 100         "class": "File",
 101         "size": 30738986
 102     }
 103 }
 104 </code></pre>
 105 </notextile>
 106
 107 h3. Work reuse
 108
 109 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@.
 110
 111 h2.  Command line options
 112
 113 table(table table-bordered table-condensed).
 114 |_. Option |_. Description |
 115 |  --basedir BASEDIR|     Base directory used to resolve relative references in the input, default to directory of input object file or current directory (if inputs piped/provided on command line).|
 116 |  --version|             Print version and exit|
 117 |  --verbose|             Default logging|
 118 |  --quiet|               Only print warnings and errors.|
 119 |  --debug|               Print even more logging|
 120 |  --tool-help|           Print command line help for tool|
 121 |  --enable-reuse|Enable job reuse (default)|
 122 |  --disable-reuse|Disable job reuse (always run new jobs).|
 123 |  --project-uuid UUID|   Project that will own the workflow jobs, if not provided, will go to home project.|
 124 |  --output-name OUTPUT_NAME|Name to use for collection that stores the final output.|
 125 |  --output-tags OUTPUT_TAGS|Tags for the final output collection separated by commas, e.g., '--output-tags tag0,tag1,tag2'.|
 126 |  --ignore-docker-for-reuse|Ignore Docker image version when deciding whether to reuse past jobs.|
 127 |  --submit|              Submit workflow to run on Arvados.|
 128 |  --local|               Control workflow from local host (submits jobs to Arvados).|
 129 |  --create-template|     (Deprecated) synonym for --create-workflow.|
 130 |  --create-workflow|     Create an Arvados workflow (if using the 'containers' API) or pipeline template (if using the 'jobs' API). See --api.|
 131 |  --update-workflow UUID|Update an existing Arvados workflow or pipeline template with the given UUID.|
 132 |  --wait|                After submitting workflow runner job, wait for completion.|
 133 |  --no-wait|             Submit workflow runner job and exit.|
 134 |  --api WORK_API|        Select work submission API, one of 'jobs' or 'containers'. Default is 'jobs' if that API is available, otherwise 'containers'.|
 135 |  --compute-checksum|    Compute checksum of contents while collecting outputs|
 136 |  --submit-runner-ram SUBMIT_RUNNER_RAM|RAM (in MiB) required for the workflow runner job (default 1024)|
 137 |  --name NAME|           Name to use for workflow execution instance.|
 138
 139 h3. Specify workflow and output names
 140
 141 Use the @--name@ and @--output-name@ options to specify the name of the workflow and name of the output collection.
 142
 143 <notextile>
 144 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --name "Example bwa run" --output-name "Example bwa output" bwa-mem.cwl bwa-mem-input.yml</span>
 145 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 146 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 147 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
 148 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
 149 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
 150 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
 151 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 152 {
 153     "aligned_sam": {
 154         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 155         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 156         "class": "File",
 157         "size": 30738986
 158     }
 159 }
 160 </code></pre>
 161 </notextile>
 162
 163 h3. Submit a workflow with no waiting
 164
 165 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.
 166
 167 <notextile>
 168 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --no-wait bwa-mem.cwl bwa-mem-input.yml</span>
 169 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 170 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Upload local files: "bwa-mem.cwl"
 171 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Uploaded to qr1hi-4zz18-eqnfwrow8aysa9q
 172 2016-06-30 15:07:52 arvados.cwl-runner[12480] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
 173 qr1hi-8i9sb-fm2n3b1w0l6bskg
 174 </code></pre>
 175 </notextile>
 176
 177 h3. Control a workflow locally
 178
 179 To run a workflow with local control, use @--local@.  This means that the host where you run @arvados-cwl-runner@ will be responsible for submitting jobs, however, the jobs themselves will still run on the Arvados cluster.  With @--local@, if you interrupt @arvados-cwl-runner@ or log out, the workflow will be terminated.
 180
 181 <notextile>
 182 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --local bwa-mem.cwl bwa-mem-input.yml</span>
 183 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 184 2016-07-01 10:05:19 arvados.cwl-runner[16290] INFO: Pipeline instance qr1hi-d1hrv-92wcu6ldtio74r4
 185 2016-07-01 10:05:28 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Queued
 186 2016-07-01 10:05:29 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Running
 187 2016-07-01 10:05:45 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Complete
 188 2016-07-01 10:05:46 arvados.cwl-runner[16290] INFO: Overall process status is success
 189 {
 190     "aligned_sam": {
 191         "size": 30738986,
 192         "path": "keep:15f56bad0aaa7364819bf14ca2a27c63+88/HWI-ST1027_129_D0THKACXX.1_1.sam",
 193         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 194         "class": "File"
 195     }
 196 }
 197 </code></pre>
 198 </notextile>
 199
 200 h2(#setup). Setting up arvados-cwl-runner
 201
 202 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@:
 203
 204 <notextile>
 205 <pre><code>~$ <span class="userinput">virtualenv ~/venv</span>
 206 ~$ <span class="userinput">. ~/venv/bin/activate</span>
 207 ~$ <span class="userinput">pip install -U setuptools</span>
 208 ~$ <span class="userinput">pip install arvados-cwl-runner</span>
 209 </code></pre>
 210 </notextile>
 211
 212 h3. Check Docker access
 213
 214 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.
 215
 216 You can determine if you have access to Docker by running @docker version@:
 217
 218 <notextile>
 219 <pre><code>~$ <span class="userinput">docker version</span>
 220 Client:
 221  Version:      1.9.1
 222  API version:  1.21
 223  Go version:   go1.4.2
 224  Git commit:   a34a1d5
 225  Built:        Fri Nov 20 12:59:02 UTC 2015
 226  OS/Arch:      linux/amd64
 227
 228 Server:
 229  Version:      1.9.1
 230  API version:  1.21
 231  Go version:   go1.4.2
 232  Git commit:   a34a1d5
 233  Built:        Fri Nov 20 12:59:02 UTC 2015
 234  OS/Arch:      linux/amd64
 235 </code></pre>
 236 </notextile>
 237
 238 If this returns an error, contact the sysadmin of your cluster for assistance.