Skip to content

Upgrade Workbench#

RStudio is now Posit!

Our professional products have been renamed to Posit Connect, Posit Workbench, Posit Package Manager, Posit Cloud, and Posit Academy so it’s easier for folks to understand that we support more than just R. Please review our Blog post/FAQ to answer commonly asked questions about the rebrand.

These procedures are to upgrade Workbench.

Upgrade Requirements#

Important

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 upgrade to 2021.09.0+.

Please review the Release Notes to decide what version best suits your current needs.

Upgrading to Version 2021.09.0+#

Your current version:

  • RStudio Server Pro1 or RStudio Workbench versions prior to 1.4:
    • If you are running an RStudio Server Pro or RStudio Workbench versions prior to 1.4 and would like to upgrade to RStudio Server Pro or RStudio Workbench version 1.4 or greater, then you first must review/complete the Upgrading to RStudio Server Pro / RStudio Workbench 1.4 procedures on the previous page.
  • 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.

You have no added administrative requirements and can skip to the Upgrade procedures section below if you:

  • Have only one RStudio Workbench node (including integration with Kubernetes or Slurm via the Launcher)
  • Do not set any of the following options in your rsession.conf configuration file:
    • session-env-var-save-blacklist
    • directory-view-whitelist

If you do not meet one or more of the requirements listed above, then continue with the following sections.

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 a requirement 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 have been 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 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 lower case 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 the RStudio Server and Session configured to run the filebase server in the session rather than the RStudio Server. This configuration is no longer supported and related options have been removed. Project Sharing will now be coordinated by the RStudio Server, 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:

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.

Upgrade Procedures#

Caution

Review the Upgrade Requirements for the applicable 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.

Note

If you perform an 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
  • Currently, connected browser clients are notified that a new version is available and automatically refresh themselves.
  • The core server binary is restarted

This includes the following behavior:

  • Running R sessions are suspended so that future interactions with the server automatically launch the updated R session binary
  • Currently, connected browser clients are notified that a new version is available and automatically refresh themselves.
  • The core server binary is restarted
  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
  1. Download and upgrade Workbench:
$ curl -O https://download2.rstudio.org/server/rhel8/x86_64/rstudio-workbench-rhel-2022.07.2-576.pro12-x86_64.rpm
$ sudo yum install rstudio-workbench-rhel-2022.07.2-576.pro12-x86_64.rpm
$ curl -O https://download2.rstudio.org/server/centos7/x86_64/rstudio-workbench-rhel-2022.07.2-576.pro12-x86_64.rpm
$ sudo yum install rstudio-workbench-rhel-2022.07.2-576.pro12-x86_64.rpm
$ sudo apt-get install gdebi-core
$ curl -O https://download2.rstudio.org/server/bionic/amd64/rstudio-workbench-2022.07.2-576.pro12-amd64.deb
$ sudo gdebi rstudio-workbench-2022.07.2-576.pro12-amd64.deb
$ sudo apt-get install gdebi-core
$ curl -O https://download2.rstudio.org/server/jammy/amd64/rstudio-workbench-2022.07.2-576.pro12-amd64.deb
$ sudo gdebi rstudio-workbench-2022.07.2-576.pro12-amd64.deb

$ curl -O https://download2.rstudio.org/server/opensuse15/x86_64/rstudio-workbench-2022.07.2-576.pro12-x86_64.rpm $ sudo zypper install rstudio-workbench-2022.07.2-576.pro12-x86_64.rpm}

For older versions of RStudio, please review the Older 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.


  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