Difference between revisions of "How to Setup Visual Studio Code for the ifarm"
(→Using ssh keys) |
m (→Using ssh keys) |
||
Line 52: | Line 52: | ||
#* Note: using a non-empty passphrase has yet to be tested | #* Note: using a non-empty passphrase has yet to be tested | ||
# Now we can copy the public key to the ifarm. Run <code>ssh-copy-id -i YOUR_KEY_NAME.pub ifarm</code> replacing <code>YOUR_KEY_NAME</code> with the key name that was generated | # Now we can copy the public key to the ifarm. Run <code>ssh-copy-id -i YOUR_KEY_NAME.pub ifarm</code> replacing <code>YOUR_KEY_NAME</code> with the key name that was generated | ||
− | #* <span style="color:blue">Windows Users:</span> <code>type $env:USERPROFILE\.ssh\id_ecdsa.pub | ssh ifarm "cat >> .ssh/authorized_keys"<code> | + | #* <span style="color:blue">Windows Users:</span> <code>type $env:USERPROFILE\.ssh\id_ecdsa.pub | ssh ifarm "cat >> .ssh/authorized_keys"</code> |
# Enter the requested passwords. If no errors occur, then both terminal and VS Code connection methods should recognize these keys and no longer require a CUE password to be entered! | # Enter the requested passwords. If no errors occur, then both terminal and VS Code connection methods should recognize these keys and no longer require a CUE password to be entered! | ||
Revision as of 09:30, 25 July 2024
Table of contents
Contents
Welcome! Have you ever wanted to edit code for GlueX analysis using smart code completion, debuggers, integrated Git, syntax highlighting, and so much more, all wrapped into one? Well look no further than Visual Studio (VS) Code! By the end of this guide, you will be able to connect to the ifarm and have all these powerful tools right at your fingertips. This includes the Extensions marketplace, which adds incredibly useful features and tools to your programming setup. If you run into any problems then please message me, Kevin Scheuer, over Slack (or email) and let me know!
Windows Users: This guide is primarily aimed at macOS / Linux users, but there will be slight deviations for windows machines. Look for blue text that will denote Windows-specific instructions.
Setup
Before beginning, please ensure you have the following:
- A working JLab Computing account
- A 2 Factor Authentication Method (2FA) setup. This is MobilePASS or Google Authenticator.
- See the guide under Software on the Getting Started at GlueX page
- Or see the Prerequisites section in this servicenow article
- Downloaded VS Code for your OS
The .ssh/config file
- Your first step for getting onto the ifarm will be creating an ssh config file, which dictates how your device, or “local machine”, will connect to the remote JLab server
- Open VS Code and navigate to the Extensions tab on the left-hand sidebar. Copy and paste
ms-vscode-remote.remote-ssh
into the search bar, and install the package.- If you can’t see the sidebar, try in the menu View > Appearance > Primary Side Bar
- In the menu bar go to View > Command Palette. Search and select
Remote-SSH: Open SSH Configuration File
- Your default file is likely at
/Users/YOUR_USERNAME/.ssh/config
. Select this file and it should now open in the editor view.- If the file is not yet created, no worries. Open VS Code's integrated terminal with Terminal > New Terminal or View > Terminal and navigate to the
.ssh
folder. Runtouch config
to create a blank file. Now open the file as instructed. - Windows Users: Your file path should be
C:/Users/YOUR_USERNAME/.ssh/config
- If the file is not yet created, no worries. Open VS Code's integrated terminal with Terminal > New Terminal or View > Terminal and navigate to the
- If settings already exist in this file they can be kept, so long as they are not ifarm related. We will be using a slightly modified version from the JLab recommended config file. Download the OS specific custom config file and copy/paste its contents into the .ssh/config file open in the VS Code editor
- At the very bottom find
User YOUR_USERNAME_HERE
and replace with your JLab CUE username. Note that nothing else but that line in the file needs to be changed - Notice there is now a dot next to the file name. This indicates edits have been made and need to be saved. Save the changes with File > Save and close the file by pressing the X next to the file name
- Open the command palette again and search/select
Preferences: Open User Settings
- Search
Remote.SSH: Remote Server Listen on Socket
and ensure this option is selected. - We'll also want to change the default
.vscode-server
location. This dictates where your Extensions and some other modules will be stored, but can quickly outgrow the limits of its default location on the ifarm at/home/YOUR_USERNAME/
. It's highly recommended to put this in a more spacious location, like a user’s directory on the work disk. SearchRemote.SSH: Server Install Path
in your user settings, and set key toifarm
and Value to be your directory of choice, then click Add item to save your change- For example, my path is
/w/halld-scshelf2101/kscheuer/
- For example, my path is
- The last setting to change will dictate how long the password prompt will stay up when signing in, as the default of 15 seconds typically feels too short. In user settings, search
Remote.ssh: Connect Timeout
and change this value to however many seconds you want - Lastly, ssh needs a specific directory to be setup to work properly. Open a terminal and navigate to
/Users/YOUR_USERNAME/.ssh/
(or wherever your config file is) and performmkdir cm
Connecting
- Before we go about connecting with VS Code, let's test the config file and ensure the connection can be established. Open a terminal via Terminal > New Terminal or View > Terminal and simply run
ssh ifarm
. Note that even though the terminal is "integrated" as part of VS Code, for the most part, it functions just like any terminal window - You should be prompted to enter a password, which will be your 2FA method (MobilePASS or Google Authenticator). Click enter and another prompt will appear. This time enter your JLab CUE password.
- You should be taken to your home directory on an ifarm node. We now know the connection can be made. Type
exit
and click enter to close the session- If you get to the JLab CUE prompt and enter your password but the connection is hanging, it may be that the ifarm node it's routing you to is having issues. There are 3 nodes 1801, 1802, and 1901. Retry from step 1 but do
ssh ifarmXXXX
replacing the X’s with one of the three node numbers
- If you get to the JLab CUE prompt and enter your password but the connection is hanging, it may be that the ifarm node it's routing you to is having issues. There are 3 nodes 1801, 1802, and 1901. Retry from step 1 but do
- From the Command Palette run
Remote-SSH: Connect to Host
. Select the option ifarm- If you’d prefer a new window to not be opened, execute
Remote-SHH: Connect Current Window to Host
- If you’d prefer a new window to not be opened, execute
- It may ask what type of system this is, select Linux. Similar to the connection we did in the terminal, you will be prompted for 2 consecutive passcode inputs. The first will be the 2FA method, and the second your CUE password
- VS Code will configure the connection, and if successful there should be a green (or blue, depending on your color theme) status bar in the lower left corner. You can even open a terminal and see what node you are on, and verify that you are in your home directory
- Congratulations, you are now connected and ready to code! You can exit at any time by clicking on that green status bar and selecting Close Remote Connection.
Using ssh keys
This section is completely optional, but if working correctly it means you'll never have to enter your CUE password again! In short, we'll make 2 ssh keys: one that sits on our local machine, and the "public" key that we'll place on the ifarm. There are different algorithms and key sizes you can use, here we'll be using ecdsa.
- Navigate to the directory of your
config
file and runssh-keygen -t ecdsa
- It then asks for an optional passphrase for the keys. To leave it empty, just press enter
- Note: using a non-empty passphrase has yet to be tested
- Now we can copy the public key to the ifarm. Run
ssh-copy-id -i YOUR_KEY_NAME.pub ifarm
replacingYOUR_KEY_NAME
with the key name that was generated- Windows Users:
type $env:USERPROFILE\.ssh\id_ecdsa.pub | ssh ifarm "cat >> .ssh/authorized_keys"
- Windows Users:
- Enter the requested passwords. If no errors occur, then both terminal and VS Code connection methods should recognize these keys and no longer require a CUE password to be entered!
Troubleshooting
- I was able to connect before, but now it's failing and/or repeatedly asks for the password prompt
- To verify this is an issue with just VS Code, check that you can connect normally by running
ssh ifarm
in a terminal - If that works, then in the command palette perform “Remote SSH: Kill VS Code Server on Host” and select ifarm. Doing this once should reset the connection
- This shouldn't remove your extensions, but if you want to be safe you can make a backup of your
.vscode-server
on the ifarm
- This shouldn't remove your extensions, but if you want to be safe you can make a backup of your
- To verify this is an issue with just VS Code, check that you can connect normally by running
- In step 4 of Connecting I don't see an option for ifarm
- Set the absolute path to your custom config file by opening
Preferences: Open User Settings
in the command palette and searching forRemote.SSH: Config File
- Set the absolute path to your custom config file by opening
Working With VS Code
A full tutorial on how to use VS Code is beyond the extent (and reasonable length) of this guide, but the official getting started webpage for VS Code is highly recommended.
Extensions
A lot of the power of VS Code comes from its “Extensions”. Below are listed some necessary ones that allow VS Code to interact with C++ or Python nicely, but also some incredibly useful ones and highlights of their features. You can search for each extension by name, or copy-paste its ID into the search bar. Note that extensions are stored in the .vscode-server
on the ifarm, and in .vscode
on your local machine, and so you can have different extensions for each location.
Standards
- C/C++ Extension Pack
ms-vscode.cpptools-extension-pack
- Python
ms-python.python
- Pylance
ms-python.vscode-pylance
- Python Debugger
ms-python.debugpy
- Jupyter
ms-toolsai.jupyter
GitHub Copilot
- Github Copilot is an AI Pair Programming tool trained on public GitHub repos. Copilot features in-line suggestion (think "smarter" tab-completion), chat bot, and more. It is an extremely useful tool that you should take advantage of. A more in-depth explanation of Copilot in VSCode, as well as instructions to get started, can be found here.
- While Copilot generally has a fee for access, graduate students can use the tool for free via the GitHub Student Developer Pack (in addition to much, much more. Seriously, sign up for it if you're a student).
Recommended
- Docs View
bierner.docs-view
- Adds a tab in the explorer sidebar to view documentation of any function you select in the editor
- Works for any object, not just the standard packages! This means while editing you can select your favorite AmpTools class/function and see its documentation on the fly
- ROOT File Viewer
albertopdrf.root-file-viewer
- Like a TBrowser, but all within VSCode!
- GitLens
eamodio.gitlens
- View the history and author of any line in a file (that’s in a GitHub repo of course)
- See a graph of all the commit history
- Git Graph
mhutchie.git-graph
- Free alternative to graph feature of GitLens if you have private repos
- Emacs keymapping
hiro-sun.vscode-emacs
- Note that it doesn’t always work perfectly, I think it tries not to override any VS Code keymaps, but this can be configured
- Oh, and if for some reason you like vim…
vscodevim.vim
- CSV to Table
phplasma.csv-to-table
- This extension gives you a command-palette option Convert to Table from CSV that gives you a very nice table-style view of any CSV file
- Edit csv
janisdd.vscode-edit-csv
- Lets you edit CSV files with a table UI similar to Excel
- Rainbow CSV
mechatroner.rainbow-csv
- Makes viewing and editing CSV files easier by coloring columns
- Code Spell Checker
streetsidesoftware.code-spell-checker
- Helps you to cut down the typos in variable names and comments
- Super useful for Jupyter notebook markdown cells
- Pylint
ms-python.pylint
- Helps you to keep your Python code straight
- Python Indent
kevinrose.vsc-python-indent
- Improves indentation of Python code
- Python Type Hint
njqdev.vscode-python-typehint
- Great if you use type hints (you should)
- Diff tabs
jozefchmelar.compare
- See diff of two tabs, even if they're not saved
- Partial Diff
ryu1kn.partial-diff
- Diff text selections within a file, across files, or to the clipboard
- indent-rainbow
oderwat.indent-rainbow
- Makes indentations easier to read
- Path Intellisense
christian-kohler.path-intellisense
- Autocompletes file paths
- Todo Tree
gruntfuggly.todo-tree
- Helps you to keep track of your TODOs and FIXMEs
- Trailing Spaces
shardulm94.trailing-spaces
- If you worry about whitespace errors
- Better PageUp/PageDown
russelldavis.better-pageup-pagedown
- If you do not like the default way scrolling with PageUp/Down works, give this a try
- VSCode is also a great platform for writing LaTeX documents
- LaTeX Workshop
james-yu.latex-workshop
- Provides preview, compile, autocomplete, syntax highlighting, sync, and more
- LTeX – LanguageTool grammar/spell checking
valentjn.vscode-ltex
- Grammar/spell checker using LanguageTool with support for LaTeX, Markdown, and others
- LaTeX Workshop
- Better Markdown Preview
shd101wyy.markdown-preview-enhanced