2 Getting Started

This chapter helps you install RStudio Connect, manage the server, and perform some initial configuration. We built this checklist to guide you through that process.

  1. Install R - 2.2
  2. Install RStudio Connect - 2.3
  3. Configure Server.Address - 2.4.1
  4. Configure Authentication - 2.4.2, 11
  5. Restart RStudio Connect - 5.1
  6. Sign into RStudio Connect - 2.4.3
  7. Configure email sending - 2.4.4
  8. (optional) Install TensorFlow Dependencies - 2.4.5
  9. (optional) Install Python - 17

2.1 Need Help?

RStudio is happy to provide support for anyone using the product.

To focus on building the best products, RStudio does not provide installation or professional services. If you require such assistance, please refer to our certified partners.

RStudio support is limited to our professional products. If your question is related to R, R code, or specific R packages, please visit https://community.rstudio.com.

If your question is related to RStudio Connect, you can open a support ticket by:

  1. Running the diagnostics script:

    /opt/rstudio-connect/scripts/run-diagnostics.sh
    Note: if you have not been able to download the software, skip this step.
  2. Email with:
  • Your name and company
  • What you are trying to do
  • What you have tried
  • Any errors you have received
  • The diagnostics file produced from step 1

Our Support Agreement contains important details about the support we provide.

2.2 Prerequisite: R

RStudio Connect requires an installation of R and supports version 3.1.0 and higher.

We recommend installing multiple versions of R. An environment with multiple versions of R helps you provide a stable, reproducible environment for your R developers.

Install R using the directions at https://docs.rstudio.com/resources/install-r/.

Ask your R developers what R versions they use. Install their exact versions on the RStudio Connect server. The latest patch release for each R version is usually fine – patch releases contain small bug fixes that do not normally alter how deployed R code runs.

Add new versions of R to your RStudio Connect environment as they are adopted by your R developers. Keep old versions of R; those versions will continue to be used by content already hosted by RStudio Connect.

User content is executed in an environment as close as possible to the development environment. RStudio Connect can better mirror your development environments when the version of R used during development is available on the RStudio Connect server. Chapter 16 explains how R installations are discovered and assigned to deployed content.

We do not recommend using the version of R made available by your Linux distribution.

When you use the version of R that ships with your Linux distribution, R is updated as distribution updates are installed. This change is highly disruptive to content hosted by RStudio Connect, as the R packages required by that content need to be reinstalled for the new version of R. Content is unavailable while package environments are reconstructed.

Chapter 16 further explains how to manage R installations and why in-place upgrades to R are not recommended.

2.3 Installation

There are two ways to install RStudio Connect onto your Linux system:

  • Guided installation (recommended)
  • Manual installation

We recommend guided installation. Follow the instructions in Section 2.3.1.

If guided installation is not appropriate in your environment, follow the manual installation instructions associated with your Linux distribution.

2.3.1 Guided Installation

These instructions describe how to install RStudio Connect using an installation script. The installation script works across all supported Linux distributions, validates the GPG key of the downloaded package, and includes support for offline use.

Note: RStudio Connect requires an R installation. Confirm at least one version of R is available in your environment before proceeding.

# Download the installation script using either "curl" or "wget".
curl -LO https://rstudio-connect.s3.amazonaws.com/rsc-installer.sh
wget https://rstudio-connect.s3.amazonaws.com/rsc-installer.sh

The installation script must be run by a privileged user or a user with sudo privileges.

# Run the installation script
bash ./rsc-installer.sh install

The installation script will interactively prompt for your approval as it downloads the RStudio Connect package, installs required dependencies, and installs RStudio Connect.

You can also perform offline installations and automated (non-interactive) installations with rsc-installer.sh. Use the help option to learn more about these capabilities.

# Print additional usage information.
bash ./rsc-installer.sh help

2.3.1.1 Package Dependencies

We recommend some additional system dependencies required by R packages. Without these dependencies, your users may not be able to deploy content into RStudio Connect.

2.3.2 Manual Installation: Red Hat / CentOS

These instructions describe how to install RStudio Connect onto a Red Hat/CentOS server.

Note: RStudio Connect requires an R installation. Confirm at least one version of R is available in your environment before proceeding.

RStudio Connect has several dependencies on packages found in the Extra Packages for Enterprise Linux (EPEL) repository. If you don’t already have this repository available, add it to your system using the instructions found here: https://fedoraproject.org/wiki/EPEL. On some distributions of Red Hat Enterprise Linux/CentOS Linux, the R package references dependencies that are not available by default. In this case, you may need to edit the /etc/yum.repos.d/redhat.repo file to enable the rhel-6-server-optional-rpms (by setting enabled = 1) before you can install the R package.

