Server Management

This section describes common administrative tasks for RStudio Package Manager.

Online and Offline Modes

Note

See also Managing Cluster Nodes for information on managing the online/offline modes of multiple nodes in a cluster.

The RSPM service supports two modes:

  1. Online - When running in online mode, the RSPM service is fully functional.
  2. Offline - When running in offline mode, the RSPM service returns 503 (service unavailable) responses for all requests. In offline mode, only a few services are available:
    • API methods that support switching to online mode and enumerating cluster nodes
    • A database connection that listens for notifications to enter online or offline mode (PostgreSQL only)

When initiating offline mode, the service attempts to complete any in-progress work and finishes serving any outstanding HTTP requests before going offline.

When initiating online mode, the service reads the RSPM configuration file and starts service with the new settings effective. The only exceptions are network- related settings like the HTTP.Listen port. When updating network settings, please stop and start the RSPM service.

Use the rspm offline and rspm online CLI commands to initiate online and offline modes.

Stopping and Starting

Note

In some cases, you may wish to take the RSPM service offline and back online instead of stopping and starting the service. See Online and Offline Modes for information.

Occasionally it is necessary to start and stop the RStudio Package Manager service. Stopping and starting is handled by systemd or Upstart.

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

After a restart, any scheduled syncs that were missed during downtime will automatically begin. See the CRAN Source section for details.

systemd

Distributions using systemd include Red Hat/CentOS 7-8, openSUSE/SLES, and Ubuntu.

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 Package Manager installer installs a systemd service called rstudio-pm, which causes the RStudio Package Manager to be started and stopped automatically when the machine boots up and shuts down. The rstudio-pm service is also automatically launched during installation.

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

Terminal

sudo systemctl start rstudio-pm
sudo systemctl stop rstudio-pm

You can restart the server with:

Terminal

sudo systemctl restart rstudio-pm

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:

Terminal

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

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

Note

Use a HUP signal when your configuration changes are limited to properties marked as reloadable. Perform a full restart of RStudio Package Manager when changing other properties.

A HUP signal only reloads configuration settings that have explicitly changed. Commenting out a setting will not affect the configuration when using the HUP signal. If you have commented out a setting instead of changing the setting value, restart the RStudio Package Manager service instead of using the HUP signal.

Additionally, licensing changes support the HUP signal.

See the Appendix - Reloadable Properties section to learn which settings may be reloaded via HUP.

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

Terminal

sudo systemctl status rstudio-pm

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

Terminal

sudo systemctl enable rstudio-pm
sudo systemctl disable rstudio-pm

Upstart (Red Hat/CentOS 6)

Upstart is a system used to automatically start, stop, and manage services. The installer writes an Upstart configuration file to /etc/init/rstudio-pm.conf. This instructs the Upstart to initialize RStudio Package Manager 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 rstudio-pm process is respawned if the process unexpectedly terminates. However, in the event that there is an issue which consistently prevents RStudio Package Manager 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 Package Manager startup attempt before it transitions to the "stopped" state.

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

Terminal

sudo start rstudio-pm
sudo stop rstudio-pm

To restart the server you can run:

Terminal

sudo stop rstudio-pm
sudo start rstudio-pm

The restart command re-initializes the server.

Note

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-pm.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:

Terminal

sudo reload rstudio-pm

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

Note

Use a HUP signal when your configuration changes are limited to properties marked as reloadable. Perform a full restart of RStudio Package Manager when changing other properties.

A HUP signal only reloads configuration settings that have explicitly changed. Commenting out a setting will not affect the configuration when using the HUP signal. If you have commented out a setting instead of changing the setting value, restart the RStudio Package Manager service instead of using the HUP signal.

See the Appendix - Reloadable Properties section to learn which settings may be reloaded via HUP.

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

Terminal

sudo status rstudio-pm

Health-Check

RSPM provides a simple health-check endpoint /__ping__, that can be used to test if the service is up/listening. The endpoint returns an empty JSON response and an HTTP 200 status. For example, on our public site this looks like:

Terminal

$ curl -I -X GET https://packagemanager.rstudio.com/__ping__
HTTP/2 200
content-type: application/json
...

Upgrading

Note

See Upgrading a Cluster for details on upgrading a highly- available cluster with minimal downtime.

Upgrading RStudio Package Manager requires limited downtime. During an upgrade users will not be able to install packages. We recommend upgrading during a period of downtime.

