5 Server Management

This section describes common administrative tasks for RStudio Connect.

5.1 Stopping and Starting

Occasionally it is necessary to start and stop the RStudio Connect service. Stopping and starting is handled by systemd or Upstart. On stop/start or restart the following occurs:

Stop:

  • The RStudio Connect process is stopped.
  • Processes serving applications and APIs are stopped.
  • Processes rendering documents run through completion.
  • In-progress deployments will fail. Processes running as part of the deployment may run to completion.

Start:

  • RStudio Connect process is resumed.
  • Applications and APIs with a minimum number of processes are started.
  • Scheduled document render updates missed during system downtime are run at most once.

The specific stop/start commands depend on the service dameon. Commands for systemd and Upstart are listed below.

5.1.1 systemd

Distributions using systemd include Red Hat/CentOS 7, SUSE 12, Ubuntu 16.04, and Ubuntu 18.04.

systemd is a management and configuration platform for Linux. The newest versions of most major Linux distributions have adopted systemd as their default init system.

The RStudio Connect installer installs a systemd service called rstudio-connect, which causes the connect program to be started and stopped automatically when the machine boots up and shuts down. The rstudio-connect service is also automatically launched during installation.

Use the following commands to manually start and stop the server:

sudo systemctl start rstudio-connect
sudo systemctl stop rstudio-connect

You can restart the server with:

sudo systemctl restart rstudio-connect

You can trigger a configuration reload with the systemctl reload command, which reads the changed configuration from disk:

sudo systemctl reload rstudio-connect

This causes the server to re-initialize but does not interrupt the current processes or any of the open connections to the server.

Use systemctl reload to send a HUP signal when your configuration changes are limited to properties marked as “reloadable”. See Appendix A to learn which settings may be reloaded. Perform a full restart of RStudio Connect when changing other properties.

You can check the status of the rstudio-connect service using:

sudo systemctl status rstudio-connect

And finally, you can use the enable/disable commands to control whether Connect should be run automatically at boot time:

sudo systemctl enable rstudio-connect
sudo systemctl disable rstudio-connect

5.1.2 Upstart (Ubuntu 14.04, Red Hat 6)

Distributions using Upstart include Red Hat/CentOS 6 and Ubuntu 14.04.

Upstart is a system used to automatically start, stop and manage services. The installer writes an Upstart configuration file to /etc/init/rstudio-connect.conf. This instructs the Upstart to initialize RStudio Connect as soon as the network is activated on the machine and stop when the machine is being shut down.

The Upstart configuration also ensures that the connect process is respawned if the process unexpectedly terminates. However, in the event that there is an issue which consistently prevents RStudio Connect from being able to start (such as a bad configuration file), Upstart will give up on restarting the service after approximately 5 failed attempts within a few seconds. For this reason, you may see multiple repetitions of a bad RStudio Connect startup attempt before it transitions to the “stopped” state.

To start or stop the server, run the following commands, respectively.

sudo start rstudio-connect
sudo stop rstudio-connect

To restart the server you can run:

sudo stop rstudio-connect
sudo start rstudio-connect

The restart command re-initializes the server.

