diff --git a/docs/hpc/06_tools_and_software/09_vscode_remote_ssh_torch.mdx b/docs/hpc/06_tools_and_software/09_vscode_remote_ssh_torch.mdx new file mode 100644 index 0000000000..194799fe0b --- /dev/null +++ b/docs/hpc/06_tools_and_software/09_vscode_remote_ssh_torch.mdx @@ -0,0 +1,32 @@ +# Connect VSCode to Torch +This page introduces two ways to connect VSCode to Torch. + +For most users, the recommended way to use a VSCode-like environment on Torch is `code-server` through Open OnDemand. This avoids the Microsoft device authentication prompts required by local VSCode Remote - SSH. + +See [Use code-server on Torch through Open OnDemand](docs/hpc/09_ood/08_vscode.mdx) before using the local VSCode Remote - SSH workflow below. + +Use the following steps only if you specifically need to connect from your local VSCode application. + +## Step 1: Configure Your SSH Client + +Before using local VSCode Remote - SSH, configure your SSH client for Torch by following [Configuring your SSH client](docs/hpc/02_connecting_to_hpc/01_connecting_to_hpc.mdx). + +## Step 2: Connect +Install the VSCode Remote - SSH extension. + +Configure Remote - SSH settings: +- Enable `Remote.SSH: Lockfiles In Tmp` +- Unable `Remote.SSH: Use Flock` + +Because Torch requires Microsoft device authentication during SSH login, VSCode may time out before you finish entering the device code. If this happens, search for Remote.SSH: Connect Timeout and set it to 120. + +Before connecting, open https://microsoft.com/devicelogin and keep it ready. In VSCode Remote Explorer, connect to the Torch login node: torch. When VSCode prompts for Microsoft device authentication, enter the code on the device login page. This may take a few attempts. VSCode may also prompt more than once during setup because it can open multiple SSH connections. + +After authentication, VSCode may take a while to install or start the VSCode server on Torch. If the connection fails during this step, try connecting again. Once the server is installed successfully, future connections are usually more consistent. + +Once connected, open a terminal in the VSCode remote session. The prompt should show that you are on a Torch login node, for example: +```bash +[NetID@torch-login-... ~]$ +``` + + diff --git a/docs/hpc/06_tools_and_software/10_use_jupyter_notebooks_in_vscode_on_torch.mdx b/docs/hpc/06_tools_and_software/10_use_jupyter_notebooks_in_vscode_on_torch.mdx new file mode 100644 index 0000000000..427ae4fca7 --- /dev/null +++ b/docs/hpc/06_tools_and_software/10_use_jupyter_notebooks_in_vscode_on_torch.mdx @@ -0,0 +1,54 @@ +# Use Apptainer Jupyter Notebooks in VSCode on Torch + +This page builds on the general VSCode access instructions in 09_vscode_remote_ssh_torch. Before following this workflow, complete that setup and connect VSCode to the Torch login node. + +## Step 1: Install VSCode Jupyter Support + +After connecting VSCode to the Torch login node, open the Extensions view in the VSCode remote window and search for Jupyter. + +Install or enable the Microsoft Jupyter extension in the remote SSH environment. If the extension is not already installed remotely, VSCode should show an option such as: + +`Install in SSH: torch` + +## Step 2: Start a Dummy Batch Job and Connect to the Compute Node + +After the Jupyter extension is installed or enabled, open a terminal in the VSCode remote session on a Torch login node. + +Interactive jobs on Torch may experience intermittent issues. Some compute nodes may work as expected, while others may not. As a workaround, submit a lightweight dummy batch job and then ssh to the allocated compute node after the job is running. + +For example: + +```bash +sbatch -c4 -t2:00:00 --mem=4G --account= --wrap "sleep infinity" +``` + +Replace `` with the account for your project. After submitting the job, Slurm will print a job ID, for example: + +```bash +Submitted batch job +``` + +Once the job is running, identify the assigned compute node and connect to it from the VSCode terminal using SSH. +Check the job status and assigned node: +```bash +squeue -u $USER +``` + +```bash +ssh csXXX +``` + +After connecting, the terminal prompt should show the compute node: +```bash +[NetID@csXXX ~]$ +``` + +## Step 3: Open the Notebook + +Open the target .ipynb notebook in VSCode. + +## Step 4: Select the Apptainer kernel + +Use the notebook kernel picker to select the Apptainer kernel for the notebook. + +If the Apptainer kernel does not appear, confirm that the kernel is installed and visible on Torch before retrying in VSCode. diff --git a/docs/hpc/09_ood/08_vscode.mdx b/docs/hpc/09_ood/08_vscode.mdx new file mode 100644 index 0000000000..c8ec956d3e --- /dev/null +++ b/docs/hpc/09_ood/08_vscode.mdx @@ -0,0 +1,33 @@ +# Use `code-server` on Torch through Open OnDemand + +Torch provides `code-server` as an Open OnDemand interactive app that runs a VSCode-like editor in your web browser. + +For most users who want a VSCode-like development environment on Torch, `code-server` is the recommended option. It avoids the Microsoft device authentication prompts required by local VSCode Remote - SSH. + +## Step 1: Launch the `code-server` App + +From the Open OnDemand dashboard, open **Interactive Apps** from the top navigation bar and select **Code Server**. + +![Code Server app in the Interactive Apps menu](docs/hpc/09_ood/static/code_server.png) + +Configure the session options for your work. For example, select the number of cores, memory, GPU type, Slurm account, working directory, and session duration. + +![Code Server Configuration](docs/hpc/09_ood/static/code_server_configuration.png) + +Click **Launch**. Open OnDemand will submit a job for the `code-server` session. + +## Step 2: Connect to the `code-server` Session + +After the job starts running, the session card will show the assigned host, session status, and remaining time. + +Click `Connect to VS Code`. + +![Code Server Job](docs/hpc/09_ood/static/code_server_job.png) + +This opens a VSCode-like editor in your browser. You can browse and edit files on Torch and use the terminal provided in the session. + +## Why Use `code-server` Instead of Local VSCode Remote - SSH? + +Using `code-server` through Open OnDemand can be easier than using local VSCode Remote - SSH because authentication and job submission are handled through Open OnDemand. Users do not need to complete separate Microsoft device authentication prompts in VSCode, submit a dummy batch job manually, or connect to the assigned compute node from a local VSCode session. + +If you specifically need to use the local VSCode desktop application, see [Connect VSCode to Torch](docs/hpc/06_tools_and_software/09_vscode_remote_ssh_torch.mdx). diff --git a/docs/hpc/09_ood/static/code_server.png b/docs/hpc/09_ood/static/code_server.png new file mode 100644 index 0000000000..7f92080cc0 Binary files /dev/null and b/docs/hpc/09_ood/static/code_server.png differ diff --git a/docs/hpc/09_ood/static/code_server_configuration.png b/docs/hpc/09_ood/static/code_server_configuration.png new file mode 100644 index 0000000000..00822d00f1 Binary files /dev/null and b/docs/hpc/09_ood/static/code_server_configuration.png differ diff --git a/docs/hpc/09_ood/static/code_server_job.png b/docs/hpc/09_ood/static/code_server_job.png new file mode 100644 index 0000000000..3c51725bd1 Binary files /dev/null and b/docs/hpc/09_ood/static/code_server_job.png differ diff --git a/docs/hpc/13_tutorial_intro_hpc/05_environment_variables.mdx b/docs/hpc/13_tutorial_intro_hpc/05_environment_variables.mdx index 5f3004afd5..52958f9305 100644 --- a/docs/hpc/13_tutorial_intro_hpc/05_environment_variables.mdx +++ b/docs/hpc/13_tutorial_intro_hpc/05_environment_variables.mdx @@ -137,6 +137,7 @@ hostname echo "This job was launched in the following directory:" echo ${SLURM_SUBMIT_DIR} +``` :::