Skip to content

Server Management#

This section describes common administrative tasks for Package Manager.

Online and Offline Modes#

For information on managing the online/offline modes of multiple nodes in a cluster, reference the Managing Cluster Nodes documentation.

The Package Manager service supports two modes:

  1. Online - When running in online mode, the Package Manager service is fully functional.
  2. Offline - When running in offline mode, the Package Manager 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 Package Manager 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 Package Manager 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 Package Manager service offline and back online instead of stopping and starting the service. For more information, reference the Online and Offline Modes section.

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

Note

systemd is a management and configuration platform for Linux.

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

The Package Manager installer installs a systemd service called rstudio-pm, which causes the 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 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 Package Manager service instead of using the HUP signal.

Additionally, licensing changes support the HUP signal.

To learn which settings may be reloaded via HUP, review the Appendix - Reloadable Properties section.

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 Package Manager should be run automatically at boot time:

Terminal
$ sudo systemctl enable rstudio-pm
$ sudo systemctl disable rstudio-pm

Editing Default Service Settings#

In certain situations, you may need to modify the default Package Manager service configuration - for example, to add environment variables required by the application. Instead of editing the main service file directly (which can be overwritten during updates), you can create an override file using the following command:

Terminal
$ sudo systemctl edit rstudio-pm.service

This command will open a text editor where you can add or modify settings. For example, to set an environment variable, add the following:

[Service]
Environment="ENV_VAR=value"

After saving the file, reload the systemd configuration:

Terminal
$ sudo systemctl daemon-reload

Finally, restart the Package Manager service:

Terminal
$ sudo systemctl restart rstudio-pm

Health-Check#

Package Manager 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.posit.co/__ping__
<< HTTP/2 200
<< content-type: application/json
<< ...

Upgrading#

Important

The upgrade instructions below cover upgrading Posit Package Manager on the same server and between supported versions. If you are planning on changing servers or you are upgrading from an older unsupported version, please see the How to Upgrade and/or Migrate Posit Team guide.

Note

For details on upgrading a highly-available cluster with minimal downtime, reference the Upgrading a Cluster section.

Upgrading 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:

  • Download and install the latest .rpm or .deb file depending on your distribution:
curl -fO https://cdn.posit.co/package-manager/deb/amd64/rstudio-pm_2024.11.0-6_amd64.deb
sudo apt install ./rstudio-pm_2024.11.0-6_amd64.deb

curl -fO https://cdn.posit.co/package-manager/deb/amd64/rstudio-pm_2024.11.0-6_amd64.deb
sudo apt install ./rstudio-pm_2024.11.0-6_amd64.deb

curl -fO https://cdn.posit.co/package-manager/deb/amd64/rstudio-pm_2024.11.0-6_amd64.deb
sudo apt install ./rstudio-pm_2024.11.0-6_amd64.deb

curl -fO https://cdn.posit.co/package-manager/rpm/x86_64/rstudio-pm-2024.11.0-6.x86_64.rpm
sudo dnf install rstudio-pm-2024.11.0-6.x86_64.rpm

curl -fO https://cdn.posit.co/package-manager/rpm/x86_64/rstudio-pm-2024.11.0-6.x86_64.rpm
sudo dnf install rstudio-pm-2024.11.0-6.x86_64.rpm

# Be sure to import the key before installing the RPM. See the Signed Builds section below.
sudo zypper refresh
curl -fO https://cdn.posit.co/package-manager/rpm/x86_64/rstudio-pm-2024.11.0-6.x86_64.rpm
sudo zypper install rstudio-pm-2024.11.0-6.x86_64.rpm

# Be sure to import the key before installing the RPM. See the Signed Builds section below.
sudo zypper refresh
curl -fO https://cdn.posit.co/package-manager/rpm/x86_64/rstudio-pm-2024.11.0-6.x86_64.rpm
sudo zypper install rstudio-pm-2024.11.0-6.x86_64.rpm

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

Note

Upgrade failed or trying to upgrade across several major versions? Try Purging Package Manager and doing a fresh install afterwards.

Backups#

We recommend including the 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 (refer to the File Storage 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. Reference the File Storage: S3 section for more information about storing variable data on S3.

A running Package Manager server may be writing into the data directory. You should stop the 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 Package Manager. Please refer to the Stopping and Starting section for instructions specific to your operating system version.

Server Migration#

You may need to migrate your Package Manager installation:

  • When moving from one environment to another (e.g., physical to virtual or on-prem to cloud)
  • To facilitate HA setup with more than one node

Several factors must be considered before migrating your Package Manager installation from one server to another. We recommend that you don't make any configuration changes (or as few as possible) during the initial migration. If, for instance, you are migrating to a new server and upgrading to a new default version of R, complete the migration first. Then upgrade R in subsequent steps.

Before you migrate the server, perform a backup to obtain a consistent copy of the data in the necessary directories. These directories can then be copied to the new server.

To conduct a server migration, refer to the How to Upgrade and/or Migrate Posit Team guide.

If you are also changing to a different database provider, refer to the section on Changing the Database Provider.

Purging Package Manager#

If you are migrating Package Manager to a different server, you may want to consider purging Package Manager. You may also want to consider purging and doing a fresh installation of Package Manager if upgrading fails.

Important

Purging Package Manager will fully remove configured sources, repositories, and other config options. See Backups to back up important data before purging.

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

  1. Stop the Package Manager service. Refer to Stopping and Starting for additional details.
  2. Uninstall the Package Manager package from your system:
Terminal
$ sudo apt-get purge rstudio-pm
Terminal
$ sudo yum remove rstudio-pm
Terminal
$ sudo zypper remove rstudio-pm
  1. If it still exists, remove /opt/rstudio-pm.
  2. Remove logs from /var/log/rstudio/rstudio-pm/rstudio-pm*
  3. 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 Package Manager. You may also wish to remove the PostgreSQL user associated with Package Manager.
  4. Remove the Server.DataDir directory. By default, this is /var/lib/rstudio-pm.
  5. If they still exist, remove configuration files from /etc/rstudio-pm.
  6. Remove any variable data directories outside the Server.DataDir directory that are defined by FileStorage configuration sections. Refer to the File Storage section for more information.
  7. Remove any data stored on S3.

Privileged Ports#

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/rstudio-pm/rstudio-pm.log:

/var/log/rstudio/rstudio-pm/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 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. Reference the Stopping and Starting section for additional details.

Improving Performance for Local Sources#

When 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 File Storage 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