Configuration

VS Code configuration

Configuration of VS Code sessions is handled via the config file /etc/rstudio/vscode.conf. 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.	/usr/lib/rstudio-server/bin/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.	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	Deprecated in favor of `launcher-sessions-clusters`. Comma-delimited list of available Job Launcher clusters for launching VS Code sessions.	`launcher-sessions-clusters` in `rserver.conf`
default-session-cluster	Deprecated in favor of `launcher-default-cluster`. The default Job Launcher cluster to use when launching a VS Code session.	`launcher-default-cluster` in `rserver.conf`
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)
min-ext-version	Setting deprecated starting with Posit Workbench 2022.12.0.

For example, your vscode.conf file might look like the following:

# /etc/rstudio/vscode.conf
exe=/usr/lib/rstudio-server/bin/code-server/bin/code-server
enabled=1
default-session-cluster=Kubernetes
default-session-container-image=rstudio:vscode-session

SSL Configuration

Many VS Code features, including displaying web views, require enabling HTTPS using a trusted certificate. When HTTPS is not enabled or the certificate used is not trusted by the user’s browser, sessions will display a warning dialog informing users that they are using an insecure context, and some functionality will not work as expected. See SSL configuration for instructions on enabling SSL.

VS Code code-server versions

For the best experience, it is recommended to use the code-server version bundled with Workbench (version 4.14.1).

Note

Workbench is bundled with a modified version of 4.14.1 that includes an upgraded version of node (16.20.2).

Due to differences between code-server versions, Posit Workbench needs to know the versions of code-server that is in use. It can be automatically detected by Posit 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=4.14.1

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/lib/rstudio-server/bin/code-server/bin/code-server
args=--host=0.0.0.0 --verbose
user-data-dir=<desired user path>

Note that the specified in the configuration can contain the ~ to represent the user’s home directory.

Whenever a VS Code session is launched, Workbench 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.

A simple template is automatically created for you 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
}

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.

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
the Posit Workbench VS Code extension
Posit Workbench session binaries
If creating container users (see Server configuration), you must have the libuser1-dev or libuser-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.

Varied installation locations

In some cases, the path to code-server might be different depending on where the VS Code session is running. For example, the path to code-server might vary from container to container. By specifying a WORKBENCH_VSCODE_PATH environment variable in your container build, you can ensure that the desired code-server installation will be executed by Workbench. The WORKBENCH_VSCODE_PATH can also be set in the launcher-env file as described in the Launcher environment section. Workbench will resolve which code-server executable should by used with the following priority:

The value of the WORKBENCH_VSCODE_PATH environment variable, if set.
The value of exe as defined in vscode.conf.
Workbench’s internal installation of code-server.
A code-server installation that is on the PATH.

If there is no code-server at any of those locations, VS Code sessions will fail to start.

Note

Please note that code-server must still be installed at the location configured in vscode.conf on the Workbench host. Additionally, the same version of code-server must be installed on the Workbench host and in the containers or on the session hosts.