Skip to content

Server Management#

This section describes common administrative tasks for Posit Connect.

RStudio is now Posit

Our professional products have been renamed to Posit Connect, Posit Workbench, and Posit Package Manager. Some references to RStudio and rstudio-connect will remain as we transition through the rebrand.

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.

Off-Host Execution (Public Beta)

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.

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:

sudo systemctl start rstudio-connect

sudo systemctl stop rstudio-connect

You can restart the server with:

sudo systemctl restart rstudio-connect

You can trigger a configuration reload with the systemctl reload command, which reads the changed configuration from disk:

sudo systemctl reload rstudio-connect

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

Note

Use systemctl reload to send a HUP signal when your configuration changes are limited to properties marked as "reloadable". See the Configuration appendix to learn which settings may be reloaded. Perform a full restart of Posit Connect when changing other properties.

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

sudo systemctl status rstudio-connect

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

sudo systemctl enable rstudio-connect

sudo systemctl disable rstudio-connect

System Messages#

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

The Server.PublicWarning setting defines the message for the welcome page. Server.LoggedInWarning defines the message for the content page. The messages are supplied as HTML snippets. For example:

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
PublicWarning = "<strong>Warning:</strong> Scheduled downtime this weekend."
LoggedInWarning = "Data Science Team Meeting Tomorrow"

Messages can be added or modified without restarting the connect service. After adding the message property to the config file, use the reload command:

sudo systemctl reload rstudio-connect

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.

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

Upgrading#

Note

We recommend backing up Posit Connect's databases and data directory before upgrading. If you need to roll back to a prior version, you will need these backups. See Downgrading for more details.

Upgrading Posit Connect requires limited downtime. Scheduled document renders are interrupted, and connections to running applications and APIs are closed. We recommend upgrading during a period of low usage. Users can be warned ahead of an upgrade with system messages.

The Posit Connect version number is visible on the left-hand navigation pane of the Posit Connect dashboard.

The latest version of Posit Connect is available on the download page along with release notes.

You can upgrade Posit Connect by using one of the following methods:

  • The installation/upgrade script or

  • The latest .rpm or .deb file:

    • Download the latest .rpm or .deb file for your distribution.

    • Run the install command:

      sudo gdebi <rstudio-connect-version.deb>

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

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

For offline environments, simply download the latest .rpm or .deb file, copy it to your offline server, and run the installation command (shown above).

The new version of Posit Connect will install on top of an earlier installation. Existing configuration settings are respected. During installation the Posit Connect service is restarted. Total downtime is less than 10 minutes.

Note

The /etc/rstudio-connect/rstudio-connect-migration.gcfg configuration file is modified during product updates. The Configuration Migration section describes this file and how it is managed. The migration file acts as a staging area for new or updated options. Review the contents of this file after upgrading and move its contents to the main /etc/rstudio-connect/rstudio-connect.gcfg configuration file.

Downgrading#

Rolling an Posit Connect installation back to an older version is not supported.

In order to downgrade an Posit Connect installation to a previously used version, you must first restore an old snapshot of your database and data directory, taken when that version of Connect was in use. Install the older version of Posit Connect only when the database and data directory are compatible with that release. Please contact Posit customer support (support@posit.co) if you need additional guidance.

The method of backup and restore differs depending on the database configured.

  • SQLite backups and restores are detailed in the SQLite documentation's section on SQLite Backups.
  • PostgreSQL backups and restores, including differences for high-availability configurations, are detailed in the High Availability & Load Balancing documentation under Backups, Snapshots, and Data Integrity

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:

    sudo apt-get purge rstudio-connect

    Red Hat/CentOS:

    sudo yum remove rstudio-connect

    SUSE:

    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.

Docker#

Some organizations are starting to deploy Posit Connect within a Docker container. In Connect's native execution mode, the Connect server will manage and run your processes within that container. If you are using Connect's off-host execution features (beta), then content processes are started in isolated Pods on Kubernetes, external to the server container. This section describes the requirements for a container-based deployment.

