2 Getting Started

This chapter helps you install RStudio Connect on Ubuntu or Red Hat Enterprise Linux/CentOS Linux, learn to manage the server, and perform some initial configuration.

We built this checklist to guide you through that process.

  1. Install R - Ubuntu 2.1.1, Red Hat/CentOS 2.1.2
  2. Download RStudio Connect installer
  3. Install RStudio Connect - Ubuntu 2.1.1, Red Hat/CentOS 2.1.2
  4. Set Server.SenderEmail - 2.2.1
  5. Set Server.Address - 2.2.1
  6. Configure Authentication - 2.2.2, 8
  7. Restart RStudio Connect - 5.1
  8. Sign into RStudio Connect - 2.2.3
  9. Configure email sending - 2.2.4

2.1 Installation

This section explains how to install R using the public package repositories for your Ubuntu or Red Hat/CentOS server. Chapter 12 explains how to configure RStudio Connect to access multiple versions of R on the same server.

2.1.1 Ubuntu (12.04+)

Connect recommends an installation of R version 3.0 or higher. To install the latest version of R you should first add the CRAN repository to your system as described here:

http://cran.rstudio.com/bin/linux/ubuntu/README.html

You can then install R using the following command:

$ sudo apt-get install r-base

Note: If you do not add the CRAN Ubuntu repository as described above this command will install the version of R corresponding to your current system version. This version of R may be a year or two old. It is strongly recommended that you add the CRAN repositories so you can run the most up-to-date version of R.

RStudio Connect can be configured to use versions of R other than the default system R. Please see Section 12 for details.

You will use gdebi to install Connect and its dependencies. It is installed via the gdebi-core package.

$ sudo apt-get install gdebi-core

You should have been provided with a .deb installer for RStudio Connect. If you only have a link to this file, you can use wget to download the file to the current directory.

$ wget https://download-url/rstudio-connect-1.4.6-11.deb

Once the .deb file is available locally, run the following command to install RStudio Connect.

$ sudo gdebi rstudio-connect-1.4.6-11.deb

This will install Connect into /opt/rstudio-connect/, and create a new rstudio-connect user.

At this point you should have Connect installed on your server. You can now configure the server following the instructions in Section 2.2.1 However, we recommend that you consider installing some additional system dependencies that common R packages require. Without these system dependencies, your users may not be able to use the R packages they require on the server.

Recommended Packages

The following system dependencies are required by many common R packages and nearly all deployments will need to provide these. These package names may vary slightly between different versions of Ubuntu.

build-essential
libcurl4-gnutls-dev 
openjdk-7-* # may require also executing `R CMD javareconf`
libxml2-dev
libssl-dev
texlive-full # very large dependency, but needed to render PDF documents from R Markdown

Supplemental Packages

There are additional system dependencies that may be required for some R packages depending on the types of R packages your users are leveraging. You could consider providing these packages for your users now, or wait until they are requested.

An up-to-date resource to help understand the system dependencies of various R packages in Ubuntu is available at https://github.com/rstudio/shinyapps-package-dependencies.

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.1.2 Red Hat Enterprise Linux/CentOS Linux (6.0+)

Prerequisites

RStudio Connect recommends an installation of R version 3.0 or higher. Connect has several dependencies on packages (including R itself) found in the Extra Packages for Enterprise Linux (EPEL) repository. If you don’t already have this repository available you should 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.

After enabling EPEL you should then ensure that you have installed the version of R available from EPEL. You can do this using the following command:

$ sudo yum install R  

RStudio Connect can be configured to use versions of R other than the default system R. Please see Section 12 for details.

You can now begin the installation of RStudio Connect. You should have been provided with an RPM file which contains Connect and all of its dependencies (other than R). You can install this rpm file using yum. If you have only a link to the RPM file, you can use wget to download the file to the current directory. You can install this RPM file using yum.

$ sudo yum install --nogpgcheck rstudio-connect-1.4.6-11.rpm

This will install Connect into /opt/rstudio-connect/ and create a new rstudio-connect user.

At this point you should have Connect installed on your server. You can now configure the server following the instructions in Section 2.2.1 However, we recommend that you consider installing some additional system dependencies that common R packages require. Without these system dependencies, your users may not be able to use the R packages they require on the server.

Recommended Packages

The following system dependencies are required by many common R packages and nearly all deployments will need to provide these. These package names may vary slightly between different versions of Red Hat Enterprise Linux/CentOS Linux.

make
gcc
gcc-c++
libcurl-devel
libxml2-devel
java-1.7.0-openjdk-devel  # may require also executing `R CMD javareconf`
openssl-devel
texlive-*  # VERY large dependency, but needed to render PDF documents from R Markdown

2.2 Initial Configuration

RStudio Connect is installed and running, but probably needs a bit of customization for your organization. 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.2.1 Editing the Configuration File

RStudio Connect is controlled by the /etc/rstudio-connect/rstudio-connect.gcfg configuration file. You will edit this file to make server-wide configuration changes to the system. See the configuration appendix A for details about this file, its syntax, and the available settings.

We strongly recommend setting the SenderEmail and Address server properties. Both must be specified in the [Server] section of your configuration file.

The Server.SenderEmail property is the email address from which Connect sends emails. It is important that the sendmail or SMTP configuration RStudio Connect uses be willing and able to send email from this SenderEmail address. Otherwise, Connect will not be able to successfully send email. See Section 2.2.4 for more details about mail sending.

The Server.Address property is the public URL used to access the server. When accessible over a non-standard port, this URL must specify both hostname and port. If this isn’t configured, Connect will not be able to include links in emails that send users to the appropriate location on the server.

The standard HTTP port is 80; the standard HTTPS port is 443.

Whenever RStudio Connect is deployed behind a proxy, you must configure the Server.Address setting with the proxied location. RStudio Connect normally returns URLs that are in terms of its local address. The Server.Address property causes Connect to use an alternate base location when building URLs. Setting Server.Address to the location of your proxy will produce URLs in terms of your proxy address instead of the Connect local address.

Using RStudio Connect with a proxy is experimental. There are known issues with URL construction, especially in situations where the proxy is performing path rewriting. This limitation will be removed in upcoming releases.

Here is a sample configuration specifying both SenderEmail and Address.

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

Use the instructions in Section 5.1 to restart RStudio Connect after altering the rstudio-connect.gcfg configuration file.

2.2.2 Authentication

It is important that you specify the correct style of authentication for your organization. If you are using RStudio Connect on a trial basis, feel free to use the default password authentication. RStudio Connect also supports a number of external authentication integrations, which are detailed in Section 8.

You must establish the correct form of authentication before using RStudio Connect. Migrating from one style of authentication to another is NOT SUPPORTED.

2.2.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. Connect needs to send email for account confirmation messages (when using the default password auth provider) and when distributing content.

2.2.4 Email Sending

Visit the RStudio Connect dashboard and sign in as an administrator. Visit the Admin>Settings screen and configure mail sending for your organization.

RStudio Connect supports two options for sending mail:

  • 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.

Please contact your system administrator if you have questions about which of these options are appropriate.

Be sure to verify your settings by sending a test message!