10. Server Management

In this section, you will learn:

Server maintenance

While managing a Posit Connect server, several common maintenance tasks occur, including configuration changes, backup management, and software updates.

Configuration changes

Most Posit Connect configuration settings are located in /etc/rstudio-connect/rstudio-connect.gcfg. These settings might need to be updated for a number of reasons. For configuration changes to take effect, the server either needs to be restarted or reloaded.

Server reload vs restart

If a configuration item is marked “Reloadable: true” in the Appendices - Configuration section of the Administrator Guide, then reloading the server will apply the change. However, a server restart is required if a configuration item is not marked as Reloadable. The main benefit of a reload versus restart is the server is re-initialized, but the current processes and open connections are not interrupted.

For example, changes in SMTP mail settings can be applied by a server reload, whereas a change to the Server Address requires a server restart.

The commands for restarting and reloading a server are listed below. There is more information about systemd and each command’s effect in the Server Management section of the Administrator Guide.

Restarting a server

sudo systemctl restart rstudio-connect

Reloading a server

sudo systemctl reload rstudio-connect

Backups

A frequent backup strategy is crucial to server management; the exact details will depend on your organization’s architecture. In creating backup snapshots, we recommend backing up the Posit Connect configuration file in /etc/rstudio-connect and the variable data directory, which defaults to /var/lib/rstudio-connect. Stop the server before taking backups.

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

Managing upgrades

Posit Connect releases new versions frequently containing new features, stability improvements, bug fixes, and more. We recommend upgrading servers often to take advantage of the improvements. In addition to utilizing the latest product, upgrading keeps servers on supported versions of the product as listed on our support page. Every organization operates differently, however, we recommend upgrading at a minimum of once a year, ideally twice or more.

Upgrade process

  1. Before upgrading, ensure backups have been created.
  2. Review the Posit Connect release notes for the versions between the current and new versions.
  3. Follow the instructions on the Posit Connect upgrade page, which requires an upgrade script or installation file to be downloaded and executed. If your server is offline, you should copy the installation file onto your server.

License management

A Posit Connect server requires a license key to be activated at its inception and occasionally at renewals depending on the renewal type. This process can be done online or offline, depending on your environment. Posit Connect will attempt to send an email to administrators when the license key is 60 days from expiration. The Connect Dashboard will notify administrators and publishers when the license is within 15 days of expiration.

To determine the current license status of your server, you can use the following command:

sudo /opt/rstudio-connect/bin/license-manager status

When you receive a new license key, it can be activated by the following command, followed by a server restart.

sudo /opt/rstudio-connect/bin/license-manager activate <product-key>
sudo systemctl restart rstudio-connect

More information about License Management is available in the Administrator Guide.

R, Python, and Quarto versions

Multiple versions of R, Python, and Quarto can be installed on a Posit Connect server. We recommend installing multiple versions so that when a user deploys content that needs a specific version, Connect can host that content successfully. R, Python, and Quarto configurations are all in the standard configuration file /etc/rstudio-connect/rstudio-connect.gcfg.

R versions

First, install multiple R versions by following the Install R documentation section. Once installation is complete, a configuration may be required if you follow the explicit configuration outlined below, otherwise by default Posit Connect will scan and automatically detect the installed R versions without any configuration.

Note

Posit Connect does not require R, Python, or Quarto to be installed on the server. Most teams will want to utilize all three; however if your organization only has R users, you can proceed only to install R.

Scanning

By default Posit Connect will have version scanning enabled, where it will look for R in locations known to contain multiple version installations. This behavior can be disabled by setting the following configuration option:

[R]
ExecutableScanning = false

Explicit

Posit Connect can be instructed to use specific R installations. The Executable setting indicates an installation of R that Connect should use. Specify Executable once for each R installation. While this explicit configuration can be used in conjunction with scanning, it is recommended to disable scanning when explicitly defining the R versions to use, like in the sample configuration below.

[R]
ExecutableScanning = false
Executable = /opt/R/3.3.1/bin/R
Executable = /opt/R/3.2.4/bin/R
Executable = /opt/R/3.1.3/bin/R

Python versions

First, install multiple versions of Python by following the Install Python documentation section. Once installation is complete, Posit Connect configuration is required.