You should have an .rpm file containing RStudio Connect and all of its dependencies (other than R). If you do not have an installer, download it into the current directory with wget.

For Red Hat/CentOS 6 and 7

wget https://rstudio-connect.s3.amazonaws.com/rstudio-connect-1.8.0-9.el.x86_64.rpm
sudo yum install rstudio-connect-1.8.0-9.el.x86_64.rpm

For Red Hat/CentOS 8

wget https://rstudio-connect.s3.amazonaws.com/rstudio-connect-1.8.0-9.el8.x86_64.rpm
sudo yum install rstudio-connect-1.8.0-9.el8.x86_64.rpm

RStudio Connect is installed into /opt/rstudio-connect/ and creates an rstudio-connect user.

See Section 2.4.1 to start configuring your RStudio Connect server.

2.3.2.1 Package Validation

The RStudio Connect installer is signed with a key belonging to RStudio, Inc. If you wish to verify this signature, you can obtain the public key from our website; save it into a file (e.g. rstudio-code-signing.key). You can also obtain it from a GnuPG keyserver using the following command:

gpg --keyserver keys.gnupg.net --recv-keys 3F32EE77E331692F
gpg --armor --export 3F32EE77E331692F > rstudio-code-signing.key

Once you have obtained the key, you need to import it into the set of keys RPM uses to validate package signatures, after which you can validate the package signature using the rpm command:

For Red Hat/CentOS 6 and 7

rpm --import rstudio-code-signing.key
rpm -K rstudio-connect-1.8.0-9.el.x86_64.rpm

For Red Hat/CentOS 8

rpm --import rstudio-code-signing.key
rpm -K rstudio-connect-1.8.0-9.el8.x86_64.rpm

2.3.2.2 Package Dependencies

We recommend some additional Red Hat/CentOS system dependencies required by R packages. Without these dependencies, your users may not be able to deploy content into RStudio Connect.

2.3.3 Manual Installation: SLES (12 SP4, 15)

These instructions describe how to install RStudio Connect onto an SUSE Linux Enterprise server.

Note: RStudio Connect requires an R installation. Confirm at least one version of R is available in your environment before proceeding.

You should have an .rpm file containing RStudio Connect and all of its dependencies (other than R). If you do not have an installer, download it into the current directory with wget.

For SUSE 12:

wget https://rstudio-connect.s3.amazonaws.com/rstudio-connect-1.8.0-9.sles12.x86_64.rpm
sudo zypper install rstudio-connect-1.8.0-9.sles12.x86_64.rpm

For SUSE 15:

wget https://rstudio-connect.s3.amazonaws.com/rstudio-connect-1.8.0-9.sles15.x86_64.rpm
sudo zypper install rstudio-connect-1.8.0-9.sles15.x86_64.rpm

RStudio Connect is installed into /opt/rstudio-connect/ and creates an rstudio-connect user.

See Section 2.4.1 to start configuring your RStudio Connect server.

2.3.3.1 Package Validation

The RStudio Connect installer is signed with a key belonging to RStudio, Inc. If you wish to verify this signature, you can obtain the public key from our website; save it into a file (e.g. rstudio-code-signing.key). You can also obtain it from a GnuPG keyserver using the following command:

gpg --keyserver keys.gnupg.net --recv-keys 3F32EE77E331692F
gpg --armor --export 3F32EE77E331692F > rstudio-code-signing.key

Once you have obtained the key, you need to import it into the set of keys RPM uses to validate package signatures, after which you can validate the package signature using the rpm command:

rpm --import rstudio-code-signing.key
# Validate SLES 12 installer
rpm -K rstudio-connect-1.8.0-9.sles12.x86_64.rpm
# Validate SLES 15 installer
rpm -K rstudio-connect-1.8.0-9.sles15.x86_64.rpm

2.3.3.2 Package Dependencies

We recommend some additional SLES system dependencies required by R packages. Without these dependencies, your users may not be able to deploy content into RStudio Connect.

2.3.4 Manual Installation: Ubuntu

These instructions describe how to install RStudio Connect onto an Ubuntu server.

Note: RStudio Connect requires an R installation. Confirm at least one version of R is available in your environment before proceeding.

These instructions use gdebi to install Connect and its dependencies. You may need to install gdebi if it is not already available on your system. The gdebi installation tool is part of the gdebi-core package.

sudo apt-get install gdebi-core

You should have a .deb file containing RStudio Connect and all of its dependencies (other than R). If you do not have an installer, download it into the current directory with wget.

