Manual Installation#

Prerequisites#

  • Meet the Requirements for RStudio Connect
  • Install R on the server using the steps provided by RStudio

Step 1. Download and install#

  • Run the following to download and install RStudio Connect:

    $ curl -O https://cdn.rstudio.com/connect/1.8.4/rstudio-connect-1.8.4.1-20.el8.x86_64.rpm
    $ sudo yum install rstudio-connect-1.8.4.1-20.el8.x86_64.rpm
    
    $ curl -O https://cdn.rstudio.com/connect/1.8.4/rstudio-connect-1.8.4.1-20.el7.x86_64.rpm
    $ sudo yum install rstudio-connect-1.8.4.1-20.el7.x86_64.rpm
    
    $ curl -O https://cdn.rstudio.com/connect/1.8.4/rstudio-connect-1.8.4.1-20.el6.x86_64.rpm
    $ sudo yum install rstudio-connect-1.8.4.1-20.el6.x86_64.rpm
    
    $ sudo apt-get install gdebi-core
    $ curl -O https://cdn.rstudio.com/connect/1.8.4/rstudio-connect_1.8.4.1-20~ubuntu20_amd64.deb
    $ sudo gdebi rstudio-connect_1.8.4.1-20~ubuntu20_amd64.deb
    
    $ sudo apt-get install gdebi-core
    $ curl -O https://cdn.rstudio.com/connect/1.8.4/rstudio-connect_1.8.4.1-20~ubuntu18_amd64.deb
    $ sudo gdebi rstudio-connect_1.8.4.1-20~ubuntu18_amd64.deb
    
    $ sudo apt-get install gdebi-core
    $ curl -O https://cdn.rstudio.com/connect/1.8.4/rstudio-connect_1.8.4.1-20~ubuntu16_amd64.deb
    $ sudo gdebi rstudio-connect_1.8.4.1-20~ubuntu16_amd64.deb
    
    $ curl -O https://cdn.rstudio.com/connect/1.8.4/rstudio-connect-1.8.4.1-20.sles15.x86_64.rpm
    $ sudo zypper install rstudio-connect-1.8.4.1-20.sles15.x86_64.rpm
    
    $ curl -O https://cdn.rstudio.com/connect/1.8.4/rstudio-connect-1.8.4.1-20.sles12.x86_64.rpm
    $ sudo zypper install rstudio-connect-1.8.4.1-20.sles12.x86_64.rpm
    
  • Verify the installation by ensuring that the service is running:

    Terminal
    $ sudo systemctl status rstudio-connect
    

Step 2. Verify and activate your license#

  • Verify the status of your license and that your evaluation license is active by running the following command:

    Terminal
    $ sudo /opt/rstudio-connect/bin/license-manager status
    

    • If you already have a license key, then follow the License activation procedures:

      License activation procedures

      There are several options for activating your license:

      Online activation

      If your server is in an online environment and you already have the license key, then activate the license using the following command (the <LICENSE-KEY> is the license key that was provided to you):

      Terminal
      $ sudo /opt/rstudio-connect/bin/license-manager activate <LICENSE-KEY>
      

      For additional information about online activation, refer to the Product Activation section of the Admin Guide.


      Offline activation

      If you are working in an offline environment, then refer to the License Server Offline Activation section of the Admin Guide.


      Floating license

      If your server is up and running and you need to configure RStudio Connect to use a floating license, then the Using Floating Licensing section of the Admin Guide provides additional information.


Step 3. Initial configuration#

It is important to configure the following before logging into RStudio Connect for the first time:

Server email address and server address

Property Description
Server.SenderEmail The email address from which RStudio Connect sends emails.
Sever.Address The server address/public URL of your server.
Server.EmailProvider Determines how RStudio Connect sends emails.
SMTP Sends email using an STMP endpoint.

Caution

If you don't properly configure the Server.Address, then you will not be able to add a user to the server because the account confirmation link requires the Server.Address to be configured. Additionally, some other RStudio Connect features will not be available without this property defined.

  • Make changes in the /etc/rstudio-connect/rstudio-connect.gcfg file using the examples below:
    [Server]
    SenderEmail = account@company.com
    
    [Server]
    Address = https://rstudio-connect.company.com
    
    [Server]
    Email.Provider = STMP
    
    [SMTP]
    Host = 
    Port = 
    SSL = 
    User = 
    Password = 
    

By default, RStudio Connect's email functionality is disabled until it is properly configured. We strongly recommend configuring it now so all of RStudio Connect's features are available right away.

  • Save your changes and restart RStudio Connect:

    Terminal
    sudo system restart rstudio-connect
    

    Note

    Although most newer distributions use systemd, Red Hat/CentOS 6 use Upstart. The documentation for restarting RStudio Connect for distributions using Upstart is available here.