Off-Host Execution (Public Beta)

To get started with Posit Connect's off-host execution feature, see the official feature documentation.

If you are using multiple Docker containers to run Posit Connect, the High Availability and Load Balancing section contains requirements for a load-balanced, multi-host configuration.

Please contact your Customer Success representative for guidance deploying Posit Connect into your particular environment.

Distributions#

Posit Connect is supported on the Linux distributions given in the System Requirements section. Docker-based deployments need to use one of these operating systems.

R#

R version 3.1.0 or higher must be installed within your Docker container. We recommend installing a curated set of R versions rather than using R installed by a package manager. Use the R installation instructions from the R Installation section when building your Docker image.

Python#

To support Python content deployment on Posit Connect, Python version 3.5 or higher must be installed within your Docker container. We recommend installing a curated set of Python versions rather than using Python installed by a package manager. Use the Python installation instructions from the Python Installation section when building your Docker image.

Quarto#

To support Quarto content deployment on Posit Connect, Quarto must be installed within your Docker container. Use Posit's Quarto Installation instructions when building your Docker image.

Privileged containers#

Off-Host Execution (Public Beta)

The following section applies to Posit Connect's "native" execution mode. If you are running Posit Connect with off-host execution on Kubernetes enabled, then the Posit Connect container does not require privileged access. In this mode, isolation between content items is handled using Kubernetes VolumeMounts. For an overview of this architecture, please see our official feature documentation.

Posit Connect runs processes within an "unshare" environment using bind mounts as described in the Sandboxing section. These bind mounts help Connect hide and isolate parts of the filesystem from executed user processes. Bind mounts are not permitted when running within an unprivileged container.

Docker containers are allowed mount permissions with the SYS_ADMIN capability. You can give these permissions to your container using either the --cap-add=SYS_ADMIN or --privileged=true option.

Learn more about Linux capabilities and CAP_SYS_ADMIN in the capabilities man page.

The Docker container running Posit Connect must be started with either --cap-add=SYS_ADMIN or --privileged=true.

Licensing#

We recommend using a floating license server and having Posit Connect use that license server. The Floating Licenses section explains how to obtain and configure the license server as associating Posit Connect with the floating license server.

Note

We recommend using docker stop rather than docker kill to terminate your Posit Connect Docker containers. Using docker stop allows floating license leases to be gracefully released. License leases not returned to the license server need to wait for lease expiration before they can be reused.

Please contact your Customer Success representative if your organization is unable to run a persistent floating license server.

Storage#

Mount a persistent storage location into the Docker container and configure that location as your Server.DataDir. Do not mount this to the default /var/lib/rstudio-connect location. See the Variable Data section for more information about the data managed by Posit Connect.

Database#

The default SQLite database provider may be used when Posit Connect runs inside a single Docker container and your Server.DataDir is a mounted volume that is NOT part of a networked (NFS) share.

You must use PostgreSQL in all multiple-container deployments or if your persistent storage location is a networked location.

Examples#

This section contains an rstudio-connect.gcfg configuration file and Dockerfile that will help get you started building your own environment.

With the Dockerfile and rstudio-connect.gcfg files in a directory, you can build a Docker image tagged with rstudio/connect-docker:latest with the command:

docker build -t rstudio/connect-docker .

Once the image is built, it can be run with the command:

docker run -d --privileged=true --rm \
    -p :9999:3939 \
    -v $(pwd)/data:/data \
    rstudio/connect-docker:latest

This launches Posit Connect within a Docker container. The Connect instance is available on port :9999 (published from :3939 within the container). This sample mounts the ./data directory as our persistent storage and will need updating for your environment.

Configuration#

This rstudio-connect.gcfg file is copied into the Docker image by a COPY command in the Dockerfile that follows. This file is only an initial configuration and will need customization for your organization.

