Server Migration with Local Storage

This section explains how to migrate your Posit Connect installation from a single provisioned server or virtual machine (VM) to another.

These instructions only apply for single-host installations that use SQLite and local storage. They do not apply when using PostgreSQL or when the Connect variable data is stored on a networked file system.

Prerequisites

These steps can be performed on the target server while your existing Connect installation is active and running.

  1. Target server running a supported Linux distribution.

  2. Either root or sudo access on the current and target Connect server.

    Managing the Connect service and its configuration requires elevated privileges.

  3. Upgrade Connect, if necessary.

    Confirm that the version of Connect on your current server matches the product version you intend to use on the target server. Separate product upgrades from changes to your infrastructure.

  4. Install R, Python, and Quarto.

    Mirror the currently installed versions of R, Python, and Quarto on the target server.

    Most installations will use this guidance:

  5. Install system packages.

    Install system packages onto the target server that are installed on the active server. These system dependencies are required by many R and Python packages.

    Some content will fail to run without the appropriate system libraries.

  6. Create the Unix users and groups used by Posit Connect.

    The Applications.RunAs user and the Applications.SharedRunAsUnixGroup group must exist on the target server.

    If the Applications.SharedRunAsUnixGroup group has members other than Applications.RunAs user, those accounts are probably used when running content. Create those Unix accounts on the target server, as well.

    Tip

    It is recommended, though not required, that user and group identifiers (uid and gid) are consistent between the old and new servers.

  7. A Connect API key for an administrator account.

    You will use this API key to clear the runtime caches and optionally rebuild content after starting Connect in the new environment.

Workflow

Step 1: Stop Connect (old)

sudo systemctl stop rstudio-connect

Step 2: Configure Connect

Transfer the /etc/rstudio-connect/rstudio-connect.gcfg configuration from the old server to the new one. Make sure that the networked file system is available at the same location on the new server.

Step 3: Transfer files

Transfer the Connect variable data and database files from the old server to the new.

Copy files from the old location to the new. By default, Connect data lives beneath /var/lib/rstudio-connect, though your configuration may use an alternate Server.DataDir location.

The copy MUST preserve file ownership, permissions, and special files like symbolic links. Not all file transfer clients are able to preserve these attributes.

Consider using rsync with the --archive / -a option to perform the transfer, such as in the following example.

rsync -a oldserver:/var/lib/rstudio-connect/ /var/lib/rstudio-connect

If you installation also customizes the Database.Dir or SQLite.Dir, copy those locations to the new server, as well.

Step 4: Start Connect (new)

Start the Connect service on the target server.

sudo systemctl start rstudio-connect

Step 4: Route traffic

Adjust your infrastructure so your Connect requests are routed to and serviced by the new Connect server.

Step 4: Clear runtime caches & rebuild content

The content runtime caches containing the R and Python package dependencies for your content are incompatible with the Linux distribution and system libraries available on the new server.

You MUST clear these runtime caches and rebuild your deployed content.