Upgrade
These instructions describe the configuration requirements and how to upgrade Posit Workbench.
If you are running RStudio Server Pro versions prior to 1.4, then additional steps are required before continuing; the procedures below will not work for your environment.
Please copy the text below into an email to support@posit.co. We will route your email appropriately once it has been received.
This message is copy/pasted from the Posit Workbench Upgrade guide: docs.posit.co/ide/server-pro/upgrade/upgrade/.
I am a customer attempting to upgrade Posit Workbench from a version below 1.4.
Please forward this message to Solutions Engineering to schedule an architecture call to discuss my migration.
Requirements
Your environment must be running RStudio Server Pro or Posit Workbench version 1.4, or greater.
Before you begin
These upgrade procedures are not incremental, however, you must review each section to verify that you are not using any deprecated configurations.
Additionally:
- 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:
- Follow the procedures available in the Upgrading from Open Source to Workbench section.
Upgrade Behavior
If you upgrade Workbench and an existing version of the server is currently running, then the upgrade process also ensures 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.
When load balancing is configured upgrading multiple nodes may cause brief glitches if you upgrade each Workbench node one at a time. This is due to the possibility of two Workbench nodes with different versions trying to coordinate. If some downtime is acceptable, we recommend taking all nodes offline before upgrading.
Upgrading to Version 2022.02.0+
If you would like to upgrade to 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 is now 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 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.
For reference, make a backup copy of the existing
/etc/rstudio/vscode.conf
file.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.
Upgrading to Version 2023.03.1+
There are no additional requirements to upgrade to version 2023.03.1+. Continue to the Upgrade Procedures section below.
Upgrading to Version 2023.06.0+
There are no additional requirements to upgrade to version 2023.06.0+. Continue to the Upgrade Procedures section below.
Upgrading to Version 2023.06.1+
There are no additional requirements to upgrade to version 2023.06.1+. Continue to the Upgrade Procedures section below.
Upgrading to Version 2023.09.0+
Breaking Changes
Using an encrypted password in database.conf
for PostgreSQL has been deprecated in favor of SSL certificate authentication.
PostgreSQL Database Password
If your PostgreSQL database password in database.conf
is encrypted, you will either need to:
- Set an unencrypted password in
database.conf
(available for 2023.09.0+)- If using an unencrypted password, be sure to safeguard it by setting the file permissions for
database.conf
to600
.
- If using an unencrypted password, be sure to safeguard it by setting the file permissions for
- Configure your PostgreSQL to authenticate with SSL certificates (available for 2023.09.1+)
Workbench will fail to start until you do one of the above options. In Workbench 2023.09.1+, you will also receive a warning log about the encrypted password. For more information see Database Configuration.
Recommended Configuration Changes
There are also some optional recommended configuration changes for Workbench 2023.09+
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-clusters
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.
Upgrade Procedures
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.
Notify users ahead of time of the upgrade. You can use the admin notification feature.
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
Put the old version of the server into offline mode:
sudo rstudio-server offline
Download and upgrade Workbench:
$ curl -O https://download2.rstudio.org/server/rhel8/x86_64/rstudio-workbench-rhel-2023.09.1-x86_64.rpm
$ sudo yum install rstudio-workbench-rhel-2023.09.1-x86_64.rpm
$ curl -O https://download2.rstudio.org/server/centos7/x86_64/rstudio-workbench-rhel-2023.09.1-x86_64.rpm
$ sudo yum install rstudio-workbench-rhel-2023.09.1-x86_64.rpm
$ curl -O https://download2.rstudio.org/server/focal/amd64/rstudio-workbench-2023.09.1-amd64.deb
$ sudo apt-get install ./rstudio-workbench-2023.09.1-amd64.deb
$ curl -O https://download2.rstudio.org/server/jammy/amd64/rstudio-workbench-2023.09.1-amd64.deb
$ sudo apt-get install ./rstudio-workbench-2023.09.1-amd64.deb
$ curl -O https://download2.rstudio.org/server/opensuse15/x86_64/rstudio-workbench-2023.09.1-x86_64.rpm
$ sudo zypper install rstudio-workbench-2023.09.1-x86_64.rpm
For older versions of RStudio/Workbench, please review the Previous Versions page.
Restart the server:
sudo rstudio-server restart
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.