.. _software-vscode:

*******
VS Code
*******

Introduction
============
Visual Studio Code (VS Code) is a code editor widely used for software development. Its integration with remote systems via the ``Remote-SSH`` extension allows users to work on HPC clusters directly from their local machines.

However, to facilitate this functionality VS Code runs a program called the ``vscode-server`` on the HPC login nodes, which can significantly degrade performance and negatively impact **all** other users. Moreover, the ``vscode-server`` can remain even after users finish their work and disconnect.

.. warning::
   **Do not run** ``vscode-server`` **on login nodes.** The additional processes can overload these shared resources, leading to slow response times and potential system instability.

.. hint::
   On this page we present different strategies for working with VS Code in our cluster environments while avoiding negatively impacting the login node(s).

Solutions
=========

.. tabs::

    .. tab:: Local Development

        Instead of running VS Code remotely, consider a two-step workflow consisting of

        1. **Editing your code** and then
        2. **Deploying your code** only when ready.

        This workflow offers several advantages:

        - **Improved Performance:** Work on your code without the added latency of a remote connections.
        - **Version Control with Git:** Collaborate with others, track changes and revert them if necessary.
        - **Flexible Deployment Options:** Deploy updates via git, scp, or sftp to the clusters.

        For quick edits on the clusters, such as changing a parameter or a single string inside a file a number of command line editors such as `vi <https://en.wikipedia.org/wiki/Vi_(text_editor)>`_  or `nano <https://en.wikipedia.org/wiki/GNU_nano>`_ are available.

        .. hint::
            This approach is considered best practise.


    .. tab:: Open OnDemand

        A very usable web version of VS Code is available via :ref:`software-ood` (OOD) on the CoSTAR cluster.

        **To launch the OOD editor:**

        1. Log in to :ref:`software-ood` (OOD) on the CoSTAR cluster.
        2. Navigate to the Dashboard and select ``Code Server / System Installed App`` from the landing page or from the Interactive Apps menu.
        3. Fill in the form asking you about number of hours, CPU cores, and amount of RAM.

           A reasonable choice could be 5 hours, 4 cores, 8 GB. The lower your request for resources is, the faster it will be granted by the scheduler.
        4. Click on ``Launch`` to submit your request.
        5. Once the server has allocated your resources, click on ``Connect to VS Code``.

        More about OOD: :ref:`software-ood`

        .. hint::
            This approach is suitable for HPC newcomers.

    .. tab:: Connect to Compute Nodes

        Instead of connecting to the login node, you can configure VS Code to connect directly to a compute node. This method ensures that the ``vscode-server`` process runs on a compute node, keeping the shared login nodes free from heavy load. Your local VS-Code IDE can be configured to ask for a compute node on the cluster in an interactive session.

        .. warning::
            This solution is the technically most advanced option. It does require a certain understanding of SSH configuration and our cluster’s scheduler.

        **Step 1: Modify Your SSH Config File**

        Add the following entries to your SSH config file.

        *For macOS and Linux users:*

        .. code-block:: bash

           Host costar
               HostName costar-login01.surrey.ac.uk
               User ab1234

           Host costar-vscode
               ForwardAgent yes
               StrictHostKeyChecking no
               UserKnownHostsFile=/dev/null
               ProxyCommand ssh costar "/usr/bin/salloc --nodes=1 --ntasks-per-node=2 --time=8:00:00 /bin/bash -c 'nc \$SLURM_NODELIST 22'"
               User ab1234

        *For Windows users, the configuration is nearly identical:*

        .. code-block:: text

           Host costar
               HostName costar-login01.surrey.ac.uk
               User ab1234

           Host costar-vscode
               ForwardAgent yes
               StrictHostKeyChecking no
               UserKnownHostsFile=/dev/null
               ProxyCommand ssh costar "/usr/bin/salloc --nodes=1 --ntasks-per-node=2 --time=8:00:00 /bin/bash -c 'nc $SLURM_NODELIST 22'"
               User ab1234

        This setup creates a special SSH host entry called ``costar-vscode`` that, when connected to, automatically requests and further connects to a compute node via the scheduler.

        For connecting to a running job, see the :ref:`tutorials-ssh-access` guide.

        .. hint::

            1. For detailed instructions on locating and editing your SSH config file, please see our :ref:`ssh-key-setup` page.
            2. Replace ``ab1234`` with **your actual username** .
            3. Change the requested resources, i.e., CPU cores, time (set to 2 and 8 hours in the example above) to your liking.
            4. You might need to adjust the SSH connection timeout limit in VS Code (see Optional Steps below) to allow for the time the scheduler needs to allocate your job request.

        **Step 2: Connect with the VS Code Remote-SSH Extension**

        - Open the Command Palette (``Ctrl+Shift+P`` on Windows/Linux or ``Cmd+Shift+P`` on macOS).
        - Run the command ``Remote-SSH: Connect to Host...``.
        - Select the ``costar-vscode`` host from the list.

        **Optional Steps**

        *Increase the SSH Timeout:*

        - Open VS Code settings (``File > Preferences > Settings`` or ``Code > Settings.. > Settings``).
        - Search for ``remote.SSH.connectTimeout`` and set it to 180 seconds. This should give the scheduler enough time to allocate a compute node.

        *Set Up Passwordless SSH (optional):*

        Configure SSH key authentication for a smoother connection process. See :ref:`ssh-key-setup` for details.