The latest version is available on the download page along with release notes. The current version is available by running:

Terminal

cat /opt/rstudio-pm/VERSION

To upgrade:

  1. Download the latest .rpm or .deb file

  2. Run the install command:

    sudo gdebi <rstudio-pm-version.deb>

    sudo yum install <rstudio-pm-version.rpm>

    sudo zypper install <rstudio-pm-version.rpm>

The new version of RStudio Package Manager will install on top of an earlier installation. Existing configuration settings are respected. During installation the RStudio Package Manager service is restarted.

Purging RStudio Package Manager

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

  1. Stop the RStudio Package Manager service. (See Stopping and Starting for details)

  2. Uninstall the RStudio Package Manager package from your system:

    sudo apt-get purge rstudio-pm

    sudo yum remove rstudio-pm

    sudo zypper remove rstudio-pm

  3. Remove /opt/rstudio-pm if it still exists.

  4. Remove logs from /var/log/rstudio-pm*
  5. Purge the databases
    • When using SQLite, remove the SQLite.Dir directory. This has a default location of /var/lib/rstudio-pm/db.
    • When using PostgreSQL, drop the databases used by RStudio Package Manager. You may also wish to remove the PostgreSQL user associated with RStudio Package Manager.
  6. Remove the Server.DataDir directory. By default, this is /var/lib/rstudio-pm.
  7. Remove configuration files from /etc/rstudio-pm if they still exist.
  8. Remove any variable data directories outside the Server.DataDir directory that are defined by FileStorage configuration sections. See the Variable Data Classes section for more information.
  9. Remove any data stored on S3. See the Storage Class Destinations section.

Backups

We recommend including the RStudio Package Manager configuration file in /etc/rstudio-pm as well as the variable data directory which defaults to /var/lib/rstudio-pm in your system backups. If you have configured the databases to be stored outside the data directory, ensure that it is also included in the backup. If you have customized the storage locations for any variable data classes (see the Variable Data Classes section), each customized directory should also be included in the backup.

If you use S3 to store variable data, consider whether you need additional backups for your S3 data. See the Storage Class Destinations section for more information about storing variable data on S3.

A running RStudio Package Manager server may be writing into the data directory. You should stop the RStudio Package Manager server before taking a backup.

Terminal

sudo stop rstudio-pm
# Run appropriate backup steps here.
sudo start rstudio-pm

Your platform may need alternate commands to restart RStudio Package Manager. Please see the Stopping and Starting section for instructions specific to your operating system version.

Server Migrations

See the Server Migrations section for information on migrating your RStudio Package Manager installation to another environment.

Privileged Ports

RStudio Package Manager listens on HTTP port 4242 by default. When you modify the HTTP.Listen or HTTPS.Listen configuration properties to use a privileged port under 1024, the service will fail to start, and you will see an error like the following in `/var/log/rstudio-pm.log:

2017/11/28 13:41:59 Error: Could not initialize the HTTP listener: listen tcp :80: bind: permission denied

If you wish to listen with HTTP or HTTPS on a privileged port (< 1024), you can grant the RStudio Package Manager binary permission to do so by issuing the following command as root:

Terminal

sudo setcap 'cap_net_bind_service=+ep' /opt/rstudio-pm/bin/rstudio-pm

After issuing the above command, restart the service (see the Stopping and Starting section).

Improving Performance for Local Sources

When RStudio Package Manager adds packages to local sources, it stores the packages in tar archives using gzip compression. If you are installing large packages in local sources, you may be able to improve performance by adjusting these settings:

  • Gzip Compression Level - A lower value will result in higher storage requirements, but increases performance. Valid values range from 1 to 9.
  • Write Buffer Size - Use a buffer size that is appropriate for the packages storage target. See the Variable Data Classes section for information on where packages are stored.

Default Settings

; /etc/rstudio-pm/rstudio-pm.gcfg

[Server]
PackageRewriteCompressionLevel = 6
PackageRewriteBufferSize = 32KB

Example Settings

; /etc/rstudio-pm/rstudio-pm.gcfg

[Server]
; Decreasing the compression level increases the storage requirements, but
; greatly increases the speed of writing packages for local sources.
PackageRewriteCompressionLevel = 1

; Set a buffer size that is appropriate for the storage system that contains
; packages.
PackageRewriteBufferSize = 2MB