For more information about configuring these properties, see the Editing the Configuration File in the Admin Guide.


Authentication

RStudio Connect can be configured with the following authentication methods by customizing the Authentication.Provider property.

RStudio Connect Authentication Properties:

Failure to configure authentication before logging in for the first time may cause serious problems for you in the future. Although it is possible to change the authentication method at a later date, it is cumbersome and may result in a loss of user content subscriptions, and other assets. However, if you plan on using RStudio Connect on a trial basis using Password authentication, you are now able to log into RStudio Connect.

Note

By default, RStudio Connect is set to use Password authentication as the provider, unless you configure an alternate method.

Password Configuration

Password (default)

The default authentication provider used by RStudio Connect. Password authentication uses a local user account backed by the RStudio Connect database and it is not integrated with a third-party service. The Password section of the Admin Guide provides a full description.

  • Navigate to the /etc/rstudio-connect/rstudio-connect.gcfg file.
  • Locate the Authentication.Provider setting.

    Note

    If this is the initial installation of RStudio Connect, then Password authentication is the default method, even if the Provider setting is left blank.

  • Even though Password authentication is the default method, locate the Authentication.Provider setting and for the Provider, type:

    [Authentication]
    Provider = password
    
  • Save your changes and restart RStudio Connect:

    Terminal
    $ sudo systemctl restart rstudio-connect
    

LDAP & Active Directory Configuration

LDAP/AD

Integrates with your company’s LDAP or AD infrastructure. User authentication and user search requests will be directed to the LDAP/AD server.

  • Navigate to the /etc/rstudio-connect/rstudio-connect.gcfg file.
  • Locate the Authentication.Provider setting and for the Provider, type "LDAP":

    [Authentication]
    Provider = LDAP
    
  • Now define an LDAP or AD section in the configuration file by adding a header that is case-sensitive, such as:

    [LDAP "European LDAP Server"]
    

Support for LDAP and AD has the following constraints:

Constraint Description
LDAP/AD user objects User objects must contain a user’s first name, last name, email address, and username.
Changes to a user When changes are made to a user's name, email address, or username that are in your LDAP/AD system, the changes do not automatically propagate to RStudio Connect. However, the user information updates the next time that the user logs into RStudio Connect after the LDAP/AD update is made.
Single bind When using single bind, the DN of a user must contain their username (i.e., it must utilize the UsernameAttribute). Using a different attribute for username, such as CN only to match the DN, may cause users to have to type their full name to log in. For example, it is not supported if the DN for a user is cn=SueJacobs, ou=People, dc=company, dc=com but their actual username is stored in the uid or SAMAccountName LDAP attribute. You must use double bind when the DN does not contain the username. If the DN doesn't contain a username, then use double bind.
Single-bind searches When using single-bind configuration, the searches only include users who have previously logged in to RStudio Connect.
Single-bind groups When using single-bind configuration, groups are not available.

Several configurations are discussed above, however:

  • If you would like to view all of the configurable options available, refer to the LDAP and Active Directory section of the Admin Guide.
  • If you would like to view additional configuration examples, refer to the Complete Configuration Examples section in the appendix of the Admin Guide.

After you've applied the configuration options that are relevant to your needs: save your changes and restart RStudio Connect:

Terminal
$ sudo systemctl restart rstudio-connect

SAML Configuration

SAML

Security Assertion Markup Language (SAML) protocol is an industry-standard for single sign-on, multi-factor authentication, and authorization within the enterprise. RStudio Connect supports SAML 2.0 for authentication and group membership. The Appendix - SAML section of the Admin Guide provides additional information.

Before you configure SAML authentication, you must know which SAML identity provider that you intend to use. RStudio Connect is the service provider (SP) for this SAML identity provider (IdP). SAML requires that RStudio Connect version 1.7.6, or later, is installed. The following IdPs provide integrated templates to simplify configuration. Additionally, certain providers may require that you add the integration to your account before the guide is available.

IdP Links to the IdP's custom configuration guides
Azure Active Directory (AD) https://azuremarketplace.microsoft.com/en-us/marketplace/apps/aad.rstudioconnect?tab=Overview
Okta https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-RStudio-Connect.html
OneLogin https://www.onelogin.com/product/app-catalog

For all other IdPs, or to proceed with custom configuration, do the following:

a. Determine your RStudio Connect Server.Address where users log in to RStudio Connect, for example, https://example.com.

b. Configure an SP for RStudio Connect within your SAML IdP. Modify our example values to fit your environment.

  • The RStudio Connect's "Entity ID" or unique URL is directly related to your server address from step a.
  • Additionally, this is the two underscores before and after the word "login".
    For example: https://example.com/__login__/saml.

