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.
  • R processes serving Shiny applications and Plumber APIs are stopped.
  • R processes rendering R Markdown documents run through completion.
  • In-progress deployments will fail. R processes running as part of the deployment may run to completion.

Start:

  • RStudio Connect process is resumed.
  • Shiny applications and Plumber APIs with a minimum number of R processes are started.
  • Scheduled R Markdown 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 (Red Hat/CentOS 7, Ubuntu 16.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

If you wish to keep the server running without interruption, but reload the configuration, you can use the systemctl command to send a HUP signal:

$ sudo systemctl kill -s HUP --kill-who=main 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 a HUP signal when your configuration changes are limited to properties marked as reloadable. See Appendix A to learn which settings may be reloaded via HUP. 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 12.04, Ubuntu 14.04, Red Hat 6)

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.

If you wish to reload the configuration and keep the server and all R processes running without interruption, you can use the reload command:

$ sudo reload rstudio-connect

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

Use a HUP signal when your configuration changes are limited to properties marked as reloadable. See Appendix A to learn which settings may be reloaded via HUP. 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.

Messages are set in the /etc/rstudio-connect/rstudio-connect.gcfg file. Server.PublicWarning 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:

[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 either systemd (Red Hat/CentOS 7, Ubuntu 16.04):

sudo systemctl kill -s HUP --kill-who=main rstudio-connect

or Upstart (Ubuntu 12.04, 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 R Markdown documents are not interrupted. Connections to running Shiny applications and Plumber 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:

    sudo gdebi <rstudio-connect-version.deb>

    Red Hat/CentOS:

    sudo yum install --nogpgcheck <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
  3. Remove /opt/rstudio-connect if it still exists.
  4. Remove logs from /var/log/rstudio-connect*
  5. 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.
  6. Remove the Server.DataDir directory. By default, this is /var/lib/rstudio-connect.
  7. Remove configuration files from /etc/rstudio-connect if they still exist.