Skip to content

Upgrade Posit Workbench#

STOP! - If your version is less than RStudio Server Pro 1.4, contact support before continuing

If you are running RStudio Server Pro versions prior to 1.4, then you must contact support for assistance with upgrading your system to the newest version of Posit Workbench.

The procedures below will not work for your environment.

Overview#

These instructions describe the configuration requirements and how to upgrade Posit Workbench, formerly RStudio Workbench and RStudio Server Pro1.

Posit End User License Agreement

This page includes instructions for downloading Posit professional products. Download and/or use of these products is governed under the terms of the Posit End User License Agreement. By downloading you agree to the terms posted there.

Requirements#

  • Your environment must be running RStudio Server Pro or RStudio Workbench version 1.4, or greater (including versions of Posit Workbench)

Upgrade#

Before you begin:

  • These upgrade procedures are not incremental.
    • Therefore, if you wish to upgrade to versions 2022.02.0+, then you do not need to complete the section to Upgrading to 2021.09.0+.
  • We recommend that you upgrade to the latest version of Workbench. Please review the Release Notes prior to performing an upgrade.
If you want to upgrade from Open Source to Workbench

For Open Source to Workbench:

  • If you currently have RStudio Server Open Source installed and want to upgrade to Workbench, then please follow the procedures available in the Upgrading from Open Source to Workbench section of the support article.

Upgrade Behavior#

If you upgrade of Workbench and an existing version of the server is currently running, then the upgrade process will also ensure that active sessions are immediately migrated to the new version.

This includes the following behavior:

  • Running R sessions are suspended so that future interactions with the server automatically launch the updated R session binary.
  • Connected browser clients are notified that a new version is available and automatically refreshes themselves.
  • The core server binary restarts.

Upgrading to Version 2021.09.0+#

RStudio Server Pro or RStudio Workbench version is currently version 1.4 or greater:

  • If your RStudio Server Pro or RStudio Workbench version is currently version 1.4 or greater, and you would like to upgrade to RStudio Workbench version 2021.09.0 or greater, there may be additional configuration updates required for your upgrade, which are available below.

Administrative requirements#

Confirm that you have no added administrative requirements to complete prior to an upgrade.

If the options listed above do not apply to your configuration, skip to the Upgrade procedures section.

Load Balancing Configuration#

Recommended, if load-balancing

The formatting of the load balancing configuration file has changed. The prior format of this file is still supported, but it is highly recommended that you update your configuration files now to prevent issues with future releases.

To update a load-balanced RStudio Workbench cluster to 2021.09.0 or greater, you need to stop all nodes in the cluster and then make the following changes to the configuration file on each node:

  1. Remove the [config] header.
  2. Add a new option www-host-name set to the hostname or IP address of the node whose configuration you are currently updating. This is the address that other nodes in the cluster can reach this node at. It should already be listed under the [nodes] section of this file.
  3. Remove the [nodes] header and each node entry under this header.

Note

It is no longer required that the load balanced configuration file be identical across nodes.

For complete details on configuring load balancing with RStudio Workbench, see the RStudio Workbench Professional Edition Admin Guide.

Session Configuration#

Required, if using applicable options

The following name changes were made to the optional, user-configurable, rsession.conf options:

If your configuration is using either of these rsession.conf options (session-env-var-save-blacklist and/or directory-view-whitelist):

  • You need to update the legacy names to reflect the renamed changes for these options prior to updating to a newer version of RStudio Workbench.
Create container user changes#

If your system uses the Job Launcher option launcher-sessions-create-container-user=1 in launcher.conf, RStudio Workbench now, by default, creates supplemental groups as well as the user's primary group.

If enumerating groups in your environment is expensive or these extra groups are not desired, then:

  • Set the option launcher-sessions-container-forward-groups=0 to disable supplemental group creation.
Username aliases now supported#

Systems using Active Directory, or LDAP may support more than one username for the same UNIX user ID. They may support upper and lowercase aliases or may allow users to log in with their email address as well as their normal UNIX username.

  • In this version of RStudio Workbench, any valid username for a user may be used to authenticate the user.
  • Once authenticated, the canonical username for that user's ID will be used by the system.

Upgrading to Version 2022.02.0+#