wget https://rstudio-connect.s3.amazonaws.com/rstudio-connect_1.8.0-9_amd64.deb
sudo gdebi rstudio-connect_1.8.0-9_amd64.deb

RStudio Connect is installed into /opt/rstudio-connect/ and creates an rstudio-connect user.

See Section 2.4.1 to start configuring your RStudio Connect server.

2.3.4.1 Package Validation

The RStudio Connect installer is signed with a key belonging to RStudio, Inc. If you wish to verify this signature, you can obtain the public key from our website. You can also obtain it from a GnuPG keyserver using the following command:

gpg --keyserver keys.gnupg.net --recv-keys 3F32EE77E331692F

Once you have obtained the key, you can validate the .deb file as follows:

dpkg-sig --verify rstudio-connect_1.8.0-9_amd64.deb

2.3.4.2 Package Dependencies

We recommend some additional Ubuntu system dependencies required by R packages. Without these dependencies, your users may not be able to deploy content into RStudio Connect.

2.3.4.2.2 Supplemental System Packages

Here are additional system dependencies used by R packages. Their necessity depends on the type of content your users create and the R packages they use. You could provide these packages now or wait until they are requested.

libgmp10-dev
libgsl0-dev
libnetcdf6
libnetcdf-dev
netcdf-bin
libdigest-hmac-perl
libgmp-dev
libgmp3-dev
libgl1-mesa-dev
libglu1-mesa-dev
libglpk-dev
tdsodbc
freetds-bin
freetds-common
freetds-dev
odbc-postgresql
libtiff-dev
libsndfile1
libsndfile1-dev
libtiff-dev
tk8.5
tk8.5-dev
tcl8.5
tcl8.5-dev
libgsl0-dev
libv8-dev

2.4 Initial Configuration

RStudio Connect is installed, but requires additional configuration before it is ready for use. This section will help you specify the public URL of your server, configure authentication, and validate that RStudio Connect is able to send email.

2.4.1 Editing the Configuration File

RStudio Connect is controlled primarily by the /etc/rstudio-connect/rstudio-connect.gcfg configuration file. You will edit this file to make server-wide configuration changes to the system. Learn about its file format and available options in the Configuration Appendix.

Let’s start by configuring the Server.Address server property.

The Server.Address property is the public URL used to access the server. This setting lets email include links pointing back to your server.

Whenever RStudio Connect is deployed behind a proxy, you must configure Server.Address with the proxied location and not the local hostname of the Connect server.

Server.Address must contain hostname and port when your installation uses a non-standard port. You do not need to include port for an https:// URL on the standard HTTPS port 443 or an http:// URL on the standard HTTP port 80.

Here is a sample configuration with Server.Address:

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
Address = https://rstudio-connect.company.com/

Here is a sample configuration with RStudio Connect using a non-standard port:

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
Address = http://rstudio-connect.company.com:3939/

This example has RStudio Connect available underneath a specific URL path. You may have this situation when Connect is accessed through a proxy.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
SenderEmail = rstudio-connect@company.com
Address = https://proxy.company.com/connect/

Important Note

Please use a publicly available URL (like the one you set in Server.Address) when connecting rsconnect or the RStudio IDE to your RStudio Connect server. If a non- public address (e.g., localhost) is used for publishing content, rsconnect will not be able to automatically open the published content in the user’s browser.

Restart RStudio Connect after altering the rstudio-connect.gcfg configuration file.

sudo systemctl restart rstudio-connect

Your platform may use alternate commands to restart RStudio Connect. Please see Section 5.1 for instructions specific to your operating system version.

2.4.2 Authentication

It is important that you specify the correct style of authentication for your organization. RStudio Connect includes a built-in authentication mechanism and supports a number of external authentication integrations, which are detailed in Section 11.

It’s strongly recommended that the definitive form of authentication be established before using a permanent RStudio Connect installation. Migrating from one style of authentication to another can be done but it is a challenging process that will cause some temporary disruption.

The means to migrate between authentication providers are described in the section 11.1.

2.4.3 Sign In!

Use a web browser to visit the RStudio Connect dashboard. This has a default location of http://your-connect-server:3939/. Click the “Sign In” link. If you are using an external authentication provider, specify your login credentials. If you are using password authentication, follow the “Create a new account” link and configure your account.

The first account will be marked as an RStudio Connect administrator. Please use this account to configure mail sending. These settings are necessary in order for Connect to be able to distribute reports and notify users of errors running their content. Connect also sends confirmation messages when using the default password auth provider.

2.4.4 Email Sending

