Skip to content

Commit 297c6b3

Browse files
ShaivanBhagatjelletreep
ShaivanBhagat
and
jelletreep
authored
add github copilot manual (#101)
--------- Co-authored-by: Jelle Treep <h.j.treep@uu.nl>
1 parent a7e173c commit 297c6b3

3 files changed

Lines changed: 275 additions & 0 deletions

File tree

‎docs/manuals.qmd‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,5 @@ To find the best data transfer method for your situation, check out this [**Inte
3030

3131
- [Setup Ollama on VRE Lab](manuals/ollama.qmd)
3232
- [Running long jobs](manuals/long-jobs.qmd)
33+
- [Connecting to Research Cloud from VS Code via SSH](manuals/vscode-to-researchcloud.qmd)
34+
- [Using AI powered coding assistants on Surf Research Cloud via SSH](manuals/github-copilot.qmd)

‎docs/manuals/coding-assistants.qmd‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: "Using AI assistants on SURF Research Cloud"
3+
---
4+
5+
# Overview
6+
7+
This guide explains how to use AI assistants while working on SURF Research Cloud.
8+
9+
::: {.callout-warning}
10+
## Disclaimer
11+
12+
With this guide we do not endorse AI coding assistants. Users are responsible for:
13+
14+
- **Compliance:** Ensuring use complies with institutional policies on AI tools
15+
- **Privacy:** Understanding that data may be sent to external AI services
16+
- **Validation:** Reviewing and validating all AI-generated code
17+
- **Licensing:** Checking terms of service and licensing requirements
18+
19+
Review [Utrecht University's AI policy and guidelines](https://www.uu.nl/en/organisation/ai-policy) before using AI coding assistants.
20+
:::
21+
22+
## How It Works
23+
24+
The easiest method is to connect the IDE (Integrated Development Environment; e.g. VSCode, VSCodium, etc.) on your PC to a workspace using Remote-SSH. In this way, you can use any extensions that you install in the IDE on your PC for your work on Research Cloud.
25+
26+
## Prerequisites
27+
28+
1. IDE that supports connecting to your workspace via SSH such as VSCode, VSCodium, Pycharm or Positron (R).
29+
2. IDE extension of the AI coding assistant of your choice. You will typically need an **Active subscription or account** for your chosen AI assistant.
30+
3. **API key or authentication** if required by the assistant.
31+
4. A workspace on SURF Research Cloud.
32+
33+
::: {.callout-tip}
34+
**Recommended workspaces:** While this setup works with any workspace, those with Python environment managers pre-installed (Python Workbench, VRE Lab) make it easier to manage project dependencies.
35+
:::
36+
37+
38+
## Setup Instructions
39+
40+
Follow our [Connecting to Research Cloud from VS Code](../manuals/vscode-to-researchcloud.qmd) to set up Remote-SSH and connect your IDE to your workspace. Once connected, you can use the AI coding assistant extensions as you normally would on your PC. The AI assistant will have access to the files and environment in your Research Cloud workspace, allowing it to assist you with coding tasks.
41+
42+
## Contact
43+
44+
If you have any issues or questions, you can [contact us here.](https://www.uu.nl/en/research/research-data-management/contact)
45+
46+

‎docs/manuals/vscode-to-researchcloud.qmd‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
title: "Connecting to Research Cloud from VS Code"
3+
---
4+
5+
## Overview
6+
7+
This guide shows you how to connect your local VS Code to a SURF Research Cloud workspace using SSH.
8+
9+
### How It Works
10+
11+
- **Local VS Code** provides the editing interface and your preferred extensions
12+
- **Surf Research Cloud workspace** provides the computing power, pre-installed software, and file storage
13+
- **Files live on the workspace**, not on your local computer
14+
- **Code executes on the workspace** using its resources and libraries
15+
16+
### Why Use This Setup?
17+
18+
- Work with your familiar VS Code setup and your choice of extensions
19+
- Use the computing resources of your workspace
20+
- Access pre-installed Python environments (`uv`, `conda`, `pyenv`, etc.) seamlessly
21+
- Edit files directly on the workspace without constant file transfers
22+
23+
::: {.callout-warning}
24+
## Important Considerations for Workspace Management
25+
26+
- Pause your workspace when not actively using it to save credits (closing your local VSCode ssh session does not pause the workspace)
27+
- Workspaces have expiration dates so keep track of when your workspace will expire
28+
- Backup your data and important files regularly
29+
- Files are on the workspace and are deleted when the workspace is deleted
30+
31+
See our guide on [responsible use](../responsible-use.qmd) for managing costs and resources.
32+
:::
33+
34+
## Prerequisites
35+
36+
1. **[A running workspace](../first-steps.qmd#workspace-state)** on SURF Research Cloud
37+
2. **[VS Code](https://code.visualstudio.com/)** installed on your local computer
38+
3. **SSH access configured** Follow the [SSH setup guide](../first-steps.qmd#ssh) to:
39+
- Create an SSH key pair on your local computer
40+
- Add your public key to SRAM
41+
- Test the SSH connection using the workspace IP address and your SRAM username
42+
43+
::: {.callout-tip}
44+
This method works with any workspace that has SSH access.
45+
46+
**Recommended workspaces:** Python Workbench or VRE Lab come with Python environment managers (uv, conda, pyenv) pre-installed, making it easier to manage dependencies for your projects.
47+
:::
48+
49+
## Setup Instructions
50+
51+
### Step 1: Setup SSH Connection
52+
53+
Make sure you have SSH access set up and tested as described in the prerequisites. This is essential for connecting VS Code to your workspace.
54+
55+
You can find your workspace's IP address (e.g., `145.38.x.x`) by expanding the workspace tile in the SRC portal. Your SRAM username can be found from your profile.
56+
57+
Before configuring your ssh settings, verify that your ssh key is working. On your local computer, open a terminal and run:
58+
```bash
59+
ssh -i ~/.ssh/id_ed25519 YOUR_USERNAME@YOUR_PUBLIC_IP
60+
```
61+
62+
Replace `YOUR_USERNAME` with your SRAM username and `YOUR_PUBLIC_IP` with the IP address of your workspace.
63+
If you have an `id_rsa` key instead of `id_ed25519`, adjust the path accordingly.
64+
65+
If you are connecting for the first time, you will see: `Are you sure you want to continue connecting (yes/no)?`. Type `yes` and press Enter to continue.
66+
You may also be prompted to enter the passphrase for your SSH key if you set one up. You can press `enter` if you did not set up a passphrase.
67+
68+
If the connection is successful, you should see a welcome message from the server. You can exit the session by typing `exit`.
69+
70+
71+
### Step 2: Configure SSH Connection
72+
73+
Create an SSH configuration file to make connecting easier.
74+
75+
On your **local computer**, open a terminal and run:
76+
```bash
77+
nano ~/.ssh/config
78+
```
79+
80+
Add the following configuration (replace with your details):
81+
```
82+
Host myworkspace
83+
HostName YOUR_WORKSPACE_IP
84+
User YOUR_USERNAME
85+
IdentityFile ~/.ssh/id_ed25519
86+
```
87+
88+
- `myworkspace`: Choose a name of your choice for this connection (e.g., `researchcloud`)
89+
- `YOUR_WORKSPACE_IP`: The public IP address from your workspace tile in the SRC portal
90+
- `YOUR_USERNAME`: Your SRAM username
91+
- Adjust `IdentityFile` if you use `id_rsa` instead of `id_ed25519`
92+
93+
Save the Configuration file:
94+
95+
- Press `Ctrl+O` (save)
96+
- Press `Enter` (confirm filename)
97+
- Press `Ctrl+X` (exit nano)
98+
99+
**Test the connection from your local terminal:**
100+
101+
```bash
102+
ssh myworkspace
103+
```
104+
This allows you to connect to your workspace without needing to type your IP address or key each time. Type `exit` to disconnect.
105+
106+
107+
### Step 3: Install Remote-SSH Extension in VS Code
108+
109+
1. Open VS Code on your local computer
110+
2. Click the **Extensions** icon in the left sidebar (or press `Cmd+Shift+X` on Mac / `Ctrl+Shift+X` on Windows)
111+
3. Search for **"Remote - SSH"** and install the extension by Microsoft.
112+
113+
### Step 4: Connect to Your Workspace
114+
115+
1. In VS Code, press `Cmd+Shift+P` (Mac) / `Ctrl+Shift+P` (Windows) to open the Command Palette
116+
2. Type **"Remote-SSH: Connect to Host"** and select it
117+
3. Choose **myworkspace** from the list (or whatever name you used in your SSH config)
118+
4. A new VS Code window will open
119+
5. Wait 30-60 seconds while VS Code installs its server components on the workspace (the first time may take longer)
120+
6. When connected, you'll see **"SSH: myworkspace"** in the bottom left corner
121+
122+
### Step 5: Verify the Connection
123+
124+
1. In VS Code, open a terminal
125+
2. Run `whoami` - it should show your workspace username (not your local username)
126+
3. Run `pwd` - it should show your workspace home directory
127+
128+
You're now working on the workspace!
129+
130+
## Using Your Remote Connection
131+
132+
### Opening Files and Folders
133+
134+
- **File** → **Open Folder** to navigate to your workspace directories
135+
- All files are on the workspace, not your local computer
136+
- Changes are saved directly to the workspace
137+
138+
### Running Code
139+
140+
- Code executes on the workspace using its Python/R/Julia installations
141+
- Terminal commands run on the workspace
142+
- You can use workspace environment managers (uv, conda, pyenv)
143+
144+
### Selecting Python Environments
145+
146+
1. Press **`Cmd+Shift+P`** / **`Ctrl+Shift+P`**
147+
2. Type **"Python: Select Interpreter"**
148+
3. Choose from the workspace's available Python environments
149+
150+
### Installing Extensions
151+
152+
When you connect to a workspace, VS Code distinguishes between:
153+
154+
- Local extensions: Work on your local editor
155+
- Workspace extensions: Must be installed on the workspace
156+
157+
If you try to use an extension that is not installed on the workspace, VS Code will prompt you to install it remotely. Click **"Install in SSH: myworkspace"** when prompted. Any new extensions installed in such a manner will be installed on the workspace and not your local VSCode.
158+
159+
## Reconnecting
160+
161+
Once configured, reconnecting is simple:
162+
163+
1. Open VS Code
164+
2. Press **`Cmd+Shift+P`** / **`Ctrl+Shift+P`**
165+
3. Type **"Remote-SSH: Connect to Host"**
166+
4. Select `myworkspace`
167+
5. Make sure your workpace is running before reconnecting
168+
169+
# Example Workflow
170+
171+
Once connected to your workspace via SSH, here's an example of working with Python environment managers (`uv`, `conda`, `pyenv`):
172+
173+
1. Navigate to your storage volume on the workspace using the VS Code file explorer (e.g., `/home/username/storage-volume/`)
174+
2. Clone this example repository to your workspace:
175+
```bash
176+
git clone https://github.com/UtrechtUniversity/src-python-example.git
177+
cd src-python-example
178+
```
179+
3. After navigating to the `src-python-example` folder, you can create a Python environment using either `uv`, `conda`, or `pyenv` by following the instructions in:
180+
- [Python Environments Manual](../manuals/python-environment.qmd), or
181+
- [src-python-example](https://github.com/UtrechtUniversity/src-python-example)
182+
183+
4. Select your environment in VS Code:
184+
- Press `Cmd+Shift+P` / `Ctrl+Shift+P`
185+
- Type "Python: Select Interpreter"
186+
- Choose the environment you created
187+
188+
5. Open `vectors.ipynb` from the Notebook folder and run the cells. The code executes on the workspace using the environment you set up.
189+
190+
## Troubleshooting
191+
192+
**"Permission denied (publickey)" error**
193+
194+
- Your SSH key may not be propagated yet. Wait 5-10 minutes after adding it to SRAM
195+
- Verify your key: `cat ~/.ssh/id_ed25519.pub` matches what's in SRAM
196+
- Check the [SSH setup guide](https://servicedesk.surf.nl/wiki/spaces/WIKI/pages/195854434/Workspace+access+with+SSH)
197+
198+
**"Network is unreachable" error**
199+
200+
- Make sure you're using the **public IP** address (starts with `145.38.x.x`), not the internal IP
201+
- Check the workspace is running in the SRC portal
202+
203+
**Connection works in terminal but not in VS Code**
204+
205+
- Verify your SSH config file: `cat ~/.ssh/config`
206+
- Make sure `Host`, `HostName`, `User`, and `IdentityFile` are correct
207+
- Try `ssh myworkspace` in terminal first
208+
209+
**Workspace IP Address Changed**
210+
211+
Workspace IP addresses may change when a workspace is restarted. If you can't connect:
212+
213+
- Check the current IP address in the SRC portal
214+
- Update your SSH config file with the new IP addres
215+
- Or connect directly: `ssh username@new-ip-address`
216+
217+
## Tips
218+
219+
- **Working directory:** When you connect, you start in your home directory of your workspace. Use `Open Folder` from the File menu to navigate to your project
220+
- **Workspace costs:** Remember to pause your workspace when not using it to save credits
221+
- **File management:** All files are on the workspace. Back up important files periodically to avoid data loss if the workspace is deleted
222+
223+
:::callout-important
224+
**Security:** Never share your private SSH key. Only the public key (`.pub` file) goes in SRAM. Keep your private key secure on your local computer.
225+
:::
226+
227+
If you have any issues or questions, you can [contact us here.](https://www.uu.nl/en/research/research-data-management/contact)

0 commit comments

Comments
 (0)