Upgrading from RStudio Connect 1.7.2 and below


RStudio Connect 1.7.4 introduces a new upgrade process to help manage configuration settings. While the process is generic and will apply in future releases, this article outlines specific steps administrators should follow to upgrade from 1.7.2 to 1.7.4+.  It is not required to install 1.7.4 first, this will work for upgrading from 1.7.2 to 1.7.6 for example. If you are upgrading from an older version, please consult the intermediate release notes.


  1. Stop RStudio Connect
    # for Ubuntu 16/18; CentOS/REHL 7; SUSE 12
    sudo systemctl stop rstudio-connect

    # for CentOS/RHEL 6; Ubuntu 14
    sudo stop rstudio-connect
  2. Download and install the 1.7.4 version, follow the instructions here for your distribution. 

  3. After upgrading, you will see a new auto-generated configuration file*:
    • /etc/rstudio-connect/rstudio-connect-migration.gcfg: This is an auto-generated configuration file managed by RStudio Connect.
    • /etc/rstudio-connect/rstudio-connect.gcfg: This is the main, user-managed configuration file.

  4. The goal of this step is to transfer the settings in the auto-generated configuration file into the user-managed configuration file. To make this process easy, run the following command (after again stopping RStudio Connect):
    /opt/rstudio-connect/bin/rscadmin configure --append-migration
  5. Next, we want to modify the updated configuration file, /etc/rstudio-connect/rstudio-connect.gcfg, to remove any plain text passwords. In the configuration file, you'll want to look for the following settings (please see the important notes below for settings indicated with a *).
    • [LDAP].BindPassword*
    • [0Auth2].ClientSecret*
    • [Postgres].Password*
    • [Postgres].InstrumentationPassword*
    • [SMTP].Password

  6. For each setting identified in step 5, run the following command: 
    /opt/rstudio-connect/bin/rscadmin configure --encrypt-config-value
    > ... you'll see lots of output, then the tool will pause
    > ... type in the value for the configuration setting

    In the configuration file, replace the old plain-text value, "some-secret-password", with the output from the command above, "an-encrypted-version-of-the-password".

  7. Once complete, start the RStudio Connect service and verify that you can visit the Connect web interface:
    # for Ubuntu 16/18; CentOS/REHL 7; SUSE 12
    sudo systemctl start rstudio-connect

    # for CentOS/RHEL 6; Ubuntu 14
    sudo start rstudio-connect

*Important Notes:

  • Step 3: See the appendix for more information if your configuration file is located in a different directory.

  • Step 4-6: These steps can be completed at any time after the upgrade. RStudio Connect will continue to work prior to completing these steps, but you will be relying on the auto-generated configuration file. As an example, you could upgrade RStudio Connect, and then perform the config migration during a later period of scheduled maintenance. We do recommend consolidating all settings into the user-managed configuration file.

  • Step 5: Either [LDAP].BindPassword or [0Auth2].ClientSecret may not exist, and instead be replaced with [LDAP].BindPasswordFile or [0Auth2].ClientSecretFile. In these cases, follow the same instructions, but place the encrypted secret in the referenced file. 

  • Step 5: If your configuration file contains a password in either [Postgres].URL or [Postgres].InstrumentationURL, you should replace the password in those fields with the text: {$} and then create the field [Postgres].Password and [Postgres].InstrumentationPassword. Follow the remaining instructions to ensure those passwords are encrypted. 
    ; before all steps
    URL = postgres://admin:password@my.postgres.ip/connect

    ; after all steps
    URL = postgres://admin:{$}@my.postgres.ip/connect
    Password = an-encrypted-version-of-the-password


Why are we doing all of this? In order to send emails, administrators must configure RStudio Connect to use a sendmail or SMTP client. In prior versions of RStudio Connect, this configuration was done interactively. Starting in version 1.7.4, RStudio Connect removes this support in favor of managing email settings in the RStudio Connect configuration file. This change makes setup easier and more consistent and enables teams using tools like Chef or Puppet to provision Connect.

In addition, steps 5 and 6 improve upon the old RStudio Connect configuration file to meet industry best practices for storing credentials.