Installation
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
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.
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
.
Workbench is bundled with a modified version of 4.14.1 that includes an upgraded version of node (16.20.2).
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
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
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 --extensions-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.
Recommended extensions
We recommend installing the following extensions:
Quarto
The Quarto extension provides language support for .qmd
files. Learn more about Quarto at https://quarto.org.
To pre-install the latest version of the Quarto extension from Open VSX, include the following line in vscode.extensions.conf
:
quarto.quarto
Python
The official Python extension from Microsoft provides rich language support for the Python Language. Features include:
- The ability to create, edit, and execute Jupyter Notebooks
- Code refactoring
- Code auto-completion
- Code formatting
- Debugging tools
- Unit testing tools
To pre-install the latest version of the Python extension from Open VSX, include the following line in vscode.extensions.conf
:
ms-python.python
R
The R extension provides support for the R programming language.
To pre-install the latest version of the R extension from Open VSX, include the following line in vscode.extensions.conf
:
REditorSupport.r
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
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:
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
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 ofcode-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 namedmy-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
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.
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.