doc/user/cwl/arvados-vscode-training.html.md.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Developing CWL Workflows with VSCode"
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10
  11 Imported from https://github.com/arvados/arvados-vscode-cwl-training
  12 git hash: 4ea2b3e8cbfdf977eaba6bedc36b55aa172a69d8
  13
  14 {% endcomment %}
  15
  16 These lessons give step by step instructions for using Visual Studio
  17 Code (abbreviated "vscode") to develop CWL workflows on Arvados.
  18
  19 1. Set up SSH
  20 1. Install vscode and necessary extensions
  21 1. Use vscode to connect to an Arvados shell node for development
  22 1. Create an simple command line tool, run it, and view the log
  23 1. Upload input, create a command line tool to process it, and view the output
  24
  25 ## 1. SSH Setup
  26
  27 1. (Windows only) Install git for windows [https://git-scm.com/download/win](https://git-scm.com/download/win)
  28 1. Open bash shell (installed with git for Windows)
  29    1. Shell: Run `ssh-keygen`
  30    1. Shell: Look for `Your public key has been saved in /c/Users/MyUsername/.ssh/id_rsa.pub`
  31    1. Shell: Run `cat /c/Users/MyUsername/.ssh/id_rsa.pub`
  32    1. Shell: Highlight and copy the lines starting with `ssh-rsa …`
  33 1. Open Arvados workbench
  34    1. Workbench: Go to `SSH keys` in the user menu
  35    1. Workbench:Click `+Add new ssh key`
  36    1. Workbench: Paste the key into `Public key` and enter something for `name`
  37    1. Workbench: Go to `Virtual Machines` in the user menu
  38    1. Workbench: Highlight and copy the value in in the `Command line` column.
  39 1. At the git bash command line
  40    1. Shell: paste the `ssh shell…` command line you got from workbench.
  41    1. Shell: type "yes" if it asks `do you want to continue connecting`
  42    1. Shell: You should now be logged into the Arvados shell node.  Note:
  43       it can take up to two minutes for the SSH key to be copied to
  44       the shell node.  If it doesn't work the first time, wait 60
  45       seconds and try again.
  46    1. Shell: Log out by typing `exit`
  47
  48 ## 2. VSCode setup
  49
  50 1. Install [Visual Studio Code](https://code.visualstudio.com/) and start it up
  51 1. Vscode: go to `Extensions`
  52    1. search for `remote development` and install the Remote Development extension pack from Microsoft
  53 1. Vscode: On the left side bar, choose `Remote explorer`
  54    1. In the drop down, choose `SSH targets`
  55    1. Click `Add new`
  56    1. Enter the `ssh shell…` command line you used in the previous section, step 1.4.1
  57    1. Right click the ssh target in the list and select “connect to host in current window`
  58 1. Vscode: go to `Extensions`
  59    1. Search for `benten` and install `CWL (Rabix/Benten)`
  60    1. Choose `Install extension on the remote ssh host`
  61 1. Vscode: On the left side bar, choose `Explorer`
  62    1. Select `Clone Repository` and then enter [https://github.com/arvados/arvados-vscode-cwl-training](https://github.com/arvados/arvados-vscode-cwl-training)
  63    1. Choose `Open`
  64 1. Go to Arvados Workbench
  65    1. Workbench: In the user menu, select `Current token`
  66    1. Vscode: Click on the `Terminal` menu
  67    1. Vscode: Click `Run Task…`
  68    1. Vscode: Select `Configure Arvados`
  69    1. Workbench: Copy the string following `ARVADOS_API_HOST=`
  70    1. Vscode: Paste the string at the `Value for ARVADOS_API_HOST` prompt
  71    1. Workbench: Copy the string following `ARVADOS_API_TOKEN=`
  72    1. Vscode: Paste the string at the `Value for ARVADOS_API_TOKEN` prompt
  73
  74 # 3. Register & run a workflow
  75
  76 1. Vscode: Click on the `lesson1/main.cwl` file
  77    1. Click on the `Terminal` menu
  78    1. Click `Run Task…`
  79    1. Select `Register or update CWL workflow on Arvados Workbench`
  80 1. Workbench: Go to `+NEW` and select `New project`
  81    1. Enter a name for the project like "Lesson 1"
  82    1. You should arrive at the panel for the new project
  83 1. Workbench: With `Lesson 1` selected
  84    1. Click on `+NEW` and select `Run a process`
  85    1. Select `CWL training lesson 1` from the list and click `Next`
  86    1. Enter a name for this run like `First training run`
  87    1. Enter a message (under `#main/message`) like "Hello world"
  88    1. Click `Run process`
  89    1. This should take you to a panel showing the workflow run status
  90 1. Workbench: workflow run status panel
  91    1. Click on the three vertical dots in the top-right corner
  92    1. Choose `Log`
  93    1. Under `event type` choose `stdout`
  94    1. You should see your message
  95
  96 ## 4. Working with input and output files
  97
  98 1. Vscode: Click on the `lesson2/main.cwl` file
  99    1. Click on the `Terminal` menu
 100    1. Click `Run Task…`
 101    1. Select `Register or update CWL workflow on Arvados Workbench`
 102 1. Go to your desktop
 103    1. Using a text editor such as notepad, create a file "message.txt"
 104    1. Enter a message like "Hello world" and save
 105 1. Workbench: Go to `+NEW` and select `New project`
 106    1. Enter a name for the project like "Lesson 2"
 107    1. You should arrive at the panel for the new project
 108 1. Arvados workbench: With `Lesson 2` project selected
 109    1. Click on +NEW and select `New collection`
 110    1. Call the collection "my message"
 111    1. Drag and drop `message.txt` into the browser
 112    1. Click `Create a collection`
 113    1. The file should be uploaded and then you will be on the collection page
 114 1. Workbench: Select the `Lesson 2` project
 115    1. Click on `+NEW` and select `Run a process`
 116    1. Select `CWL training lesson 2` from the list and click `Next`
 117    1. Enter a name for this run like "Second training run"
 118    1. Click on `#main/message`
 119    1. A selection dialog box will appear
 120    1. Navigate to the collection you created in step (4.4.4) and choose `message.txt`
 121    1. Click `Run process`
 122    1. This should take you to a panel showing the workflow run status
 123 1. Workbench: workflow run status panel
 124    1. Wait for the process to complete
 125    1. Click on the dot menu
 126    1. Choose `Outputs`
 127    1. Right click on `reverse.txt`
 128    1. Click on `Download`
 129    1. Open the downloaded file.  It should have your results.
 130
 131 ## 5. Register a workflow with default inputs
 132
 133 The default value for the `message` parameter will taken from the `lesson3/defaults.yaml` file
 134
 135 1. Workbench: Go to `+NEW` and select `New project`
 136    1. Enter a name for the project like "Lesson 3"
 137    1. You should arrive at the panel for the new project
 138 1. Workbench: With `Lesson 3` selected
 139    1. Click on `+NEW` and select `Run a process`
 140    1. Select `CWL training lesson 3` from the list and click `Next`
 141    1. Enter a name for this run like "Third training run"
 142    1. The `#main/message` parameter will be pre-filled with your default value.  You can choose to change it or use the default.
 143    1. Click `Run process`
 144    1. This should take you to the status page for this workflow
 145
 146 ## 6. Run a workflow without registering it
 147
 148 The `message` parameter will be taken from the file `lesson4/main-input.yaml`.  This is useful during development.
 149
 150 1. Workbench: Go to `+NEW` and select `New project`
 151    1. Enter a name for the project like "Lesson 4"
 152    1. You should arrive at the panel for the new project
 153    1. Click on `Additional info` in the upper right to expand the `info` panel
 154    1. Under `Project UUID` click the `Copy to clipboard` button
 155 1. Vscode: Select the file `lesson4/main.cwl`
 156    1. Click on the `Terminal` menu
 157    1. Click `Run Task…`
 158    1. Select `Set Arvados project UUID`
 159    1. Paste the project UUID from workbench at the prompt
 160 1. Vscode: Select the file `lesson4/main.cwl`
 161    1. Click on the `Terminal` menu
 162    1. Click `Run Task…`
 163    1. Select `Run CWL workflow on Arvados`
 164 1. Vscode: In the bottom panel select the `Terminal` tab
 165    1. In the upper right corner of the Terminal tab select `Task - Run CWL Workflow` from the drop-down
 166    1. Look for logging text like `submitted container_request zzzzz-xvhdp-0123456789abcde`
 167    1. Highlight and copy the workflow identifier (this the string containing -xvhdp- in the middle)
 168    1. The results of this run will appear in the terminal when the run completes.
 169 1. Workbench: Paste the workflow identifier into the search box
 170    1. This will take you to the status page for this workflow