2 Getting Started

This chapter helps you install RStudio Connect on Ubuntu (Section 2.2.3) or Red Hat Enterprise Linux (Section 2.2.4)/CentOS Linux (Section 2.2.4)/ SUSE Linux Enterprise (Section 2.2.4), learn to manage the server (Section 5.1), and perform some initial configuration (Section 2.3).

We built this checklist to guide you through that process.

Install R - Ubuntu 2.2.3, Red Hat/CentOS/SUSE 2.2.4
Download RStudio Connect installer
Install RStudio Connect - Ubuntu 2.2.3, Red Hat/CentOS/SUSE 2.2.4,
Set Server.SenderEmail - 2.3.1
Set Server.Address - 2.3.1
Configure Authentication - 2.3.2, 10
Restart RStudio Connect - 5.1
Sign into RStudio Connect - 2.3.3
Configure email sending - 2.3.4
Install TensorFlow Dependencies (Optional) - 2.3.5
Install Python (Optional) - 16

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:

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.
Email support@rstudio.com 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 Installation

This section explains how to install R on an Ubuntu or Red Hat/CentOS/SUSE server. You must install R version 3.1.0 or higher.

Administrators should install the versions of R that they wish to support from source so that user content is run in an environment as close as possible to the development environment. This allows maintenance of multiple versions of R simultaneously and mitigates the risk associated with updating the version of R.

2.2.1 Package Managers

The best practice is to install R from source rather than with a package manager like apt, yum, or zypper. Installing R with a package manager means that R will be updated when the package manager update command is run and a new version is released. Any content that was uploaded and built with the old R version will need to be rebuilt for the new R version. This is not guaranteed to succeed.

2.2.2 Build R from Source

To build R from source, first, acquire the build dependencies for R.

In Ubuntu, you can install build dependencies with

apt-get build-dep r-base

Or determine and install dependencies independently by using the following command:

apt-rdepends --build-depends r-base

In RedHat Enterprise Linux and CentOS, you can install build dependencies with

yum-builddep R

Or determine and install dependencies independently by using the following command:

yum deplist R

In SUSE, build dependencies should be installed directly with zypper install <dependency>. A partial list of the libraries that you might need is below.

zypper install \
    gcc \
    gcc-c++ \
    gcc-fortran \
    readline-devel \
    xorg-x11-devel \
    liblzma5 \
    xz-devel \
    pcre-devel \
    libcurl-devel \
    make

Second, you should download and unpack the source tarball for the version of R that you want to install from CRAN. To install R-3.4.3, this might look like the following:

# Download and extract source code
wget https://cran.r-project.org/src/base/R-3/R-3.4.3.tar.gz
tar -xzvf R-3.4.3.tar.gz
cd R-3.4.3

The final step is to configure, make, and install R. The recommended install location in this case is at /opt/R/3.4.3. If you would like to choose a different location, you can change --prefix=. To learn more about how Connect looks for R installations, see section 15.3.1.

# Build R from source
./configure \
    --prefix=/opt/R/$(cat VERSION) \
    --enable-memory-profiling \
    --enable-R-shlib \
    --with-blas \
    --with-lapack

make
sudo make install

It is very important that the R installation folder is not moved once it is installed from source. Libraries are statically linked, so moving the folder will break the installation of R.

To test that the installation went smoothly, execute:

/opt/R/3.4.3/bin/R --version

Once you have R installed on the server, it is important to understand how Connect discovers R and chooses the R version that an asset will use. Chapter 15 explains more about this process.

2.2.3 Ubuntu (14.04+)

RStudio Connect requires an installation of R version 3.1.0 or higher. See section 2.2.2 for details on installing R from source.

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 a .deb installer for RStudio Connect. It can be downloaded from the RStudio website. 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.7.2-7_amd64.deb

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

sudo gdebi rstudio-connect_1.7.2-7_amd64.deb

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

You can now configure the server following the instructions in Section 2.3.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.

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.2.4 Red Hat Enterprise Linux/SUSE Linux Enterprise (12 SP3+)/CentOS Linux (6.0+)

Prerequisites

RStudio Connect requires an installation of R version 3.1.0 or higher. See section 2.2.2 for details on installing R from source.

For RedHat/CentOS, 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, 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 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/zypper. If you have only a link to the RPM file, you can use wget to download the file to the current directory.

wget https://download-url/rstudio-connect-1.7.2-7.x86_64.rpm

For RedHat/CentOS:

sudo yum install --nogpgcheck rstudio-connect-1.7.2-7.x86_64.rpm

For SUSE:

sudo zypper --no-gpg-checks install rstudio-connect-1.7.2-7.x86_64.rpm

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

Recommended Packages

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

Start by 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.3.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. This setting enables Connect 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.

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.

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.

Here is a sample configuration specifying both SenderEmail and Address.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
SenderEmail = rstudio-connect@company.com
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]
SenderEmail = rstudio-connect@company.com
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/

By default the version and build number for RStudio Connect is displayed within the dashboard. If you wish to hide this information you can do so by configuring the Server.HideVersion setting. When set to true the version and build will be hidden from users.

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.3.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 10.

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

2.3.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.3.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!

At this point, RStudio Connect is installed and ready for use. The rest of the administration guide covers additional configuration options.

2.3.5 Install TensorFlow Dependencies (Optional)

Note: libtensorflow.so is required for TensorFlow Model API deployment support, and an up-to-date libtensorflow.so is required to run TensorFlow Model APIs at the latest version. If users are experiencing difficulty deploying TensorFlow Models to RStudio Connect, try updating libtensorflow.so to the latest version following the instructions below.

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 RStudio Sales for information on 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.9.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.3.5.1
You could compile libtensorflow from source. This would allow you to make various compile-time optimizations for your hardware. See 2.3.5.2

2.3.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 CentOS7/RHEL7, 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.

2.3.5.2 Compiling TensorFlow Libraries From Source

NOTE: These instructions have been tested as of TensorFlow 1.7, 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

Install Bazel per the Bazel Installation Instructions
Download the TensorFlow Source either using git clone or by downloading a source tarball.
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
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.
Execute bazel build --config opt //tensorflow:libtensorflow.so. This will compile tensorflow for your platform
Copy libtensorflow.so and libtensorflow_framework.so from bazel-bin/tensorflow into your platform’s shared library path