Installation
General Installation
In order to add VS Code integration to RStudio Workbench, you must first install the open-source code-server wrapper. This wrapper allows access to VS Code via a web server in a browser, allowing Workbench 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, and automatically configure /etc/rstudio/vscode.conf.
When running RSW behind an external proxy, the HTTPS_PROXY environment variable must be set to the hostname or IP address of your proxy server when installing the VS Code wrapper and RStudio Workbench VS Code extension.
The default configuration will allow users to manage their own extensions; if use of a global extensions directory is desired, then it may be passed as an option to the install-vs-code command. Alternatively, vscode.conf can be manually updated to include --extensions-dir after it has been created. For example, to install everything at /opt/code-server with per-user extensions directories:
# likely need root privilege to install to /opt
sudo rstudio-server install-vs-code /opt/code-serverTo install everything at /opt/code-server with a global extensions directory at /opt/code-server/extensions:
# likely need root privilege to install to /opt
sudo rstudio-server install-vs-code /opt/code-server --extensions-dir=/opt/code-server/extensionsAny arguments after the installation directory will be added to the args entry in vscode.conf, which is supplied to the code-server binary when the session is started. Note that if a global extensions directory is provided this way, this command will also automatically install the RStudio Workbench VS Code extension as described in the Installing the RStudio Workbench Extension section.
Once the installation completes, you’ll need to restart the RStudio service for it to detect availability of VS Code sessions.
You must also install code-server on all Launcher nodes (for Local or Slurm plugins) and within any containers used (if using Kubernetes).
Installing the RStudio Workbench Extension
Requirements
The RStudio Workbench extension requires at least code-server 3.9.3, however code-server version 4.4.0 is recommended in order to enable SSL communication between code-server and RStudio Workbench. While other versions may work as expected, compatibility is only guaranteed with versions 3.9.3 and 4.4.0. The install-vs-code-ext command can upgrade code-server automatically for you if you include the -d flag with the directory that code-server should be installed in. For example, your command may look like this:
rstudio-server install-vs-code-ext -d /opt/code-serverInstallation
If using a global extensions directory, the install-vs-code-ext script can be used to install the latest version of the extension. This script is run while upgrading RStudio Workbench, but may fail with a warning if the version requirement is not met.
If allowing user extension directories, and the requirements above are met, the extension will be installed on a per user basis when the user launches their first VS Code session. When running RStudio Workbench behind a proxy, the HTTPS_PROXY variable must be set to the hostname or IP address of the proxy server during this installation; this can be configured by setting the variable in the Launcher Environment.
Pre-Installing VS Code Extensions
Admin Configuration
Administrators can configure a list of extensions that will be installed for all users by creating a vscode.extensions.conf file. The file should contain a list of extensions with each extension on its own line. If the extension is to be installed from Open VSX, the line should include the full extension ID, including the publisher. For example, to install the latest version of the Quarto extension and version 2.3.8 of the R extension from Open VSX, include the following lines in vscode.extensions.conf:
quarto.quarto
Ikuyadeu.r@2.3.8When no version is specified, RStudio Workbench attempts to install the most recent release, which may or may not be compatible with the active code-server version. To ensure compatibility between extensions and code-server, we recommend specifying a version for each extension and updating the version(s) with each upgrade of code-server.
Alternatively, paths to local extension files (.vsix) can be included:
/opt/code-server/company-extensions/company-extension-1.0.1.vsixThese extension files must exist on the node where the session is launched, which may differ from where RStudio Workbench is installed (such as in Kubernetes and Slurm environments).
Each line of the file is passed directly to code-server’s install extension command allowing any argument or format accepted by this command to be included. To test out your command, you can run the following (omitting --extensions-dir if not using a global extensions directory):
code-server --extension-dir=/opt/code-server/extensions --install-extension <test-line>Installation
If configured with a global extensions directory, the admin must run rstudio-server install-vs-code-ext to install the extensions from vscode.extensions.conf.
If users are managing their own extensions, RStudio Workbench will install the extension list when a user launches VS Code sessions. Depending on the network speed and number of extensions, this could cause lead to a noticeable increase in session load time the first time a user starts a VS Code session.
Extensions being installed from Open VSX will not be re-installed unless they are passed the --force argument in vscode.extensions.conf. However, extensions installed from a local copy will be re-installed each time the installation is attempted. If a significant number of extensions are being installed in this way, we recommend configuring your environment to use a global extension directory to prevent increased session start times.
Manual Installation
code-server can be installed manually, if desired. Additionally, if you have opted for a global extensions directory you can also opt to manually install the RStudio Workbench VS Code extension, and it may be necessary to manually install any other extensions that you require, if users will not have write access to the extensions directory.
Manually Installing code-server
If you’d like to install code-server manually, simply download the code-server Linux distributable (available at https://rsw-vscode-extension.s3.amazonaws.com/code-server/code-server-4.4.0-linux-amd64.tar.gz) and extract it to the desired location on the RStudio Workbench 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://rsw-vscode-extension.s3.amazonaws.com/code-server/code-server-4.4.0-linux-amd64.tar.gz -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.gzManually Installing the RStudio Workbench VS Code Extension
When VS Code sessions are configured with a global extensions directory, it is possible to manually install the VS Code extension rather than using the provided install-vs-code-ext script. If VS Code sessions are not configured with a global extensions directory, the RStudio Workbench VS Code Extension will be automatically installed the first time a user launches a VS Code session. It is still possible to manually install the extension in this circumstance, however the operation will have to be performed for every user.
The RStudio Workbench VS Code extension can be downloaded from https://rsw-vscode-extension.s3.amazonaws.com/rstudio-workbench-1.1.7.vsix. The current latest version is 1.1.7.
For example, to install the RStudio Workbench VS Code extension to the global extension directory /opt/code-server/extensions:
# Ensure the extension directory exists
mkdir -p /opt/code-server/extensions
cd /opt/code-server/extensions
# Download the extension
export RSW_EXT_VERSION=1.1.7
wget https://rsw-vscode-extension.s3.amazonaws.com/rstudio-workbench-${RSW_EXT_VERSION}.vsix -O rstudio-workbench-${RSW_EXT_VERSION}.vsix
# Install the extension
/opt/code-server/code-server --extensions-dir /opt/code-server/extensions --install-extension ./rstudio-workbench-${RSW_EXT_VERSION}.vsixTo install the extension manually on behalf of a particular user, when not using a global installation directory, run the following commands as the desired user:
# Ensure the extension directory exists
mkdir -p "${XDG_DATA_HOME:-~/.local/share}/rstudio"
cd "${XDG_DATA_HOME:-~/.local/share}/rstudio"
# Download the extension
export RSW_EXT_VERSION=1.1.7
wget https://rsw-vscode-extension.s3.amazonaws.com/rstudio-workbench-${RSW_EXT_VERSION}.vsix -O rstudio-workbench-${RSW_EXT_VERSION}.vsix
# Install the extension
/opt/code-server/code-server --install-extension ./rstudio-workbench-${RSW_EXT_VERSION}.vsixInstalling the extension manually when a global installation directory is not in use will require you to repeat the operation for every user.
Manually Installing Extensions
When VS Code sessions are configured with a global extensions directory, users without write access to this directory will not be able to install extensions and the extensions marketplace will be disabled. Otherwise, users are able to manage their own extensions, and installs must be performed on a per user basis by the user. There are three ways in which extensions can be installed:
- Install the extension through
code-server’s hosted repository. This can be done from within a VS Code session via the UI. Alternatively, this can be done via the command line with the following command, with the--extensions-dirargument omitted when a global directory is not in use:
/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-extensioncommand 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 ofcode-server, it will fail to install. You can try using an older version of the extension in this case.
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-extensioncommand. Building third party extensions from source is outside of the scope of this document.
RStudio does not provide support for external extensions. If you have questions or issues we encourage you to check Stack Overflow, the extension’s repository, or the code-server repository.