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