14 VS Code Sessions (Preview)
14.1 Overview
RStudio Server Pro allows you to launch VS Code sessions from the home page via the Job Launcher, if configured. Users can start VS Code sessions that allow them to work with VS Code while still working within the administrative framework provided by RStudio, such as authentication, PAM session management, etc.
Currently, VS Code Sessions are a Preview feature. The feature itself is stable and usable, but you may find some bugs, and we are still working to complete some aspects of the VS Code development workflow. We highly encourage you to submit your feedback to let us know how we can improve! See the Professional Support section for more information on submitting feedback.
Note: Before VS Code sessions can be launched, the Job Launcher must be setup correctly. For more information, see the Job Launcher section.
Note: RStudio is not affiliated with Microsoft. Your usage of the open source code-server and VS Code are subject to their respective licenses: see here and here.
14.2 Installation
14.2.1 General Installation
In order to add VS Code integration to RSP, you must first install the open-source code-server
wrapper, available at https://rstd.io/vs-code-server. code-server
is a wrapper which allows access to VS Code via a webserver in a browser, allowing RSP to create VS Code sessions and proxy them through the browser.
To install, simply run the command rstudio-server install-vs-code <path to installation directory>
. This will install the code-server
binary, the R and Python extensions, and automatically configure /etc/rstudio/vscode.conf
. For example, to install everything at /opt/code-server
:
# likely need root privilege to install to /opt
sudo rstudio-server install-vs-code /opt/code-server
Once the installation completes, you’ll need to restart the RStudio service for it to detect availability of VS Code sessions.
Note: You must also install code-server on any Launcher nodes (for Local or Slurm plugins) and within any containers used (if using Kubernetes).
If you’d like to install everything manually, simply download the code-server
Linux distributable and extract it to the desired location on the RSP host(s).
For example, to manually install code-server
under /opt
:
# create directory to house code-server
mkdir /opt/code-server
cd /opt/code-server
# download the code server package
wget https://rstd.io/vs-code-server -O vs-code-server.tar.gz
# extract code-server binary
tar zxvf vs-code-server.tar.gz --strip 1
# remove the archive
rm vs-code-server.tar.gz
Note: At the time of writing, only code-server versions 3.2.0 and 2.x have been confirmed to work with RSP.
14.2.2 Installing Language Extensions
code-server
does not provide access to the official Visual Studio Marketplace. There are three ways in which you can add extensions to code-server
:
- Install the extension through
code-server
’s hosted repository. This can be done from within a VS Code session via the UI (similar to how extensions are added in VS Code), or via command line with the following command:
/opt/code-server/code-server --extensions-dir /opt/code-server/extensions --install-extension <extension name>
- Download an extension in VSIX format from an online marketplace such as Open VSX. Then, install it using the
--install-extension
command like the example above, passing the VSIX file path as the extension name. Note that if the latest version of the extension is incompatible with the version of code-server, it will fail to install. You can try using an older version of the extension in this case.
Note: It is against VS Code’s Terms of Service to use the official Marketplace extensions with third party tools like
code-server
. We strongly recommend using a free and open source alternative like Open VSX.
- Build the extension from source. There are several extensions freely available on GitHub that can be built into a VSIX file yourself and then installed via the
--install-extension
command. Building third party extensions from source is outside of the scope of this document.
14.2.2.1 Recommended Extensions
We recommend installing support for both R and Python. If you installed code-server
via the rstudio-server install-vs-code
command (noted above), the R and Python extensions were also installed. However, if you wish to install them manually, follow the instructions below.
To install the Python extension, download and extract the VSIX file into the correct format:
curl -L https://rstd.io/vs-code-python-ext -o ms-python.python-2020.5.86806.vsix.gz && gunzip ms-python.python-2020.5.86806.vsix.gz
Then, install the extension:
/opt/code-server/code-server --extensions-dir /opt/code-server/extensions --install-extension /path/to/ms-python.python-2020.5.86806.vsix
Similarly, to download and install the R extension:
curl -L https://rstd.io/vs-code-r-ext -o Ikuyadeu.r-1.1.0.vsix.gz && gunzip Ikuyadeu.r-1.1.0.vsix.gz
/opt/code-server/code-server --extensions-dir /opt/code-server/extensions --install-extension /path/to/Ikuyadeu.r-1.1.0.vsix
Your extensions will now be available, but when configuring args
in /etc/rstudio/vscode.conf, make sure to add the --extensions-dir=
argument to whatever directory you installed your extensions at.
14.3 Configuration
14.3.1 VS Code Configuration
Configuration of the VS Code feature is handled via the config file /etc/rstudio/vscode.conf
. Note that this file is not automatically created by RStudio, and must be created before being configured, and the VS Code feature is disabled by default. The following table lists the various configuration options that are available to be specified in the vscode.conf
configuration file:
/etc/rstudio/vscode.conf
Config Option | Description | Default Value | |
---|---|---|---|
enabled | Enables launching of VS Code sessions. | 0 (disabled) | |
exe | Path to the code-server executable. VS Code sessions rely on the open source code-server project. For more information, see the project site |
/opt/code-server/code-server | |
args | Arguments to be passed to the code-server command. Note that this does not override the default value - if you wish to use some of the default arguments, you must contain the default arguments in the configuration value. It is strongly recommended that you do not change this unless you know what you’re doing! In almost all configurations, the --host=0.0.0.0 configuration should be set! You can supply an --extensions-dir= to point to previously installed extensions via this parameter. |
--disable-updates --host=0.0.0.0 | |
session-clusters | Comma-delimited list of available Job Launcher clusters for launching VS Code sessions. Leave blank to specify all clusters. | ||
default-session-cluster | The default Job Launcher cluster to use when launching a VS Code session. | ||
default-session-container-image | The default container image to use when launching a containerized VS Code session. | ||
session-container-images | Comma-delimited list of images that may be used for running VS Code sessions. | ||
vscode-session-path | Path to the VS Code Session launcher executable/script. It is recommended that you do not change this unless you know what you’re doing, and you need to point to a different script. | /usr/lib/rstudio-server/bin/vscode-session-run | |
session-no-profile | Enables/disables running of bash profile scripts when starting VS Code sessions. | 0 (run profile scripts) |
For example, your vscode.conf
file might look like the following:
/etc/rstudio/vscode.conf
exe=/usr/bin/code-server
enabled=1
default-session-cluster=Kubernetes
default-session-container-image=rstudio:vscode-session
14.3.2 Launcher Configuration
When creating containerized VS Code sessions via the Job Launcher, you will need to specify mount points as appropriate to mount the users’ home drives and any other desired paths. In order for sessions to run properly within containers, it is required to mount the home directories into the containers.
For more information, see Launcher Mounts. Note that you can specify the Workbench
with VS Code
to configure mount entries that should only be mounted for VS Code sessions.
14.3.3 Container Configuration
When running VS Code sessions in containers, such as by using the Kubernetes Job Launcher plugin, you will need to ensure that the image(s) used to launch VS Code sessions contain, at minimum, the following:
- code-server installation
- RSP session binaries
- If creating container users (see Server Configuration), you must have the
libuser1-dev
orlibuser-devel
packages, depending on your platform to install the libuser library and development tools.
For ease of use, it is recommended that you use the r-session-complete
Docker image as a base for any VS Code session images you intend to create.
14.4 Troubleshooting
If you experience issues related to running VS Code sessions, you can use the Launcher verification tool which will attempt to launch VS Code sessions and provide diagnostic output about what could be going wrong. For more information, see the Troubleshooting section for the Job Launcher integration documentation.