Note the following:

  • The Assertion Consumer Response URL for RStudio Connect is directly related to your server address. For example, https://example.com/__login__/saml/acs.
  • The URL to log in to RStudio Connect used to create SP-initiated logins is your server address. For example, https://example.com.
  • SAML creates an Assertion when users log in to the system. Some IdPs require that you configure the assertion attributes for the SP. By default, RStudio Connect uses the following attributes, which are case sensitive, and can be configured and changed, if desired:
  • Username
  • FirstName
  • LastName
  • Email

If your IdP can pass groups in an Assertion Attribute, then those groups can be defined within RStudio Connect. By default, this attribute is named “Groups.” You can either configure:

  • A multi-valued Assertion Attribute.
  • A single-valued Assertion Attribute, where multiple group memberships are text-delimited (e.g. group1|group2|group3).

The IdP Metadata provided by your Identity Provider is required. Oftentimes, this is just an HTTPS URL that the XML metadata can be fetched from. Otherwise, the XML file can be downloaded and moved to the RStudio Connect server.

c. Do the following to configure RStudio Connect by using the values that are shown above.

  • Navigate to the /etc/rstudio-connect/rstudio-connect.gcfg file.
  • Ensure that the server address is set within the [Server] configuration block, for example:

    [Server]
    Address = https://<serveraddress>.com
    

  • Locate the Authentication.Provider setting and for the Provider and type "saml":

    [Authentication]
    Provider = saml
    

For more information about the available options, refer to the SAML section in the Admin Guide.

SAML Configuration Example

To see an example of the SAML configuration section that uses the values configured in this section, refer to the Getting Started with SAML in RStudio Connect article's step 3.a to the RStudio support site.

d. Save your changes and restart RStudio Connect:

Terminal
$ sudo systemctl restart rstudio-connect

For the full description of configuring SAML authentication, see the SAML section in the Admin Guide.

PAM Configuration

PAM

Pluggable Authentication Module (PAM) provides dynamic authentication support for applications and services in a Linux System.

  • Navigate to the /etc/rstudio-connect/rstudio-connect.gcfg file.
  • Locate the Authentication.Provider setting and for the provider, type "pam":
[Authentication]
Provider = pam
  • Optionally, you can change the PAM service name that's used for authentication by customizing the PAM.Service setting. By default, the default PAM service name used for RStudio Connect is rstudio-connect. For example:

    ; /etc/rstudio-connect/rstudio-connect.gcfg
    [PAM]
    Service = rstudio-connect
    
Ubuntu systems

RStudio Connect does not create a PAM service on Ubuntu systems and attempts to use the rstudio-connect service name for authentication. PAM will recognize that there is no service with that name and fall back to the default other service located at /etc/pam.d/other. If the other service is not appropriate for your organization, see the Ubuntu documentation.

Red Hat/CentOS/SUSE systems

Additionally, Red Hat/CentOS/SUSE systems may deny access to unknown PAM service names by default because of the other configuration in /etc/pam.d/other contains only “deny” rules. If you are running a Red Hat/CentOS/SUSE system and require PAM to be configured, refer to the Red Hat/CentOS/SUSE documentation.

  • Refer to the PAM section of the admin guide if your organization requires:

    • Different requirements from the default behavior or
    • Groups to be configured and managed
  • Save your changes and restart RStudio Connect:

    Terminal
    $ sudo systemctl restart rstudio-connect
    

For the full description of configuring OAuth2 authentication, see the PAM documentation.

OAuth2 (OpenID Connect) Configuration

OAuth2 (OpenID Connect)

OpenID Connect is an authentication scheme based on OAuth2 and may be used to authenticate against various vendors such as Google, Microsoft (Azure), Okta, OneLogin, Auth0, PingIdentity, and many others that implement this standard. Additionally, OAuth2 requires that you have a client ID and client secret.

Note

By default, RStudio Connect comes pre-configured to use Google as the identity provider for OpenID Connect. For backwards compatibility, Google is the default configuration, so no action is necessary for existing installations.

  • Navigate to the /etc/rstudio-connect/rstudio-connect.gcfg file.
  • Locate the Authentication.Provider setting and for the Provider, type "oauth2":

    [Authentication]
    Provider = oauth2
    
To use a provider other than Google:
  • An OpenID Connect issuer must be defined on OAuth2.OpenIDConnectIssuer
  • The issuer must be an HTTPS URL and the location of the /.well-known/openid-configuration discovery metadata for OpenID Connect.
  • The HTTPS certificate associated with the issuer URL must be valid and associated with a valid certificate authority (self-signed certificates are not accepted).