In contrast to R versions, Python versions must be explicitly defined and enabled in the configuration. Enable Python with Enabled = true and specify Executable once for each Python installation.

[Python]
Enabled = true
Executable = /opt/python/3.7.6/bin/python3
Executable = /opt/python/3.8.1/bin/python3

Quarto versions

Similar to Python, first install multiple versions of Quarto by following the Install Quarto section of the documentation. Once installation is complete, Posit Connect configuration is required.

Quarto versions must be explicitly defined and enabled in the configuration. Enable Quarto with Enabled = true and specify Executable once for each Quarto installation.

[Quarto]
Enabled = true
Executable = "/opt/quarto/1.0.37/bin/quarto"
Executable = "/opt/quarto/1.1.189/bin/quarto"
Executable = "/opt/quarto/1.2.66/bin/quarto"

SSL

While not strictly required, we highly recommend configuring SSL/TLS certificates for greater security. Detailed instructions are available in the Configuring SSL Certificates in Posit Connect section of the documentation.

The main steps required are:

  1. Add SSL certificate and key locations to the configuration file
  2. Change the listening port
  3. Redirect HTTP traffic to HTTPS
  4. Restart the server

Migrations

As your organization grows, the need to migrate to a new server or change associated services such as authentication and database could arise. The exact steps for each will vary based on your architecture. General guidance on each type of migration is provided below and in the documentation.

Server migration

When migrating servers, we recommend making as few changes as possible, successfully migrating, and then resuming making changes. For example, install the same version of R and Python on the new server and start adding new ones only after the migration is complete. Refer to the Server Migrations section of the Administrator Guide for detailed steps.

Auth migration

When changing the authentication method, great care must be applied to ensure users have the correct content and can use Posit Connect as expected. If maintaining existing content is not important, the easiest route is to purge, reinstall Posit Connect, and then make the authentication change.

If you need to migrate to a new authentication method and keep users’ content, follow the detailed instructions provided in the Auth Provider Migration section of the Administrator Guide. This is commonly required if you start using the built-in username/password method and need to move to use your organization’s SSO or LDAP-like authentication method.

Database migration

Posit Connect has a built-in migrate command for migrating data from one database to another. More details can be referred to in the Database Migration section of the Administrator guide.

Note

Only migration from SQLite to PostgreSQL and from PostgreSQL to PostgreSQL are supported.

The main steps required are:

  1. Stop the server
  2. Backup your data
  3. Ensure you have a Postgres configuration section
  4. Run the migration
  5. Upgrade the Database.Provider configuration section to point to the new database
  6. Restart the server

Connect API

Posit Connect has a rich API that can perform many actions. You will learn to utilize the Connect API throughout this course to manage users, groups and content.

To utilize the API, you will need to use a library that can make HTTP requests in any language, below are some popular options:

  • curl (Linux tool for making HTTP calls)
  • httr (R HTTP library)
  • requests (Python HTTP library)

There is also an R package connectapi that makes it easier to use the Connect API and includes helpful functions.

Endpoints

The Connect API includes endpoints to manage many aspects, some of which are listed below:

  • Audit logs
  • Content bundles
  • Content
  • Content permissions
  • Groups
  • Jobs
  • R, Python, and Quarto information
  • Tags
  • Tasks
  • Users
  • Vanity URLs

API Keys

Most endpoints require you to identify yourself as a valid Posit Connect user. You do this by specifying an API Key when you call the server. The API Keys chapter of the Posit Connect User Guide explains how to create an API Key.

Once you have an API Key, you can authenticate by passing the key with the prefix “Key  ” (the space is important) in the Authorization header.

For example, below is a sample request using curl:

curl -H "Authorization: Key XXXXXXXXXXX" \
     https://rstudioconnect.example.com/__api__/v1/server_settings/r

Exercise

Tip

🚀 Launch the exercise environment!

In the exercise environment you will get experience:

  • Applying configuration changes
  • Starting, Stopping and Restarting the Connect service
  • Upgrading Connect
  • Installing a new version of R and explicitly listing versions
  • Migrating databases from SQLite to PostgreSQL
  • Creating an API key and making an API request