Skip to content

Commit bb32333

Browse files
bcummingbcumming
authored
add vscode guide (#21)
1 parent 2eb839d commit bb32333

File tree

5 files changed

+210
-4
lines changed

5 files changed

+210
-4
lines changed

‎docs/access/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,10 @@ This documentation guides users through the process of accessing CSCS systems an
2626

2727
[:octicons-arrow-right-24: SSH][access-ssh]
2828

29+
- :fontawesome-solid-layer-group: __VSCode__
30+
31+
How to connect VSCode IDE on your laptop with Alps
32+
33+
[:octicons-arrow-right-24: SSH][access-vscode]
34+
2935
</div>

‎docs/access/vscode.md‎

Lines changed: 157 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,161 @@
1-
[](){#vscode}
1+
[](){#access-vscode}
22
# Connecting with VSCode
33

4+
[Visual Studio Code](https://code.visualstudio.com/) provides flexible support for remote development.
5+
VSCode's [remote tunnel feature](https://code.visualstudio.com/docs/remote/tunnels) starts a server on a remote system, and connects the editor to this server.
6+
There are two ways to set up the connection:
7+
8+
* using the code CLI: the most flexible method if using containers or uenv.
9+
* using the VSCode interface: VSCode will connect onto the system, download and start the server
10+
11+
The main challenge with using VSCode is that the most convenient method for starting a remote session is to start a remote tunnel from the VS Code GUI.
12+
This approach starts a session in the standard login environment on that node, however this won't work if you want to be developing in a container, in a uenv, or on a compute node.
13+
14+
## Flexible method: remote server
15+
16+
The most flexible method for connecting VSCode is to log in to the Alps system, set up your environment (start a container or uenv, start a session on a compute node), and start the remote server in that environment pre-configured.
17+
18+
!!! note
19+
This approach requires that you have a GitHub account, and that the GitHub account is configured with your VS Code editor.
20+
21+
The first step is to download the VS Code CLI tool `code`, which CSCS provides for easy download.
22+
There are two executables, one for using on systems with x86 or ARM CPUs respectively.
23+
24+
=== "`aarch64` nodes (daint, clariden, santis)"
25+
```
26+
wget https://jfrog.svc.cscs.ch/artifactory/uenv-sources/vscode/vscode_cli_alpine_arm64_cli.tar.gz
27+
tar -xf vscode_cli_alpine_arm64_cli.tar.gz
28+
```
29+
30+
=== "`x86_64` nodes (eiger, bristen)"
31+
```
32+
wget https://jfrog.svc.cscs.ch/artifactory/uenv-sources/vscode/vscode_cli_alpine_x64_cli.tar.gz
33+
tar -xf vscode_cli_alpine_x64_cli.tar.gz
34+
```
35+
36+
Alternatively, download the CLI tool from the [VS Code site](https://code.visualstudio.com/Download) -- take care to select either x86 or Arm64 version that matches the target system.
37+
38+
After downloading, copy the `code` executable to a location in your PATH, so that it is available for future sessions.
39+
40+
??? note "guidance on where to put architecture-specific executables"
41+
The home directory can be shared by multiple clusters that might have different micro-architectures, so it is important to separate executables for x86 and aarch64 (ARM) targets.
42+
43+
In `~/.bashrc`, add the following line (you will need to log in again for this to take effect):
44+
```
45+
export PATH=$HOME/.local/$(uname -m)/bin:$PATH
46+
```
47+
The `uname -m` command will print `aarch64` or `x86_64`, according to the microarchitecture of the node it is run on.
48+
49+
Then create the path, and copy the `code` executable to the architecture-specific path:
50+
```
51+
mkdir -p $HOME/.local/$(uname -m)/bin
52+
cp ./code $HOME/.local/$(uname -m)/bin
53+
```
54+
55+
To set up a remote server on the target system,
56+
run the `code` executable that you downloaded the `tunnel` argument.
57+
You will be asked to choose whether to log in to Microsoft or GitHub (we have tested with GitHub):
58+
59+
```
60+
> code tunnel
61+
...
62+
? How would you like to log in to Visual Studio Code? ›
63+
Microsoft Account
64+
❯ GitHub Account
65+
```
66+
67+
You will be requested to go to [github.com/login/device](https://github.com/login/device) and enter an 8-digit code.
68+
Once you have finished registering the service with GitHub, in VSCode on your PC/laptop open the "remote explorer" pane on the left hand side of the main window, and the connection will be visible under REMOTES (TUNNELS/SSH) -> Tunnels.
69+
70+
!!! note "first time setting up a remote service"
71+
If this is the first time you have followed this procedure, you may have to sign in to GitHub in VSCode.
72+
Click on the Remote Explorer button on the left hand side, and then find the following option:
73+
74+
```
75+
REMOTES(TUNNELS/SSH)
76+
Tunnels
77+
Sign in to tunnels registered with GitHub
78+
```
79+
80+
If you have not signed in to GitHub with VS Code editor, you will be redirected to the browser to sign in.
81+
82+
After signing in and authorizing VSCode, the open tunnel should be visible under REMOTES (TUNNELS/SSH) -> Tunnels.
83+
84+
### Using with uenv
85+
86+
To use a uenv with VSCode, the uenv must be started before calling `code tunnel`.
87+
Log into the target system and start the uenv, then start the remote server, for example:
88+
```
89+
# log into daint (this could be any other Alps cluster)
90+
ssh daint
91+
# start a uenv session on the login node
92+
uenv start --view=default prgenv-gnu/24.11:v1
93+
# then start the tunnel
94+
code tunnel
95+
```
96+
97+
Alternatively, you can execute `code tunnel` directly in the environment:
98+
```
99+
ssh daint
100+
uenv run --view=default prgenv-gnu/24.11:v1 -- code tunnel
101+
```
102+
103+
Once the tunnel is configured, you can access it from VSCode.
104+
105+
!!! warning
106+
If you plan to do any intensive work: repeated compilation of large projects or running python code in Jupyter, please see the guide to running on a compute node below.
107+
Running intensive workloads on login nodes, which are shared resources between all users, is against CSCS [fair usage][policies-fair-use] of Shared Resources policy.
108+
109+
### Using with containers
110+
4111
!!! todo
5-
how to connect VSCode
112+
write a guide
113+
114+
### Running on a compute node
115+
116+
If you plan to do computation using your VSCode, then you should first allocate resources on a compute node and set up your environment there.
117+
118+
!!! example "directly create the tunnel using srun"
119+
You can directly execute the `code tunnel` command using srun:
120+
```
121+
ssh daint
122+
srun --uenv=prgenv-gnu/24.11:v1 --view=default -t120 -n1 --pty code tunnel
123+
```
6124

7-
* with a container
8-
* with a uenv
125+
* `--uenv` and `--view` set up the uenv
126+
* `-t120` requests a 2 hour (120 minute) reservation
127+
* `-n1` requests a single rank - only one rank/process is required for VSCode
128+
* `--pty` allows forwarding of terminal I/O, regired to sign in to Github
129+
130+
Once the job allocation is granted, you will be prompted to log into GitHub, the same as starting a session on the login node.
131+
If you don't want to use a uenv, the command is even simpler:
132+
```
133+
ssh daint
134+
srun -t120 -n1 --pty code tunnel
135+
```
136+
137+
!!! example "log into a node before starting"
138+
It is also possible to log into a compute node before executing the `code tunnel` command, if that suits your workflow:
139+
```
140+
# log into daint
141+
ssh daint
142+
143+
# start an interactive shell session
144+
srun -t120 -n1 --pty bash
145+
146+
# set up the environment before starting the tunnel
147+
uenv start prgenv-gnu/24.11:v1 --view=default
148+
code tunnel
149+
```
150+
151+
* `-t120` requests a 2 hour (120 minute) reservation
152+
* `-n1` requests a single rank - only one rank/process is required for VSCode
153+
* `--pty` allows forwarding of terminal I/O, for bash to work interactively
154+
155+
## Connecting via VSCode UI
156+
157+
!!! warning
158+
This approach is not recommended, because while it may be easier to connect via the VS Code UI, it is much more difficult to configure the connection so that you can use uenv, containers or compute nodes.
159+
160+
!!! todo
161+
Write the guide

‎docs/policies/index.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# CSCS User Policies
2+
3+
The CSCS [code of conduct](code-of-conduct.md) outlines the responsibilities and proper practices for the CSCS user community.
4+
5+
The [User Regulations](regulations.md) define the basic guidelines for the usage of CSCS computing resources. The right to access CSCS resources may be revoked to whoever breaches any of the user regulations.
6+
7+
## Computing Budget
8+
9+
Compute time on Alps systems is accounted in node hours; computing time on CSCS systems that allow node sharing will be accounted in core hours.
10+
11+
Please note that resources at CSCS are assigned over three-months windows
12+
13+
* Quotas are reset on April 1st, July 1st, October 1st and January 1st
14+
* Please make sure to use thoroughly your quarterly compute budget within the corresponding time frame
15+
* Resources unused in the three-month periods are not transferred to the next allocation period but are forever lost
16+
17+
## Data Retention Policies
18+
19+
Data belonging to active projects in the filesystems /users, /project, /store are under backup. There is no backup for data under the scratch filesystem, therefore no data recovery is possible in case of accidental loss or for data deleted due to the cleaning policy implemented on this filesystem.
20+
21+
Please note that the long term storage service is granted as long as your project is active, and the data will be removed without further notice 3 months after the expiration of the project: please check the applicable filesystem policies for the grace period granted after the expiration of the project.
22+
23+
Furthermore, as soon as your project expires, the backup of the data belonging to the project will be disabled immediately: therefore no data backup will be available after the final data removal.
24+
25+
[](){#policies-fair-use}
26+
## Fair Usage of Shared Resources
27+
28+
The [Slurm][slurm] scheduling system is a shared resource that can handle a limited number of batch jobs and interactive commands simultaneously. Therefore users should not submit hundreds of Slurm jobs and commands at the same time, as doing so would infringe our fair usage policy.
29+
30+
Let us also remind you that **running compute or memory intensive applications on the login nodes is forbidden**. Please submit batch jobs with the Slurm scheduler, in order to allocate and run your processes on compute nodes: compute or memory intensive processes affecting the performance of login nodes will be terminated without warning.

‎docs/policies/regulations.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# User Regulations
2+
3+
The User Regulations define the basic guidelines for the usage of CSCS computing resources.
4+
The right to access CSCS resources may be revoked to whoever breaches any of the user regulations.
5+
6+
These are the Terms & Conditions, which users need to follow in order to access CSCS computing resources.
7+
8+
* Access to CSCS facilities is granted on an individual basis. An account is usable by the applicant only and only for the exlpicit purposes stated in the project application. CSCS does not allow sharing of accounts.
9+
* The applicant is not permitted to give any other person (project member or otherwise), organization or representative of any organization access to CSCS facilities explicitly or implicitly, through negligence or carelessness. Revealing of passwords or identification protocols through verbal, written or electronic means is strictly prohibited. Any such activity is considered a breach of CSCS security, the contract between the applicant and CSCS at the moment the Account Application Form is submitted and approved, and the established contracts between CSCS and its computer vendors. Should such activity occur, the applicant will be immediately barred from all present and future use of CSCS facilities and is fully liable for all consequences arising from the infraction.
10+
* Any indication of usage or requests for runs which give rise to serious suspicion will be further investigated and escalated to the appropriate authorities if necessary.
11+
* Access to and use of data of other accounts on CSCS systems without prior consent from the principal investigator to which project the user account pertains is strictly prohibited. The terms and conditions for use of data from other accounts must be directly agreed to by the data owner.
12+
* The applicant confirms that all information provided on his/her Account Application Form is true and accurate, and that she/he has not knowingly misrepresented him/herself.
13+
* The principal investigator should promptly and proactively notify CSCS as soon as the applicants (i.e. the future account owner) should be suspended.
14+
15+
All CSCS account holders are fully bound to obey by the [ETH Zurich Acceptable Use Policy for Telematics Resources](https://rechtssammlung.sp.ethz.ch/Dokumente/203.21en.pdf) (“BOT”).

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,8 @@ nav:
7474
- 'Long Term Storage': storage/longterm.md
7575
- 'Object Storage': storage/object.md
7676
- 'Policies':
77+
- policies/index.md
78+
- 'User Regulations': policies/regulations.md
7779
- 'Code of Conduct': policies/code-of-conduct.md
7880
- 'UserLab Support Policy': policies/support.md
7981
- 'Slack Code of Conduct': policies/slack.md

0 commit comments

Comments
 (0)