Skip to content

Upgrade RStudio Workbench#

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

Upgrade Paths#

Note

If you perform an upgrade of RStudio 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

For RStudio Server Pro or RStudio Workbench version 1.4, or greater:

  • If you are running an RStudio Server Pro or RStudio Workbench version 1.4 or greater, then skip ahead to the Upgrading to Version 2021.09.0+ section below.

For Open Source to Workbench:

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

For RStudio Server Pro versions prior to 1.4:

  • If you are running an RStudio Server Pro version 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 complete the next section (Requirements for Upgrading to Version 1.4+) before continuing to the upgrade procedures.

Upgrading to Version 1.4+#

Requirements#

If you are running an RStudio Server Pro version prior to 1.4 and would like to upgrade to RStudio Server Pro or RStudio Workbench version 1.4 or greater, there may be additional configuration for your upgrade.

You have no added administrative requirements and can skip to the Upgrade Procedures if you:

  • Have only one RStudio Server Pro/RStudio Workbench node (including integration with Kubernetes or Slurm via the Launcher)
  • Do not wish to configure VS Code as an IDE for RStudio Workbench
  • Are satisfied with RStudio Workbench's default locations for saving server state (true in most cases)
  • Do not wish to use RStudio Workbench's Project Sharing feature

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

Database#

Required, if load-balancing

Starting in RStudio Workbench version 1.4, a database is required. The product comes with an SQLite database out-of-the-box.

  • If you are running a single-node installation of RStudio Workbench; no further configuration is required.
  • If you are load-balancing multiple RStudio Workbench instances, a separate Postgres database is required.

Note

The minimum supported PostgreSQL version is 9.5.

Install Type Database
Single Node, RStudio Sessions Only SQLite
Single Node, Jupyter + VS Code Sessions (Launcher) SQLite
Single Node, External Resource Manager (K8S, Slurm) SQLite
Multiple Nodes Load Balanced/HA (w/ or w/o External Resource Manager) Postgres

RStudio Workbench uses the database to manage and maintain the server state.

  • If using a Postgres database, an administrator must create the database and properly configure RStudio Workbench; no further database administration is required.

Info

Understanding the RStudio Product Databases includes details on how RStudio professional products use their databases.

To update a load-balanced RStudio Workbench cluster to 1.4 or greater, you will need to:

  1. Stop all nodes in the cluster.
  2. Create the Postgres database.
  3. Edit the configuration files for all nodes to use the Postgres database.
  4. Install the new version of RStudio Workbench.
  5. Start the RStudio Workbench nodes.

Detailed instructions can be found in the RStudio Workbench Professional Edition - Admin guide.

VS Code#

Optional, IDE available

RStudio Workbench 1.4 allows users to launch VS Code sessions in addition to RStudio, JupyterLab, and Jupyter Notebook sessions. This configuration must be enabled by an administrator.

Enabling VS Code sessions is a two-step process:

  1. Install the VS Code executable.
  2. Configure RStudio Workbench to use the VS Code executable.

Additionally:

  • If RStudio Workbench is configured to run sessions locally, there is an installation utility provided by RStudio Workbench for a one-line install, including R and Python extensions.
  • If RStudio Workbench is configured to use an external resource manager like Kubernetes or Slurm, the VS Code executable must be installed into the relevant containers or Slurm nodes.
    • The r-session-complete container provided by RStudio already has the VS Code executable installed.

The procedures for installing and configuring VS Code in RStudio Workbench, please see the RStudio Workbench Professional Edition Admin Guide.

Default Data Directory#

New default, now optionally configurable

RStudio Workbench maintains state in the user’s home directory:

  • In versions of RStudio below 1.4, this state was maintained in the ~/.rstudio folder, with no ability to alter the location.
  • Starting in RStudio Workbench 1.4, this data now lives in the ~/.local/share/rstudio directory, and this location is configurable.

Note

We strongly recommend that the data in this folder be used by the IDE alone, and not manually accessed.

Directory Migration#
  • For most RStudio Workbench installations, the migration will be automatic and invisible to users and administrators.
  • In some configurations, RStudio Workbench administrators may wish to move this data somewhere else if space is limited on the drive with user home directories.
Configurable Paths#
  • If you wish to return the data to its prior location, or to move the data location somewhere else, the XDG_DATA_HOME or RSTUDIO_DATA_HOME environment variables in the service definition can be configured.

See the RStudio Workbench Professional Edition - Admin guide for more details on configuring this setting.

Project Sharing#

Optional, newly enabled in Launcher configurations

Prior to RStudio Workbench version 1.4, using the Launcher feature to enable an External Resource Manager and/or JupyterLab, Jupyter Notebook, and VS Code sessions required disabling the real-time project sharing feature of RStudio sessions.

This is no longer the case as of version 1.4. Please see the RStudio Workbench Professional Edition - Admin guide for details on enabling project sharing.

Administrative Tasks Conclusion

Now that you have reviewed and completed the required administrative tasks, you may continue to the next section, Upgrading to Version 2021.09.0+.

Upgrading to Version 2021.09.0+#

Prerequisites#

For RStudio Server Pro 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 Requirements for Upgrading to Version 1.4+ section above, before continuing with this section.

Upgrade RStudio Workbench to 2021.09.0+:

  • If your RStudio Server Pro or RStudio Workbench version is at 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.

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.

Upgrade RStudio Workbench to 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

Upgrade Procedures#

Caution

Review the Upgrade Paths section above 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.

We recommend taking the service completely offline prior to running the 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
    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 install the upgraded version using your package manager:

    sudo gdebi <rstudio-server-package.deb>
    
    or
    sudo yum install --nogpgcheck <rstudio-server-package.rpm>
    

    For older versions of RStudio, please review the Older Versions page.

  5. Restart the server: sudo rstudio-server restart

  6. 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 RStudio 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. We have renamed RStudio Server Pro to RStudio Workbench. This change reflects the product’s growing support for a wide range of different development environments. Please see our official Announcement and review our FAQ regarding the name change from RStudio Server Pro to RStudio Workbench. 

Back to top