; /etc/rstudio-connect/rstudio-connect.gcfg

; Posit Connect sample configuration
[Server]
; SenderEmail is an email address used by Posit Connect to send outbound
; email. The system will not be able to send administrative email until this
; setting is configured.
SenderEmail = account@company.com

; The public URL to this Posit Connect container. This might the address for
; a proxy or the host running the Docker container.
Address = https://posit-connect.company.com

; The persistent data directory mounted into our container.
DataDir = /data

[Licensing]
LicenseType = remote

; Use and configure our PostgreSQL database.
[Database]
Provider = postgres

[Postgres]
URL = "postgres://username:password@db.company.com/connect"

[HTTP]
; Posit Connect will listen on this network address for HTTP connections.
Listen = :3939

[Authentication]
; Specifies the type of user authentication.
Provider = password

Dockerfile#

Here is a simple Dockerfile that can be used to run Posit Connect within an Ubuntu 18.04 (bionic) Docker container.

This environment installs a single R version using a DEB installer produced by the r-builds project. The R binaries produced by r-builds live in a version-specific directory beneath /opt/R/.

# Posit Connect sample Dockerfile
FROM ubuntu:bionic

# Install tools needed to obtain and install R and Posit Connect.
RUN export DEBIAN_FRONTEND=noninteractive && \
    apt-get update && \
    apt-get install -y curl gdebi-core && \
    rm -rf /var/lib/apt/lists/*

# Download and install R 3.6.1.
ARG R_VERSION="3.6.1"
ARG R_OS=ubuntu-1804
ARG R_PACKAGE=r-${R_VERSION}_1_amd64.deb
ARG R_PACKAGE_URL=https://cdn.rstudio.com/r/${R_OS}/pkgs/${R_PACKAGE}
RUN curl -fsSL -O ${R_PACKAGE_URL} && \
    export DEBIAN_FRONTEND=noninteractive && \
    apt-get update && \
    apt-get install -f -y ./${R_PACKAGE} && \
    rm ${R_PACKAGE} && \
    rm -rf /var/lib/apt/lists/*

# Download and install Posit Connect.
ARG CONNECT_VERSION=2022.11.0
ARG CONNECT_SHORT_VERSION=2022.11
ARG CONNECT_DISTRIBUTION=ubuntu18
ARG CONNECT_PACKAGE=rstudio-connect_${CONNECT_VERSION}~${CONNECT_DISTRIBUTION}_amd64.deb
ARG CONNECT_URL=https://cdn.rstudio.com/connect/${CONNECT_SHORT_VERSION}/${CONNECT_PACKAGE}
RUN curl -sL -o rstudio-connect.deb ${CONNECT_URL} && \
    apt-get update && \
    gdebi -n rstudio-connect.deb && \
    rm rstudio-connect.deb && \
    rm -rf /var/lib/apt/lists/*

# Copy our configuration over the default install configuration
COPY rstudio-connect.gcfg /etc/rstudio-connect/rstudio-connect.gcfg

# Use a remote license server issuing floating licenses
RUN /opt/rstudio-connect/bin/license-manager license-server licensing.company.com

# Expose the configured listen port.
EXPOSE 3939

# Launch Connect.
CMD ["--config", "/etc/rstudio-connect/rstudio-connect.gcfg"]
ENTRYPOINT ["/opt/rstudio-connect/bin/connect"]

This Dockerfile installs a single R version but may be extended to install a number of different R versions.

Learn more about how Posit Connect can use multiple R installations in the R chapter.

Your organization may have a shared volume containing all of the available R installations. You could mount those installations into the container as it is started. This sample command mounts a shared /shared/software/R location into the well-known /opt/R location within the container:

docker run -d --privileged=true --rm \
    -p :9999:3939 \
    -v $(pwd)/data:/data \
    -v /shared/software/R:/opt/R \
    rstudio/connect-docker:latest
Copyright © Posit Software, PBC. All Rights Reserved