Upgrade

Workbench

These instructions describe the configuration requirements and how to upgrade Posit Workbench from a supported product version to the latest version.

To upgrade from Open Source to Workbench, follow the procedures available in the Upgrading from Open Source to Workbench section.

Upgrade requirements

Important

These instructions only cover upgrading Posit Workbench on the same server and between supported versions. If you are planning on changing servers or you are upgrading from an older unsupported version, please see the How to Upgrade and/or Migrate Posit Team guide.

The following document covers adjustments that may need to be made to your configuration due to breaking changes between versions. To use this document, select the version you are currently on, or start at the oldest version that is newer than your version from the list below, and then follow the instructions until the end of the page:


Starting with Posit Workbench version 2022.12.0:

  • The components needed for VS Code sessions are installed automatically.
  • By default, VS Code session support is enabled for new installations.

When upgrading an existing installation where /etc/rstudio/vscode.conf already exists:

  • Priorly configured VS Code settings are still applied, including the use of the previously installed versions of code-server.
  • Posit strongly recommends switching to the newer VS Code components bundled with Posit Workbench.

To switch to the newer VS Code components:

  1. Complete the Upgrade Procedures section below.

  2. For reference, make a backup copy of the existing /etc/rstudio/vscode.conf file.

  3. Then, run:

    rstudio-server configure-vs-code

This provides 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.

See the VS Code Installation page of the Admin Guide for more information and examples.

Breaking Change

Workbench 2023.09 temporarily removed support for using an encrypted password in database.conf for PostgreSQL. 2023.09.1 added support SSL certificate authentication for database connections. In 2023.12 database password encryption has been restored. Both mechanisms are now supported.

There are also some optional recommended configuration changes for Workbench 2023.09+:

Increase Server Thread Pool Size

For servers that manage sessions for more than a few users, set www-thread-pool-size=8 in rserver.conf. The default value of 2 can reduce performance when the server is handling lots of requests at the same time.

Launcher Session Clusters

The following configuration settings have been deprecated from the vscode.conf and jupyter.conf configuration files:

  • session-clusters
  • default-session-clusters

In previous versions of Posit Workbench, the following settings in rserver.conf exclusively applied to RStudio Pro Sessions, but will now apply to all sessions:

  • launcher-sessions-clusters
  • launcher-adhoc-clusters
  • launcher-default-cluster

When set, the VS Code and Jupyter session specific cluster configurations will continue to apply to those sessions, but we recommend updating your configuration to use the global settings instead.

Load Balancing

A new configuration option, load-balancing-enabled, was added to rserver.conf. When set to 0, this option disables load-balancing. When set to 1, load-balancing is enabled even without the presence of the load-balancer configuration file. If the option is not set, and the load-balancer configuration file is present, Workbench will enable load-balancing as in previous releases.

The option delete-node-on-exit was added to the load-balancer configuration file. If you are deploying a load-balanced configuration of Workbench in Kubernetes, we recommend setting this option to 1. This removes the Workbench server’s database entry on shutdown so that stale node entries are not left in the database.

Continue to the Upgrade Procedures section below.

No changes required.

Upgrade Procedures

  1. Notify users ahead of time of the upgrade. You can use the admin notification feature.

  2. Check if there are any active sessions running:

    sudo rstudio-server active-sessions

  • If there are active sessions, then suspend all active user sessions:

    sudo rstudio-server suspend-all

  1. Put the old version of the server into offline mode:

    sudo rstudio-server offline

  2. Download and upgrade Workbench:

$ curl -O https://download2.rstudio.org/server/rhel9/x86_64/rstudio-workbench-rhel-?var:version-x86_64.rpm
$ sudo yum install rstudio-workbench-rhel-?var:version-x86_64.rpm
$ curl -O https://download2.rstudio.org/server/rhel8/x86_64/rstudio-workbench-rhel-?var:version-x86_64.rpm
$ sudo yum install rstudio-workbench-rhel-?var:version-x86_64.rpm
$ curl -O https://download2.rstudio.org/server/centos7/x86_64/rstudio-workbench-rhel-?var:version-x86_64.rpm
$ sudo yum install rstudio-workbench-rhel-?var:version-x86_64.rpm
$ curl -O https://download2.rstudio.org/server/focal/amd64/rstudio-workbench-?var:version-amd64.deb
$ sudo apt-get install ./rstudio-workbench-?var:version-amd64.deb
$ curl -O https://download2.rstudio.org/server/jammy/amd64/rstudio-workbench-?var:version-amd64.deb
$ sudo apt-get install ./rstudio-workbench-?var:version-amd64.deb
$ curl -O https://download2.rstudio.org/server/opensuse15/x86_64/rstudio-workbench-?var:version-x86_64.rpm
$ sudo zypper install rstudio-workbench-?var:version-x86_64.rpm
Note

For older versions of RStudio/Workbench, please review the Previous Versions page.

  1. Restart the server:

    sudo rstudio-server restart

  2. Put the new version online:

    sudo rstudio-server online

The service will never be truly down (in the sense that users see a failure to connect). The offline mode keeps users from trying to start new sessions while you’re doing the upgrade.

Your configuration and settings remain unchanged from the previous version, and if you are running Workbench, your license status remains untouched as well.

Back to top