Skip to main content

Server Management

This section describes common administrative tasks for Posit Connect.

Stopping and starting

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

Note

systemd is a management and configuration platform for Linux.

NoteOff-Host Execution

If you are running Posit Connect via the Helm chart, then systemd is not used to start the server. Instead, you should use the helm upgrade ... command to perform a rolling update. A helm upgrade that changes the configuration starts Connect in a new pod, so the configuration reload described on this page does not apply.

On stop/start or restart the following occurs:

Stop:

  • The Posit Connect process is stopped.
  • Processes serving applications and APIs are stopped.
  • Processes rendering documents run through completion.
  • In-progress deployments will fail. Processes running as part of the deployment may run to completion.

Start:

  • Posit Connect process is resumed.
  • Applications and APIs with a minimum number of processes are started.
  • Scheduled document render updates missed during system downtime are run at most once.

The Posit 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:

Terminal
sudo systemctl start rstudio-connect
Terminal
sudo systemctl stop rstudio-connect

You can restart the server with:

Terminal
sudo systemctl restart rstudio-connect

You can trigger a configuration reload with the systemctl reload command, which sends a HUP signal to Connect:

Terminal
sudo systemctl reload rstudio-connect

Connect rereads its configuration and applies the changes to properties marked as “reloadable”, without interrupting the current processes or any of the open connections to the server. Every other property keeps its running value until Connect restarts. To check what a reload applied, see Confirm a configuration reload.

Note

Use systemctl reload when your configuration changes are limited to properties marked as “reloadable”. See the Reloadable properties section of the Configuration appendix to learn which settings are reloadable. Perform a full restart of Posit Connect when changing other properties.

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

Terminal
sudo systemctl status rstudio-connect

If the service failed to start, see Startup failures for how to locate the specific error message.

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

Terminal
sudo systemctl enable rstudio-connect
Terminal
sudo systemctl disable rstudio-connect

Confirm a configuration reload

Connect reports the result of each reload in the service log. The lists of changed settings name settings but not their values.

When Connect applies a reload, it logs the reloadable settings that changed at the INFO level:

Reloaded the configuration; changed reloadable settings: SMTP.Host, SMTP.Port

If no reloadable setting changed, the message says Reloaded the configuration; no reloadable setting changed.

When the configuration changes settings that a reload does not apply, Connect also logs a warning that names them. Connect reports a named section that you add or remove, such as [LDAP "corp"], the same way:

Changed settings that a reload does not apply: LDAP "corp" (section removed), Server.EmailProvider. Restart Connect to apply them.

Connect repeats this warning on every reload until it restarts, or until the configuration file matches the running values again. Connect lists a deprecated setting that it no longer reads, such as Server.PublicWarning, the same way. A restart ignores that setting too.

When Connect cannot read the configuration, or a reloadable setting is not valid, Connect rejects the whole reload. Connect keeps running with its previous configuration and logs the reason as an error:

Cannot reload the configuration; keeping the running configuration: <reason>

Correct the configuration and reload again. If the same reload also changed settings that need a restart, Connect checks the reloadable settings against the running values of those settings. The reason can then name a value that is no longer in the configuration file, and the error message ends with a sentence that says so. In that case, restart Connect to apply all of the changes.

Setting environment variables via systemd

When running Posit Connect under systemd, you can set environment variables for the Connect server process using the /etc/default/rstudio-connect file. This is useful for configuring system-level settings such as proxy configuration, locale settings, or other environment variables that the Connect server process needs. For details about which requests use proxy settings, see Outbound proxy servers.

Note

This file only affects the Connect server process itself when running under systemd. It does not apply when running Connect in Docker or Kubernetes environments. For information about how environment variables are inherited by content processes (applications, APIs, reports), see the Process Management documentation.

The file uses a simple KEY=VALUE format, with one variable per line. Lines beginning with # are treated as comments. For example:

/etc/default/rstudio-connect
# Proxy configuration
HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1

# Locale settings
LANG=en_US.UTF-8
LC_ALL=en_US.UTF-8

After creating or modifying this file, restart the Connect service for the changes to take effect:

Terminal
sudo systemctl restart rstudio-connect

You can verify that environment variables are set correctly by checking the running process:

Terminal
PID=$(sudo systemctl show rstudio-connect --property=MainPID --value)
sudo cat /proc/$PID/environ | tr '\0' '\n'

System messages

Administrators can add a message to the Posit Connect welcome page and content page.

NoteDeprecated in favor of Custom Messaging

The Server.PublicWarning and Server.LoggedInWarning settings are deprecated. Connect imports each setting into the database once and ignores it after that. Connect logs a deprecation warning while either setting remains in the configuration file.

Manage the welcome page message, the content page message, and several other user-facing messages on the Custom Messaging page. Changes take effect immediately, without a restart or reload.

Health-check

Posit 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.

Terminal
curl -I -X GET http://myserveraddress:myserverport/__ping__

Determine version installed

The version of Posit Connect can be determined from the Connect web interface or terminal.

To find the version in the Connect web interface, navigate to the System tab then the Info page. The version is displayed under the System Info heading.

To find the version using the terminal, use the command:

Terminal
/opt/rstudio-connect/bin/connect --version

Downgrading

Rolling a Posit Connect installation back to an older version is not supported. Once an upgraded version of Connect is used within an environment, that environment is incompatible with older releases.

If you must revert to a previously used version, you must restore your Posit Connect environment from a previously created backup that is compatible with the Connect version. Please contact Posit customer support via the Posit support form if you need additional guidance.

Purging Posit Connect

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

  1. Stop the Posit Connect service. (See Starting and Stopping for details)

  2. Uninstall the Posit Connect package from your system.

    Ubuntu:

    Terminal
    sudo apt-get purge rstudio-connect

    Red Hat:

    Terminal
    sudo yum remove rstudio-connect

    SUSE:

    Terminal
    sudo zypper remove rstudio-connect
  3. Remove logs from /var/log/rstudio/rstudio-connect/*

  4. 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.

  5. Remove the Server.DataDir directory. By default, this is /var/lib/rstudio-connect.

  6. Remove configuration files from /etc/rstudio-connect if they still exist.