Note: The email features in RStudio Connect are disabled unless email sending is properly configured. In this state notifications that would be sent via email will only be visible in the logs. Also, the built-in authentication will not be able to rely on emails for account confirmation or password reset. These operations will instead require an administrator to act as an intermediary.

RStudio Connect supports two options for sending emails:

  • Sendmail - The sendmail command is used to send messages locally on your server. This relies on a working sendmail configuration or some equivalent replacement.
  • SMTP - Mail is sent using an SMTP endpoint and supports SSL and authentication.

The setting Server.EmailProvider indicates how RStudio Connect sends email. Configure Server.EmailProvider with either sendmail or SMTP to choose sendmail or SMTP sending. With SMTP mail delivery, use the [SMTP] configuration section to specify your SMTP connection settings. Appendix A.4 describes the SMTP settings.

Please contact your systems administrator if you have questions about which of these options are appropriate and add the proper values to your configuration file.

The Server.SenderEmail property is the email address from which Connect sends emails. Your email configuration must accept email with this Server.SenderEmail address as sender.

Here is a sample configuration that uses sendmail and an rstudio-connect sending account.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
SenderEmail = rstudio-connect@company.com
EmailProvider = sendmail

This configuration uses SMTP. See Appendix A.4 for all the SMTP configuration options.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
SenderEmail = rstudio-connect@company.com
EmailProvider = SMTP

[SMTP]
Host = "smtp.company.com"
Port = 25
StartTLS = "always"

Restart RStudio Connect after adjusting your email configuration (see Section 5.1) then send yourself a test message.

Sign into the RStudio Connect dashboard as an administrator and visit the Admin>Mail Settings page. Use the “Send Test Email” button to send yourself a message. Once that message arrives, you know that RStudio Connect is ready to send email.

2.4.5 Install TensorFlow Dependencies (Optional)

The TensorFlow C library libtensorflow.so is required for TensorFlow Model API deployment support. The version of libtensorflow.so must match the version supported by RStudio Connect, currently 1.15.0.

If users are experiencing difficulty deploying TensorFlow Models to RStudio Connect, verify that the correct version of libtensorflow.so is installed.

Note: TensorFlow 2.0 is not supported by RStudio Connect, as the libtensorflow.so C library for that version has not been released.

To install the TensorFlow dependencies, first verify that your license supports TensorFlow Model API deployment. If you do not have a Standard or Enterprise license, please contact your Customer Success Representative or RStudio Sales () for information about upgrading your license.

Second, verify that your platform is supported by TensorFlow. TensorFlow requires libraries that are unavailable on CentOS 6, Red Hat Enterprise Linux 6, and SUSE Linux Enterprise Server 12. Accordingly, RStudio Connect does not provide support for running TensorFlow Model APIs on these platforms.

Next, determine what version of TensorFlow your users will be deploying their models with. RStudio Connect supports TensorFlow versions 1.15.0 and earlier. Later releases and development TensorFlow builds are not supported.

Finally, there are two options for installing the required libraries:

  • You could obtain a libtensorflow binary package. This binary package would not be optimized for your platform, but would provide a working runtime for TensorFlow Model APIs on connect. See 2.4.5.1
  • You could compile libtensorflow from source. This would allow you to make various compile-time optimizations for your hardware. See 2.4.5.2

2.4.5.1 TensorFlow Binary Packages

The guide Installing TensorFlow For C should contain a section reading “Download and extract the TensorFlow C library”. Follow the instructions up to that point, download and extract the binary, and then:

  • On Ubuntu, the libraries may need to be installed to /usr/lib rather than /usr/local/lib as specified in the instructions.
  • On RHEL/CentOS, the libraries need to be installed to /usr/lib64 rather than /usr/local/lib as specified in the instructions.
  • On ALL PLATFORMS: Ensure that both libtensorflow.so and libtensorflow_framework.so are in your shared library search path.

  • After installing the shared libraries, configure the linker with ldconfig:

    sudo ldconfig

RStudio Connect will detect your TensorFlow installation after a restart.

sudo systemctl restart rstudio-connect

Your platform may use alternate commands to restart RStudio Connect. Please see Section 5.1 for instructions specific to your operating system version.

2.4.5.2 Compiling TensorFlow Libraries From Source

NOTE: These instructions have been tested as of TensorFlow 1.13.1, please refer to the TensorFlow Project for up-to-date information on building TensorFlow Libraries.

