Installation

Workbench

General installation

Starting with Posit Workbench version 2022.12.0, the components needed for VS Code sessions are installed automatically. Additionally, VS Code session support is enabled by default for new installations.

The components are the Posit Workbench VS Code extension and 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.

When upgrading an existing installation where /etc/rstudio/vscode.conf already exists, the prior VS Code settings will continue to be used, including use of the previously installed version of code-server. To switch to the newer VS Code components bundled with Posit Workbench (strongly recommended), make a backup copy of the existing /etc/rstudio/vscode.conf file (for reference), then run the command rstudio-server configure-vs-code. This will provide the option to regenerate /etc/rstudio/vscode.conf to use the bundled VS Code components. If necessary, reapply any customizations from the backup copy of vscode.conf using a text editor. For example:

# need root privilege to modify files under /etc/rstudio
sudo cp /etc/rstudio/vscode.conf /etc/rstudio/vscode.conf.bak
sudo rstudio-server configure-vs-code
Note

When running Posit Workbench 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 Posit 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 configure-vs-code command. Alternatively, vscode.conf can be manually updated to include --extensions-dir after it has been created. For example, to use a global extensions directory at /opt/code-server/extensions:

# likely need root privilege to install to /opt
sudo rstudio-server configure-vs-code --extensions-dir=/opt/code-server/extensions

Any arguments provided to the command 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 Posit Workbench VS Code extension as described in the [Installing the Posit Workbench extension] section.

Once the configuration file is modified, you’ll need to restart the Posit Workbench service for it to detect availability of VS Code sessions.

Note

You must also install the VS Code components on all Launcher nodes (for Local or Slurm plugins) and within any containers used (if using Kubernetes). The Posit Workbench session components package includes the necessary VS Code components.

The Posit Workbench extension

Requirements

For the best experience, it is recommended to use the code-server version bundled with Workbench (version 4.14.1). This is automatic in a new installation. When upgrading from a version prior to 2022.12.0, use the configure-vs-code command mentioned earlier to regenerate the /etc/rstudio/vscode.conf file, or by manually editing it and changing the code-server path to be /usr/lib/rstudio-server/bin/code-server/bin/code-server.

Note

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

Note

Other versions of code-server may work as expected but compatibility is only guaranteed with the version included with Workbench and the older versions mentioned above.

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 Posit 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 Posit 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.6.1 of the R extension from Open VSX, include the following lines in vscode.extensions.conf:

quarto.quarto
REditorSupport.r@2.6.1
Note

When no version is specified, Posit 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.vsix
Note

These extension files must exist on the node where the session is launched, which may differ from where Posit 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, Posit 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.

Databricks

If your team makes use of Databricks, the Databricks extension for VS Code allows you to remotely interact with the Databricks platform. This VS Code extension can make use of Databricks auth-passthrough if it is available and enabled for your Workbench instance.

Manual installation

If you have opted for a global extensions directory you can opt to manually install the Posit 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 the Posit 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 Posit 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 Posit Workbench VS Code extension can be found at /usr/lib/rstudio-server/bin/vscode-workbench-ext/rstudio-workbench.vsix (after installing Posit Workbench).

For example, to install the Posit 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

# Install the extension
/usr/lib/rstudio-server/bin/code-server/bin/code-server --extensions-dir /opt/code-server/extensions --install-extension /usr/lib/rstudio-server/bin/vscode-workbench-ext/rstudio-workbench.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"

# Install the extension
/usr/lib/rstudio-server/bin/code-server/bin/code-server --install-extension /usr/lib/rstudio-server/bin/vscode-workbench-ext/rstudio-workbench.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.

Manually installing extensions

When VS Code sessions are configured with a global extensions directory, users without write access to this directory cannot install extensions, and the extensions marketplace will be disabled. Otherwise, users can 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:

  1. Install the extension through code-server’s hosted repository which by default is configured to use Open VSX. 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:

    code-server --extensions-dir <extensions directory> --install-extension <extension publisher>.<extension name>

    For example, when code-server is installed at the default location and you are using an extensions directory at /opt/code-server/extensions, to install the Python extension from Open VSX, run the following:

    /usr/lib/rstudio-server/bin/code-server/bin/code-server --extensions-dir=/opt/code-server/extensions --install-extension ms-python.python

  2. Download an extension in VSIX format from an online marketplace. 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.

    For example, when code-server is installed at the default location, and you are using an extensions directory at /opt/code-server/extensions, to install an extension file named my-extension.vsix, run the following:

    /usr/lib/rstudio-server/bin/code-server/bin/code-server --extensions-dir=/opt/code-server/extensions --install-extension ./my-extension.vsix
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.

  1. 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.

Posit Workbench 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.