Arvados

Is bug #2377 a duplicate of this?

Under Logging in using PuTTY (Windows)
Initial Configuration

Step 6.5: In cmd enter: plink -P 2222 turnout@switchyard.qr1hi.arvadosapi.com %host"

Ready for review. Below is the list of what has been updated:

- Windows environment related instructions are moved into a separate page

- Cleaned up the original documentation, which is now the unix only version, to remove the moved out windows instructions.

- Update the windows instructions to ensure that they are now working

- Removed "make sure to include semicolon and quotation marks" since the path did not work with this.

- Update the ssh-adding-public-key.png image and corresponding text changes.

Reviewing 060faf2

• Please consistently capitalize the following names: "SSH" (except when referring to the literal ssh command), "Unix," "Windows"
• In page titles and links, "Accessing Arvados VM" would be better as "Accessing an Arvados VM," since the user may have access to several of them.
• Now that the different platforms have separate pages, I think it would be cleaner to remove the subheads that refer specifically to the platform again (e.g., under "Getting your SSH key" on either page).
• Instructions that refer to the Workbench interface are generally out-of-date with its recent changes. In particular, please double-check "Alternate way to add SSH keys" and "Using SSH to log into an Arvados VM."
• please visit the Accessing Arvados VM with SSH - Unix/Windows Environments - this sentence seems to be missing a word and punctuation.

ssh-access-windows.html.textile.liquid¶

• The Unix instructions refer to the site.arvados_api_host variable to avoid hardcoding references to qr1hi. Please do the same here.
• if you are using the SSH client that comes with Cygwin you should follow the Unix - this sentence seems to be missing a word. Punctuation should go inside the parentheses.
• There's trailing whitespace after the first bullet point under "Step 1 - Adding PuTTY to the PATH"
• Click to save the Public Key. - might read better as Click the _Save public key_ button. Same comment about the private key below.
• the Arvados Workbench page _Settings %(rarr)→% Virtual machines_ page. - You can trim one of the "page"s here.
• If you see a hung terminal window with no futher action: open a new terminal window - "further" has a typo. Please provide instructions for how I open a new terminal window, and add a note that "shell" should be replaced with the name of the virtual machine the user wants to log in to. I wonder if these instructions should be moved up? Right now we believe that every user will have to do this before their first login, so it seems like it would be helpful to have the instructions before the first login, in case they stop reading when they get the hung terminal (I almost did myself).

Reviewing a24c2a7a

• This sentence (on both pages) still has operating system capitalization issues: "This document is for windows environments. If you are using a unix environment (Linux, OS X, Cygwin), please visit the [other page]."
• "if you are using the SSH client that comes with Cygwin you should follow the Unix" - this sentence (still) seems to be missing a word. Punctuation should go inside the parentheses.
• The new header "Generate key using ssh-keygen" needs some change to make it grammatical—e.g., "Generate a key…"
• I'm concerned that the instructions to open a new terminal "from the Start menu" aren't specific enough. I'm not sure that many Windows users will realize this refers to what Windows calls the Command Prompt. Is it possible to be more specific?
• Did you make a specific decision to leave the terminal plink instructions where they are, rather than moving them up? I think I'm fine with it if there's a reason; just want to double-check that the comment wasn't overlooked (since it went on for a while).

Thanks.

Brett: updated as per your feedback.

I was actually looking at a different Cygwin location and missed the line you were actually referring to. It is now updated and I also corrected the unix url link in the Windows page, which was not working.

Used "Command Prompt" in place of "terminal".

I left the last plink instruction (in the hung command prompt window section) as is. I think it flows better with the sequence of instructions and moving it up would cause confusion.

Thanks.

Reviewing 7410cd97

• I'm not sure we should refer to the hung PuTTY window as a Command Prompt. I think we should only use that name to refer to the specific DOS-like CLI launched from the Windows Start menu, and call the hung PuTTY window something else. Calling PuTTY's window a terminal, as before, would be okay by me.
• On the Unix SSH page, "This document is for unix environments" is missing capitalization for Unix.

Reviewing 0456c653, and there's just one thing: the section "Alternate way to add SSH keys" still refers to an older version of the Workbench interface. For example, it talks about clicking the "user icon" instead of the user's e-mail address.

This ticket's title talks about using a template to hold these Workbench instructions and help keep them consistent. Would that help keep this sort of thing in sync?

Brett, thanks for catching the user icon issue. I updated it to say email address.

I am not sure how hard /easy it is to introduce a template for the common stuff. Unless it is very easy, I think we should merge this into master at this time so that the documentation is at least functional and usable. If we want the template, do let me know if there is a sample implementation.

Thanks.

Radhika Chippada wrote:

Brett, thanks for catching the user icon issue. I updated it to say email address.

Unfortunately, the section needs other updates related to Workbench interface changes. At least on our development environment right now, clicking the button to add a key no longer dynamically adds a row to the keys table. Instead, it takes you to a page to fill out the key's metadata, where every attribute is a separate row.

I am not sure how hard /easy it is to introduce a template for the common stuff. Unless it is very easy, I think we should merge this into master at this time so that the documentation is at least functional and usable. If we want the template, do let me know if there is a sample implementation.

Understood. Thanks.

Brett, ah the evil cycle of ongoing updates and review process got me!

I updated the add key section and image. I also extracted the common ssh items into include files and reuse among the two files. Tested thoroughly by clicking on the links several times.

Please take one more look. I am hopeful I'm almost done bothering you with this. Thanks.

ebd7d571 looks good to merge to me. Thank you.