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: 1f74405842f221c40b852cf142a393c25eefd15a
  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, then use vscode to connect to an Arvados shell node for development
  21 1. Register a workflow, run it on workbench, and view the log
  22 1. Upload input, run a workflow on it, and view the output
  23 1. Register a workflow with default inputs
  24 1. Run a workflow without registering it
  25
  26 ## 1. SSH Setup
  27
  28 1. (Windows only) Install Git for Windows [https://git-scm.com/download/win](https://git-scm.com/download/win)
  29    1. Choose "64-bit Git for Windows Setup".  It does not require admin privileges to install.
  30    1. Hit "Next" a bunch of times to accept the defaults
  31    1. The most important things is that "install git bash" and "install OpenSSH" are enabled (this is the default).
  32    1. At the end of the installation, you can launch tick a box to git bash directly.
  33    1. Open "Git Bash" (installed in the "Git" folder of the start menu)
  34 1. (All operating systems) Starting from bash shell (on MacOS or Linux you will open "Terminal")
  35    1. Shell: Run `ssh-keygen`
  36       1. Hit enter to save to a default location
  37       1. You can choose to protect the key with a password, or just hit enter for no password.
  38    1. Shell: Look for a message like `Your public key has been saved
  39       in /c/Users/MyUsername/.ssh/id_rsa.pub` (Windows git bash
  40       example, on MacOS or Linux this will probably start with `/Users` or `/home`)
  41       1. Shell: Run `cat /c/Users/MyUsername/.ssh/id_rsa.pub`
  42    1. Shell: Use the pointer to highlight and copy the lines starting
  43       with `ssh-rsa …` up to the next blank line.  Right click and
  44       select "Copy"
  45 1. Open Arvados workbench 2.  If necessary, go to the user menu and
  46    select "Go to Workbench 2"
  47    1. Workbench: Go to `SSH keys` in the user menu
  48    1. Workbench:Click `+Add new ssh key`
  49    1. Workbench: Paste the key into `Public key` and enter something for `name`
  50    1. Workbench: Go to `Virtual Machines` in the user menu
  51    1. Workbench: Highlight and copy the value in in the `Command line` column.
  52 1. At the git bash command line
  53    1. Shell: paste the `ssh shell…` command line you got from workbench.
  54    1. Shell: type "yes" if it asks `Are you sure you want to continue connecting`.
  55    1. Note: it can take up to two minutes for the SSH key to be copied to
  56       the shell node.  If you get "Permission denied" the first time, wait 60
  57       seconds and try again.
  58    1. Shell: You should now be logged into the Arvados shell node.
  59    1. Shell: Log out by typing `exit`
  60
  61 ## 2. VSCode setup
  62
  63 1. Install [Visual Studio Code](https://code.visualstudio.com/) and start it up
  64 1. Vscode: On the left sidebar, select `Extensions` ![](images/Extensions.png)
  65    1. In `Search Extensions in Marketplace` enter "remote development".
  66    1. Choose and install the "Remote Development" extension pack from Microsoft
  67 1. Vscode: On the left sidebar, choose `Remote Explorer` ![](images/RemoteExplorer.png)
  68    1. At the top of the Remote Explorer panel choose `SSH targets` ![](images/SSHTargets.png)
  69    1. Click `Add New` ![](images/AddNew.png)
  70    1. Enter the `ssh shell…` command line you used in the previous section, step 1.4.1
  71       1. If it asks you `Select SSH configuration file to update` choose the first one in the list.
  72    1. Right click the newly added ssh target in the list and select “connect to host in current window`
  73    1. If it asks `Select platform of the remote host` select `Linux`.
  74 1. Vscode: On the left sidebar, go back to `Extensions` ![](images/Extensions.png)
  75    1. Search for "benten" and install `CWL (Rabix/Benten)`
  76    1. You should see a message `Extension is enabled on 'SSH: ...' and disabled locally.`
  77 1. Vscode: On the left sidebar, choose `Explorer` ![](images/Explorer.png)
  78    1. Select `Clone Repository` and enter [https://github.com/arvados/arvados-vscode-cwl-training](https://github.com/arvados/arvados-vscode-cwl-training), then click `Open`
  79    1. If asked `Would you like to open the cloned repository?` choose `Open`
  80 1. Go to Arvados Workbench
  81    1. Workbench: In the user menu, select `Current token`
  82    1. Vscode: Click on the `Terminal` menu
  83    1. Vscode: Click `Run Task…`
  84    1. Vscode: Select `Configure Arvados`
  85    1. Workbench: Copy the string following `ARVADOS_API_HOST=`
  86    1. Vscode: Paste the string at the `Value for ARVADOS_API_HOST` prompt
  87    1. Workbench: Copy the string following `ARVADOS_API_TOKEN=`
  88    1. Vscode: Paste the string at the `Value for ARVADOS_API_TOKEN` prompt
  89
  90 ## 3. Register & run a workflow
  91
  92 1. Vscode: Click on the `lesson1/main.cwl` file
  93    1. Click on the `Terminal` menu
  94    1. Click `Run Task…`
  95    1. Select `Register or update CWL workflow on Arvados Workbench`
  96 1. Workbench: Go to `+NEW` and select `New project`
  97    1. Enter a name for the project like "Lesson 1"
  98    1. You should arrive at the panel for the new project
  99 1. Workbench: With `Lesson 1` selected
 100    1. Click on `+NEW` and select `Run a process`
 101    1. Select `CWL training lesson 1` from the list and click `Next`
 102    1. Enter a name for this run like `First training run`
 103    1. Enter a message (under `#main/message`) like "Hello world"
 104    1. Click `Run process`
 105    1. This should take you to a panel showing the workflow run status
 106 1. Workbench: workflow run status panel
 107    1. Wait for the badge in the upper right to say `Completed`
 108    1. In the lower panel, double click on the `echo` workflow step
 109    1. This will take you to the status panel for the `echo` step
 110    1. Click on the three vertical dots in the top-right corner next to `Completed`
 111    1. Choose `Log`
 112    1. This will take you to the log viewer panel
 113    1. Under `Event Type` choose `stdout`
 114    1. You should see your message
 115
 116 ## 4. Working with input and output files
 117
 118 1. Vscode: Click on the `lesson2/main.cwl` file
 119    1. Click on the `Terminal` menu
 120    1. Click `Run Task…`
 121    1. Select `Register or update CWL workflow on Arvados Workbench`
 122 1. Go to your desktop
 123    1. Right click on the desktop, select `New > Text Document`
 124    1. Name the file `message`
 125    1. Enter a message like "Hello earth" and save
 126 1. Workbench: Go to `+NEW` and select `New project`
 127    1. Enter a name for the project like "Lesson 2"
 128    1. You should arrive at the panel for the new project
 129 1. Arvados workbench: With `Lesson 2` project selected
 130    1. Click on +NEW and select `New collection`
 131    1. For Collection Name enter "my message"
 132    1. Drag and drop `message.txt` into the browser
 133    1. Click `Create a collection`
 134    1. The file should be uploaded and then you will be on the collection page
 135 1. Workbench: Select the `Lesson 2` project
 136    1. Click on `+NEW` and select `Run a process`
 137    1. Select `CWL training lesson 2` from the list and click `Next`
 138    1. Enter a name for this run like "Second training run"
 139    1. Click on `#main/message`
 140    1. A selection dialog box will appear
 141    1. Navigate to the collection you created in step (4.4.4) and choose `message.txt`
 142    1. Click `Run process`
 143    1. This should take you to a panel showing the workflow run status
 144 1. Workbench: workflow run status panel
 145    1. Wait for the process to complete
 146    1. Click on the dot menu
 147    1. Choose `Outputs`
 148    1. Right click on `reverse.txt`
 149    1. Click on `Open in new tab`
 150    1. The results should be visible in a new browser tab.
 151
 152 ## 5. Register a workflow with default inputs
 153
 154 The default value for the `message` parameter will taken from the `lesson3/defaults.yaml` file
 155
 156 1. Vscode: Click on the `lesson3/main.cwl` file
 157    1. Click on the `Terminal` menu
 158    1. Click `Run Task…`
 159    1. Select `Register or update CWL workflow on Arvados Workbench`
 160 1. Workbench: Go to `+NEW` and select `New project`
 161    1. Enter a name for the project like "Lesson 3"
 162    1. You should arrive at the panel for the new project
 163 1. Workbench: With `Lesson 3` selected
 164    1. Click on `+NEW` and select `Run a process`
 165    1. Select `CWL training lesson 3` from the list and click `Next`
 166    1. Enter a name for this run like "Third training run"
 167    1. The `#main/message` parameter will be pre-filled with your default value.  You can choose to change it or use the default.
 168    1. Click `Run process`
 169    1. This should take you to the status page for this workflow
 170    1. The greeting will appear in the `Log` of the `echo` task, which
 171       can be found the same way as described earlier in section 3.
 172
 173 ## 6. Run a workflow without registering it
 174
 175 The `message` parameter will be taken from the file `lesson4/main-input.yaml`.  This is useful during development.
 176
 177 1. Workbench: Go to `+NEW` and select `New project`
 178    1. Enter a name for the project like "Lesson 4"
 179    1. You should arrive at the panel for the new project
 180    1. Click on `Additional info` in the upper right to expand the `info` panel
 181    1. Under `Project UUID` click the `Copy to clipboard` button
 182 1. Vscode: Select the file `lesson4/main.cwl`
 183    1. Click on the `Terminal` menu
 184    1. Click `Run Task…`
 185    1. Select `Set Arvados project UUID`
 186    1. Paste the project UUID from workbench at the prompt
 187 1. Vscode: Select the file `lesson4/main.cwl`
 188    1. Click on the `Terminal` menu
 189    1. Click `Run Task…`
 190    1. Select `Run CWL workflow on Arvados`
 191 1. Vscode: In the bottom panel select the `Terminal` tab
 192    1. In the upper right corner of the Terminal tab select `Task - Run CWL Workflow` from the drop-down
 193    1. Look for logging text like `submitted container_request zzzzz-xvhdp-0123456789abcde`
 194    1. Highlight and copy the workflow identifier (this the string containing `-xvhdp-` in the middle)
 195    1. The results of this run will appear in the terminal when the run completes.
 196 1. Workbench: Paste the workflow identifier into the search box
 197    1. This will take you to the status page for this workflow
 198
 199
 200 ## Notes
 201
 202 If you need to change something about the environment of the user on
 203 the remote host (for example, the user has been added to a new unix
 204 group) you need to restart the vscode server that runs on the remote
 205 host.  Do this in vscode:
 206
 207 ctrl+shift+p: `Remote-SSH: Kill VS Code Server on Host`
 208
 209 This is because the vscode server remains running on the remote host
 210 even after you disconnect, so exiting/restarting vscode on the desktop
 211 has no effect.