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:
Online- When running in online mode, the Package Manager service is fully functional.Offline- When running in offline mode, the Package Manager service returns503 (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:
You can restart the server with:
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:
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:
And finally, you can use the enable/disable commands to control whether Package Manager should be run automatically at boot time:
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:
This command will open a text editor where you can add or modify settings. For example, to set an environment variable, add the following:
After saving the file, reload the systemd configuration:
Finally, restart the Package Manager service:
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:
$ 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:
To upgrade:
- Download and install the latest
.rpmor.debfile depending on your distribution:
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.
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:
- Stop the Package Manager service. Refer to Stopping and Starting for additional details.
- Uninstall the Package Manager package from your system:
- If it still exists, remove
/opt/rstudio-pm. - Remove logs from
/var/log/rstudio/rstudio-pm/rstudio-pm* - Purge the databases:
- When using SQLite, remove the
SQLite.Dirdirectory. 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.
- When using SQLite, remove the
- Remove the
Server.DataDirdirectory. By default, this is/var/lib/rstudio-pm. - If they still exist, remove configuration files from
/etc/rstudio-pm. - Remove any variable data directories outside the
Server.DataDirdirectory that are defined byFileStorageconfiguration sections. Refer to the File Storage section for more information. - 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:
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:
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#
[Server]
PackageRewriteCompressionLevel = 6
PackageRewriteBufferSize = 32KB
Example Settings#
[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