If you would like to upgrade to RStudio Workbench version 2022.02.0 or greater, there may be additional configuration updates required for your upgrade:

  • Some systems with project sharing enabled may have Posit Workbench configured to manage shared files in the session rather than in RStudio Server or Posit Workbench. This configuration is no longer supported, and related options have been removed. Project Sharing will now be coordinated by Posit Workbench, rather than sessions.
  • If your system is configured in this manner, the following changes must be made to your system's configuration files to prior to updating to a new version of RStudio Workbench:

Administrative requiremnts#

Server Configuration#

In rserver.conf:

  • Remove rsession-collab-server
Session Configuration#

In rsession.conf:

  • Remove rsession-collab-server
  • Remove filebase-path

Once you have made any required updates, please continue to the next section.

Upgrading to Version 2022.07.0+#

There are no additional requirements to upgrade to version 2022.07.0+. Continue to the Upgrade Procedures section below.

Upgrading to Version 2022.12.0+#

VS Code#

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:

  • Complete the Upgrade Procedures section below.
  • Make a backup copy of the existing /etc/rstudio/vscode.conf file (for reference).
  • 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.

Upgrading to Version 2023.03.0+#

There are no additional requirements to upgrade to version 2023.03.0+. Continue to the Upgrade Procedures section below.

Upgrade Procedures#

STOP! - If your version is less than RStudio Server Pro 1.4, contact support before continuing

If you are running RStudio Server Pro versions prior to 1.4, then you must contact support for assistance with upgrading your system to the newest version of Posit Workbench.

The procedures below will not work for your environment.

Important

Review the applicable Upgrade - Administrative Requirements sections (above) for the desired version that you wish to upgrade to prior to continuing with this section.

There are additional configuration requirements that must be satisfied for a successful upgrade. Failure to do so may result in an unsuccessful upgrade with configuration issues.

  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
    1. If there are active sessions, then suspend all active user sessions: sudo rstudio-server suspend-all.
  3. Put the old version of the server into offline mode: sudo rstudio-server offline.
  4. Download and upgrade Workbench:
$ curl -O https://download2.rstudio.org/server/rhel8/x86_64/rstudio-workbench-rhel-2023.03.0-386.pro1-x86_64.rpm
$ sudo yum install rstudio-workbench-rhel-2023.03.0-386.pro1-x86_64.rpm

$ curl -O https://download2.rstudio.org/server/centos7/x86_64/rstudio-workbench-rhel-2023.03.0-386.pro1-x86_64.rpm
$ sudo yum install rstudio-workbench-rhel-2023.03.0-386.pro1-x86_64.rpm

$ curl -O https://download2.rstudio.org/server/rhel9/x86_64/rstudio-workbench-rhel-2023.03.0-386.pro1-x86_64.rpm
$ sudo yum install rstudio-workbench-rhel-2023.03.0-386.pro1-x86_64.rpm

$ sudo apt-get install gdebi-core
$ curl -O https://download2.rstudio.org/server/bionic/amd64/rstudio-workbench-2023.03.0-386.pro1-amd64.deb
$ sudo gdebi rstudio-workbench-2023.03.0-386.pro1-amd64.deb

$ sudo apt-get install gdebi-core
$ curl -O https://download2.rstudio.org/server/jammy/amd64/rstudio-workbench-2023.03.0-386.pro1-amd64.deb
$ sudo gdebi rstudio-workbench-2023.03.0-386.pro1-amd64.deb

$ curl -O https://download2.rstudio.org/server/opensuse15/x86_64/rstudio-workbench-2023.03.0-386.pro1-x86_64.rpm
$ sudo zypper install rstudio-workbench-2023.03.0-386.pro1-x86_64.rpm

For older versions of RStudio, 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 will remain untouched as well.

Additional information#

For more information about upgrading RStudio Workbench, navigate to section 2.1.6 Upgrading to a New Version of the Admin Guide.

For addition information about Upgrading to a later version of RStudio Server, please reference this Support Article.

  1. You may still find references to “RStudio” in our documentation, and some of those are expected! Several of our open source products like the RStudio IDE will retain their original names, while our professional products’ names have changed to “Posit”, e.g., Posit Connect. To minimize user confusion, past versions of our professional products will go by their old names until they are no longer supported. For more information about our product names, please see the rebranding blog post. ↩

Copyright © Posit Software, PBC formerly RStudio, PBC. All Rights Reserved.