NOTE: Compiling TensorFlow from source may be difficult and is highly dependent on your host environment. If you encounter issues compiling libtensorflow.so from source, you should raise an issue at the TensorFlow project’s Github Issues Page

  1. Install Bazel per the Bazel Installation Instructions
  2. Download the TensorFlow Source either using git clone or by downloading a source tarball.

  3. Check out version 1.13.1 with git.

    git checkout v1.13.1
  4. Python, Swig, and NumPy may be required on the build platform. - On Ubuntu, they can be installed with sudo apt-get install python swig python-numpy - On CentOS, they can be installed with sudo yum install python swig numpy
  5. Enter the source directory and run ./configure. Answer the questions about your hardware to the best of your knowledge. Application logs will contain a warning if the platform’s tensorflow libraries lack usable optimizations.
  6. Execute bazel build --config opt //tensorflow:libtensorflow.so. This will compile tensorflow for your platform
  7. Copy libtensorflow.so and libtensorflow_framework.so from bazel-bin/tensorflow into your platform’s shared library path

  8. After installing the shared libraries, configure the linker with ldconfig:

    sudo ldconfig

RStudio Connect will detect your TensorFlow installation after a restart.

sudo systemctl restart rstudio-connect

Your platform may use alternate commands to restart RStudio Connect. Please see Section 5.1 for instructions specific to your operating system version.

2.4.6 Integration with RStudio Package Manager (Optional)

RStudio Package Manager is a repository management server product that makes it easy to organize and centralize R packages at your organization. RStudio Package Manager may help if your organization needs offline CRAN access, package access restrictions, internal package sharing, or other special package management needs. To learn more, visit the RStudio Package Manager Product Page and contact your RStudio Customer Success Representative.

2.4.6.1 Overriding CRAN with RStudio Package Manager

You may wish to redefine CRAN or another R package repository to point to your organization’s RStudio Package Manager repository, or at some other private R package repository that you have set up.

When a user deploys R content, the content comes with a packrat.lock file, or a manifest.json file that is used to generate the packrat.lock file. This file contains the versions and cryptographic hashes of all the package dependencies for the content, as well as the URLs of the package repositories in the deploying user’s environment. CRAN is one such repository, and it is the most commonly used repository for R programming.

You should first obtain the repository link from RStudio Package Manager:

  1. Open RStudio Package Manager
  2. Select your repository in the Repos list on the left side of the screen
  3. Select Setup in the navigation bar at the top of the screen
  4. Under Repository URL, select whether you want the Latest checkpoint or select a date to Freeze the packages to a particular date. Important: freezing your repository to a date could lead to users attempting to deploy content containing package versions that did not exist at that date. If that happens, their content will fail to build because it cannot find necessary packages.
  5. If present on your version of RStudio Package Manager, select whether you want Source or Binary packages. Important: If you choose binary packages, you must select the distribution that matches the distribution of Linux you are using on RStudio Connect.
  6. Under Use this URL... link, copy the URL.

  7. In your configuration file, add the following setting, replacing <the URL you copied> with the URL that you copied in the previous step:

    [RPackageRepository "CRAN"]
URL = <the URL you copied>

  8. Important: You MUST force your packrat cache to rebuild every time you change this setting. You can accomplish this while the server is shut down by running the migrate utility: /opt/rstudio-connect/bin/migrate rebuild-packrat --force. Note that the location of the binary and the command line options you need to pass may vary depending on where your installation is located on the filesystem.

2.4.7 Integration with RStudio Cloud

RStudio Cloud is a product geared towards bringing R to everyone. A core feature of RStudio Cloud is the ability to create projects with as-needed instances of the standard RStudio IDE, including the ability to publish content to RStudio Connect. If your users are using RStudio Cloud to publish content to RStudio Connect, there are some caveats that you should be aware of:

  1. RStudio Cloud uses a package proxy replacement for CRAN, which shows up in the packrat.lock and manifest.json files as http://package-proxy
  2. RStudio Cloud supports a fallback repository for its packages which is listed as RSPM in the repos R option and points to a CRAN mirror.
  3. When deployments from RStudio Cloud rebuild on RStudio Connect, users may see a message saying that it couldn’t contact http://package-proxy before successfully building.

2.4.7.1 Suppressing The package-proxy Message

To prevent the package-proxy message from appearing in user deployments, override CRAN using the RPackageRepository configuration heading.

[RPackageRepository "CRAN"]
URL = https://cran.rstudio.com

2.4.7.2 Making All RStudio Cloud Deployments Restore From RSPM

Because RStudio Cloud uses two repository settings to achieve its fallback behavior, you will need to override both of them using the RPackageRepository configuration heading.

[RPackageRepository "CRAN"]
URL = https://my.package.manager.instance

[RPackageRepository "RSPM"]
URL = https://my.package.manager.instance

Replace https://my.package.manager.instance with the instance of RSPM you would like to prefer that packages restore from.