README.md

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