We recommend stop and start over restart because some configuration changes are not incorporated into a restart. In particular, restart does not re-read the Upstart definition at/etc/init/rstudio-connect.conf. Changes to this file need astopandstart` to take effect.

You can trigger a configuration reload with the reload command, which reads the changed configuration from disk:

sudo reload rstudio-connect

This causes the server to re-initialize but does not interrupt the current processes or any of the open connections to the server.

Use reload to send a HUP signal when your configuration changes are limited to properties marked as “reloadable”. See Appendix A to learn which settings may be reloaded. Perform a full restart of RStudio Connect when changing other properties.

To check the status or retrieve the process ID associated with rstudio-connect, run the following:

sudo status rstudio-connect

5.2 System Messages

Administrators can add a message to the RStudio Connect welcome page and content page.

The Server.PublicWarning setting defines the message for the welcome page. Server.LoggedInWarning defines the message for the content page. The messages are supplied as HTML snippets. For example:

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
PublicWarning = "<strong>Warning:</strong> Scheduled downtime this weekend."
LoggedInWarning = "Data Science Team Meeting Tomorrow"

Messages can be added or modified without restarting the connect service. After adding the message property to the config file, use the reload commands for systemd (Red Hat/CentOS 7, SUSE 12, Ubuntu 16.04, and Ubuntu 18.04):

sudo systemctl reload rstudio-connect

or Upstart (Ubuntu 14.04, Red Hat 6):

sudo reload rstudio-connect

5.3 Health-Check

RStudio Connect provides a simple health-check endpoint that can be used to test if Connect is up/listening. Point your browser to myserveraddress:myserverport/__ping__, which returns an empty JSON response and an HTTP 200 status.

curl -I -X GET http://myserveraddress:myserverport/__ping__

5.4 Upgrading

Upgrading RStudio Connect requires limited downtime. Scheduled document renders are not interrupted. Connections to running applications and APIs are closed. We recommend upgrading during a period of downtime. Users can be warned ahead of an upgrade with system messages.

The RStudio Connect version number is visible on the lefthand navigation pane. The latest version is available on the download page along with release notes.

To upgrade:

  1. Download the latest .rpm or .deb file

  2. Run the install command:

    Ubuntu: bash sudo gdebi <rstudio-connect-version.deb>

    Red Hat/CentOS: bash sudo yum install --nogpgcheck <rstudio-connect-version.rpm>

    SUSE: bash sudo zypper --no-gpg-checks install <rstudio-connect-version.rpm>

The new version of RStudio Connect will install on top of an earlier installation. Existing configuration settings are respected. During installation the RStudio Connect service is restarted. Total downtime is less than 10 minutes.

5.5 Purging RStudio Connect

You can fully remove RStudio Connect and all its data from your server using the following steps:

  1. Stop the RStudio Connect service. (See 5.1 for details)

  2. Uninstall the RStudio Connect package from your system.

    Ubuntu:

    sudo apt-get purge rstudio-connect

    Red Hat/CentOS:

    sudo yum remove rstudio-connect

    SUSE:

    sudo zypper remove rstudio-connect
  3. Remove logs from /var/log/rstudio-connect*
  4. Purge the database
    • When using SQLite, remove the SQLite.Dir directory. This has a default location of /var/lib/rstudio-connect/db.
    • When using PostgreSQL, drop the database used by Connect. You may also wish to remove the PostgreSQL user associated with Connect.
  5. Remove the Server.DataDir directory. By default, this is /var/lib/rstudio-connect.

  6. Remove configuration files from /etc/rstudio-connect if they still exist.

5.6 Docker

Some organizations are starting to deploy RStudio Connect within a Docker container. Connect will manage and run your processes within that container. This section describes the requirements for a container-based deployment.

If you are using multiple Docker containers to run RStudio Connect, Section 6 contains requirements for a load-balanced, multi-host configuration.

Please contact the RStudio Solutions Engineering team (sol-eng@rstudio.com) for guidance deploying RStudio Connect into your particular environment.

5.6.1 Distributions

RStudio Connect is supported on the Linux distributions given in Section 1.1. Docker-based deployments need to use one of these operating systems.

5.6.2 R

R version 3.1.0 or higher must be installed within your Docker container. We recommend installing a curated set of R versions from source rather than using R installed by a package manager. The instructions in Section 2.2.2 contain the commands you will use to install R when building a Docker image.

5.6.3 Privileged containers

RStudio Connect runs processes within an “unshare” environment using bind mounts as described in Section 13.1. These bind mounts help Connect hide and isolate parts of the filesystem from executed user processes. Bind mounts are not permitted when running within an unprivileged container.

Docker containers are allowed mount permissions with the SYS_ADMIN capability. You can give these permissions to your container using either the --cap-add=SYS_ADMIN or --privileged=true option.

Learn more about Linux capabilities and CAP_SYS_ADMIN in the capabilities man page.

The Docker container running RStudio Connect must be started with either --cap-add=SYS_ADMIN or --privileged=true.

5.6.4 Licensing

We recommend using a floating license server and having RStudio Connect use that license server. Section 3.7) explains how to obtain and configure the license server as associating RStudio Connect with the floating license server.

We recommend using docker stop rather than docker kill to terminate your RStudio Connect Docker containers. Using docker stop allows floating license leases to be gracefully released. License leases not returned to the license server need to wait for lease expiration before they can be reused.

Please contact the RStudio Solutions Engineering team (sol-eng@rstudio.com) if your organization is unable to run a persistent floating license server.

5.6.5 Storage

Mount a persistent storage location into the Docker container and configure that location as your Server.DataDir. Do not mount this to the default /var/lib/rstudio-connect location. See Section 4.6 for more information on the variable data managed by RStudio Connect.

5.6.6 Database

The default SQLite database provider may be used when RStudio Connect runs inside a single Docker container and your Server.DataDir is a mounted volume that is NOT part of a networked (NFS) share.

You must use PostgreSQL in all multiple-container deployments or if your persistent storage location is a networked location.

5.6.7 Examples

This section contains an rstudio-connect.gcfg configuration file and Dockerfile that will help get you started building your own environment.

With the Dockerfile and rstudio-connect.gcfg files in a directory, you can build a Docker image tagged with rstudio/connect-docker:latest with the command:

docker build -t rstudio/connect-docker .

Once the image is built, it can be run with the command:

docker run -d --privileged=true --rm \
    -p :9999:3939 \
    -v $(pwd)/data:/data \
    rstudio/connect-docker:latest

This launches RStudio Connect within a Docker container. The Connect instance is available on port :9999 (published from :3939 within the container). This sample mounts the ./data directory as our persistent storage and will need updating for your environment.

5.6.7.1 Configuration

This rstudio-connect.gcfg file is copied into the Docker image by a COPY command in the Dockerfile that follows. This file is only an initial configuration and will need customization for your organization.

; /etc/rstudio-connect/rstudio-connect.gcfg

; RStudio Connect sample configuration
[Server]
; SenderEmail is an email address used by RStudio Connect to send outbound
; email. The system will not be able to send administrative email until this
; setting is configured.
SenderEmail = account@company.com

; The public URL to this RStudio Connect container. This might the address for
; a proxy or the host running the Docker container.
Address = https://rstudio-connect.company.com

; The persistent data directory mounted into our container.
DataDir = /data

[Licensing]
LicenseType = remote

; Use and configure our PostgreSQL database.
[Database]
Provider = postgres

[Postgres]
URL = "postgres://username:password@db.company.com/connect"

[HTTP]
; RStudio Connect will listen on this network address for HTTP connections.
Listen = :3939

[Authentication]
; Specifies the type of user authentication.
Provider = password

5.6.7.2 Dockerfile

Here is a very simple Dockerfile that can be used to run RStudio Connect within a Docker container. This simple example uses apt-get to install r-base from the Ubuntu 18.04 (bionic) repository.

# RStudio Connect sample Dockerfile
FROM ubuntu:bionic

# R from Ubuntu + necessary tools.
RUN export DEBIAN_FRONTEND=noninteractive && \
    apt-get update && \
    apt-get install -y \
            curl \
            gdebi-core \
            r-base

ARG CONNECT_VERSION=1.7.2-7
ARG CONNECT_URL_BASE=https://s3.amazonaws.com/rstudio-connect
ARG CONNECT_PACKAGE=rstudio-connect_${CONNECT_VERSION}_amd64.deb
ARG CONNECT_URL=${CONNECT_URL_BASE}/${CONNECT_PACKAGE}
RUN curl -sL -o rstudio-connect.deb ${CONNECT_URL} && \
    gdebi -n rstudio-connect.deb && \
    rm rstudio-connect.deb

# Copy our configuration over the default install configuration
COPY rstudio-connect.gcfg /etc/rstudio-connect/rstudio-connect.gcfg

# Use a remote license server issuing floating licenses
RUN /opt/rstudio-connect/bin/license-manager license-server licensing.company.com

# Expose the configured listen port.
EXPOSE 3939

# Launch Connect.
CMD ["--config", "/etc/rstudio-connect/rstudio-connect.gcfg"]
ENTRYPOINT ["/opt/rstudio-connect/bin/connect"]

Install R from source (see Section 2.2.2) by updating that Dockerfile with the following:

# Install dependencies needed to build R from source + necessary tools.
RUN export DEBIAN_FRONTEND=noninteractive && \
    apt-get update && \
    apt-get install -y curl gdebi-core && \
    apt-get build-dep -y r-base

# Fetch and install R
ARG R_VERSION=3.4.3
ARG R_ARCHIVE=R-${R_VERSION}.tar.gz
ARG R_URL=https://cran.r-project.org/src/base/R-3/${R_ARCHIVE}
RUN curl -sL -O ${R_URL} && \
    tar zxf ${R_ARCHIVE} && \
    cd R-${R_VERSION} && \
    ./configure \
                --prefix=/opt/R/${R_VERSION} \
                --enable-memory-profiling \
                --enable-R-shlib \
                --with-blas \
                --with-lapack && \
    make && make install && \
    cd .. && \
    rm -r R-${R_VERSION}

This snippet installs only a single R version but may be extended to install a number of different R versions.

Learn more about how RStudio Connect can use multiple R installations in Section 15.

Your organization may have a shared volume containing all of the available R installations. You could mount those installations into the container as it is started. This sample command mounts a shared /shared/software/R location into the well-known /opt/R location within the container:

docker run -d --privileged=true --rm \
    -p :9999:3939 \
    -v $(pwd)/data:/data \
    -v /shared/software/R:/opt/R \
    rstudio/connect-docker:latest