Troubleshooting OAuth2 related issues

When attempting to trouble OAuth2 related issues, you can enable more verbose logging with OAuth2.Logging.

[OAuth2]
Logging = true
  • Obtain a client ID and client secret:

    Obtain a client ID and client secret using Google as your vendor

    You must obtain a client ID and client secret to add to the rstudio-connect.gcfg file to enable OAuth2 authentication. This example assumes that you are using Google as your vendor.

    • Navigate to the Google Developers Console.
    • Do the following:
      • Create a new project.
      • From the Google APIs dashboard, ensure that your new project is selected.
      • Click + ENABLE APIS AND SERVICES.
      • Search and enable Enable Google+ API.
      • From the Navigation menu, select APIs & Services and click OAuth consent screen.
      • Create the appropriate User Type.
        It is important that you populate the Authorized domains field because this URL is used as your Authorized redirect URIs path in a later step.
      • Fill out and save any necessary fields in the OAuth consent screen.
        Ensure that you populate the Authorized domains field because it is required in a later step.
      • Create an OAuth client ID.
      • For the Application type, select Web application and use the following configurations in the corresponding fields:
        • Name: Give your client ID a descriptive name.
        • Authorized JavaScript origins: Enter your RStudio Server URL (e.g. https://HOST:PORT)
        • Authorized redirect URIs: Enter your RStudio Connect server address with "/login/callback" (e.g., https://HOST:PORT/login/callback). This field should be populated with the same domain that was entered for your Authorized domains that was configured in a previous step.
      • Save your changes.
      • Navigate to the /etc/rstudio-connect/rstudio-connect.gcfg file.
      • Add the client ID and client secret to the file. For example:
        [OAuth2]
        DiscoveryEndpoint = https://accounts.google.com/.well-known/openid-configuration
        ClientId = <CLIENT ID>
        ClientSecret = <CLIENT SECRET>
        
  • After adding the client ID and client secret to the file, save your changes, and restart RStudio Connect:

    Terminal
    $ sudo systemctl restart rstudio-connect
    

Now, you may use your Google Apps account to sign into RStudio Connect.

For the full description of configuring OAuth2 authentication, see the OAuth2 (Google) documentation.

Proxied Auth Configuration

Proxied

Proxied authentication allows an external system to intercept requests and handle the authentication of:

  • Users visiting the RStudio Connect dashboard or
  • Applications that RStudio Connect is hosting

Proxied authentication is only used in rare cases when you are not able to use one of the other authentication methods that RStudio Connect supports.

If you fall into this unique category and require Proxied authentication, the Proxied Authentication section in the Admin Guide has a full description for configuring Proxied authentication, including additional headers that can be configured.

The RStudio Connect Admin Guide provides detailed explanations and additional information about configuring authentication in RStudio Connect.

Step 4. Log in and verify configuration#

Administrative privileges

By default, the first user to log into RStudio Connect is assigned administrative privileges. Additionally, other users can be promoted to administrators after the configuration is complete.

  • Log in:

    • Open a web browser and navigate to the public URL that you defined for your RStudio Connect server. The default location is: http://your-connect-server-address:3939/ page displays.
    • Click Sign Up.
    • Populate the fields with the information that is required to create an account and click Sign Up. You log into RStudio Connect and the Jump Start Examples window displays.
    • Close the Jump Start Examples window.

      Jump Start Example window

      The Jump Start Example window displays each time a user logs into RStudio Connect. However, if you close the window but decide that you want to launch one of the Jump Start Examples, then:

      • From the upper right-hand corner click the Publish drop-down button.
      • Select Jump Start Examples. The Jump Start Examples window displays.
  • Verify email:

    • From the Menu bar, click Admin.
    • Click Mail Settings.
    • Click Send Test Email.
    • Wait a few moments and then verify that the test email was successfully delivered.
  • Verify configuration:

    • To verify the initial configuration that you applied during the installation, we recommend that you do one of the following:
      • Have an RStudio user log into RStudio Connect and publish one of the Jump Start Examples that display when they log into RStudio Connect.
      • Publish content to RStudio Connect using one of the Publish to RStudio Connect How To Guides.
    • If a user can publish content to RStudio Connect, then you successfully configured RStudio Connect.

      Info

      Some of the Jump Start Examples require that you have Python installed on the server for you to publish the example. Now would be a good time to verify with your user as to whether Python is a requirement and if you need to integrate RStudio Connect with Python.

Step 5. Start using RStudio Connect#

Congratulations! You have verified that users can log in, deploy content, and view content on the server.

There are several additional features and configuration options that you may wish to enable.

Continue to the next section of the documentation or view the Admin Guide, or both, for more information.