14 VS Code Sessions
14.1 Overview
RStudio Workbench 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.
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.1.1 RStudio Workbench Extension
VS Code sessions are intended to be used with the RStudio Workbench VS Code extension installed. The extension provides users with a button to open the RStudio Workbench homepage in a new tab. Because VS Code sessions are running remotely, any web server a user may be developing, such as Shiny, Dash, or Streamlit, will also be running remotely. The RStudio Workbench VS Code extension allows users to access these remote web servers through their browser. If the extension is not installed, VS Code sessions will launch but without the additional features; users working on these types of apps will not be able to access the servers they are running on.
14.2 Installation
14.2.1 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
.
VS Code utilizes extensions to provide support for different languages and other features, such as custom themes. Normally extensions are managed by a user who installs them through an extension marketplace onto their desktop. For RStudio Workbench, you need to decide if users will be able to install extensions individually themselves, or if you will provide a global installation of extensions. User installation of extensions provides the most flexibility and is consistent with a user’s desktop experience. However, if RStudio Workbench will be in a restricted or airgapped network, admins may need to install extensions globally for users.
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-server
To 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/extensions
Any 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.
Note: You must also install code-server on all Launcher nodes (for Local or Slurm plugins) and within any containers used (if using Kubernetes).
14.2.2 Installing the RStudio Workbench Extension
14.2.2.1 Requirements
The RStudio Workbench extension requires code-server
3.9.3. While later versions may work as expected, compatibility is only guaranteed with version 3.9.3. 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-server
14.2.2.2 Installation
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.
14.2.3 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.
14.2.3.1 Manually Installing code-server
If you’d like to install code-server
manually, simply download the code-server
Linux distributable (available at https://rstd.io/vs-code-server-3-9-3) 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://rstd.io/vs-code-server-3-9-3 -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
14.2.3.2 Manually 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.0.4.vsix. The current latest version is 1.0.4.
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.0.4
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}.vsix
To 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.0.4
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}.vsix
Note: Installing the extension manually when a global installation directory is not in use will require you to repeat the operation for every user.
14.2.3.3 Manually Installing Language 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-dir
argument 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-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 ofcode-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.
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.
14.3 Configuration
14.3.1 VS Code Configuration
Configuration of VS Code sessions is handled via the config file /etc/rstudio/vscode.conf
. Note that this file is not automatically created by RStudio and must be created manually or with the install-vs-code
script, as VS Code sessions are 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/bin/code-server | |
version | The version of VS Code code-server being used. If set to auto , the version is automatically detected by running the code-server version command. If VS Code is being launched via the Launcher and is not installed locally, you are strongly encouraged to set this to the version in use. Running against multiple different code-server versions simultaneously in different Launcher clusters is not supported - they must all be running the same version, or issues will occur. |
cur. | auto |
|
args | Arguments to be passed to the code-server launch command. You can supply an --extensions-dir= to point to previously installed extensions via this parameter. If no --host argument is supplied, a default of --host=0.0.0.0 will be assumed. |
| | --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 VS Code code-server Versions
Currently, RStudio Workbench supports code-server
3.9.3. Due to differences between code-server
versions, RStudio Workbench needs to know the versions of code-server
that is in use. It can be automatically detected by RStudio Workbench on start up by running the code-server
command, or can be specified by using the version
setting in /etc/rstudio/vscode.conf. Automatic version detection is done if the default value of auto
is used.
If you are running VS Code in a remote cluster like Kubernetes, you will need to manually specify the version of code-server
if it is not locally installed or is not running the same version as the remote cluster. Due to version differences, running against multiple different versions of code-server
in different Launcher clusters simultaneously is not supported - the versions must match in all clusters.
You can manually specify the version number like so:
/etc/rstudio/vscode.conf
version=3.9.3
14.3.3 VS Code User Settings
By default, code-server
writes VS Code user settings under ~/.local/share/code-server
. This can be changed by adding the user-data-dir
path argument to the VS Code options, like so:
/etc/rstudio/vscode.conf
exe=/usr/bin/code-server
args=--host=0.0.0.0 --verbose
user-data-dir=<desired user path>
Note that the ~
to represent the user’s home directory.
Whenever a VS Code session is launched, RStudio automatically merges the user settings template file at /etc/rstudio/vscode-user-settings.json
with the user’s settings file. This file should be a valid JSON file that contains desired VS Code user settings. Any matching settings that already exist in the user settings file are not overridden, allowing users the freedom to customize their environment. You should use the vscode-user-settings.json
file to provide them with a simple baseline configuration.
If you installed VS Code via the sudo rstudio-server install-vs-code
command, a simple template is created for you automatically which instructs VS Code to use the bash shell by default and to disable automatic extension updates. The generated file looks like the following:
**/etc/rstudio/vscode-user-settings.json
{
"terminal.integrated.shell.linux": "/bin/bash",
"extensions.autoUpdate": false,
"extensions.autoCheckUpdates": false
}
14.3.4 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.
Note: Only a user’s home folder is visible within VS Code sessions. To access other folders, create symbolic links to them within the home folder.
14.3.5 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
3.9.3 binary- RStudio Workbench 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 Multiple Sessions
Multiple VS Code windows with distinct processes and projects can be opened within the same VS Code session in separate browser windows. Closing a VS Code session window causes the processes associated with that window to exit, while other processes associated with the same session will remain running.
After a user closes all windows associated with a session, restarting the session from the RStudio Workbench homepage will open the last project that the user opened in this session. The order in which the windows are closed does not impact this. Reopening the VS Code Workspace or folder the user was previously working in will return the window to the state that it was left in.
14.5 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.