Multi-Server Installation

This page describes how to install Posit Connect on multiple Linux servers for high availability (HA) and load balancing. For a single-server deployment, see the Server installation page. For an overview of all installation methods, see the Installation Overview.

Prerequisites

Before you install, review the Requirements and select the Multiple servers (HA) deployment type.

Important

Complete Step 1 through Step 3 on each Linux server in the cluster. Steps 4 and 5 apply shared configuration: make the same changes on each server. Complete Step 6 and Step 7 one time for the cluster.

Step 1: Install runtimes

Install one or more versions of the runtimes that your team needs now:

Runtime installation is flexible and incremental. You can add or update runtimes at any time when the needs of your team change. The starter configuration of Connect discovers versioned installations beneath /opt/python, /opt/R, /opt/local/R, /opt/quarto, and /opt/node. You do not need to configure executable paths for runtimes installed beneath these standard roots.

Step 2: Download and install

Note

Download and/or use of Posit Connect is governed under the terms of the Posit End User License Agreement. By downloading you agree to the terms posted there.

Run the following to subscribe to the Posit package repository and install Connect:

Terminal

curl -1sLf \
  'https://dl.posit.co/public/pro/setup.deb.sh' \
  | sudo -E bash

sudo apt install rstudio-connect
sudo apt-mark hold rstudio-connect

Terminal

curl -1sLf \
  'https://dl.posit.co/public/pro/setup.rpm.sh' \
  | sudo -E bash

sudo dnf install rstudio-connect
sudo dnf install 'dnf-command(versionlock)'
sudo dnf versionlock add rstudio-connect

Terminal

curl -1sLf \
  'https://dl.posit.co/public/pro/setup.rpm.sh' \
  | sudo -E bash

sudo zypper install rstudio-connect
sudo zypper addlock rstudio-connect

The package is held after installation to prevent unintended upgrades during routine system maintenance. See the Upgrade page when you are ready to upgrade Connect.

Verify install

Verify the installation by ensuring that the service is running:

Terminal

sudo systemctl status rstudio-connect

Step 3: Verify and activate your license

Verify the status of your license by running the following command:

Terminal

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

If you have a license file, transfer that <license-file>.lic file to the server hosting Posit Connect. Ensure ownership and permissions are correct, then activate it with the commands:

Terminal

sudo chown root <license-file>.lic
sudo chmod 0600 <license-file>.lic
sudo cp -a <license-file>.lic /var/lib/rstudio-connect/

Those commands assume that the Connect server runs as root, as that is the most common way to run Connect. If you run Connect as an unprivileged user such as rstudio-connect, the license file needs to be owned by that user.

Terminal

sudo chown rstudio-connect <license-file>.lic
sudo chmod 0600 <license-file>.lic
sudo cp -a <license-file>.lic /var/lib/rstudio-connect/

Posit recommends using license file activation rather than license key activation. License files work well in all environments including ephemeral, container-based, or air-gapped environments. See License activation methods for more details.

For full details and information about license key activation, see the License management page of this guide.

Step 4: Configure high availability and load balancing

After you install Connect on each server, complete the following checklist to configure the shared resources of the cluster.

Migrate to a PostgreSQL database (if running SQLite). All nodes in the cluster must use the same PostgreSQL database.
Configure each server’s Server.DataDir to point to the same shared location; see Variable Data and Shared Data Directory Requirements.
Keep each node’s Server.LocalDataDir on local disk, not shared storage; see Variable Data.
If the Database.Dir setting has been customized, ensure that it points to a consistent, shared location on each server; see Variable Data and Shared Data Directory Requirements.
Configure each server’s Server.LandingDir to point to the same shared location (if using a custom landing page); see Using a Custom Landing Page and Shared Data Directory Requirements.
Configure your load balancer to route traffic to your Connect nodes with sticky sessions and WebSocket support; see Networking for more connectivity details.

Note

Most users will want all nodes using identical configurations in HA environments, but it is not strictly required.

For HA limitations and advanced details, see the High Availability and Load Balancing page.

Step 5: Initial configuration

Note

Make the same configuration changes in the /etc/rstudio-connect/rstudio-connect.gcfg file on each server. Then restart Connect on each server. Set Server.Address to the URL of your load balancer.

Configure the following before you log in to Connect for the first time:

Server email address
Server address
Authentication

Server email address and server address

Property	Description
`Server.SenderEmail`	The email address from which Connect sends emails.
`Server.Address`	The server address/public URL of your server.
`Server.EmailProvider`	Determines how Connect sends emails.
`SMTP`	Sends email using an SMTP endpoint.

Warning

If you do not properly configure the Server.Address, then you cannot add users to the server because the account confirmation link requires the Server.Address to be configured. Additionally, some other Connect features are not available without this property defined.

Make changes in the /etc/rstudio-connect/rstudio-connect.gcfg file using the examples below:

File: /etc/rstudio-connect/rstudio-connect.gcfg

[Server]
Address = "https://posit-connect.example.com"
EmailProvider = "SMTP"
SenderEmail = "account@example.com"

[SMTP]
Host = "smtp.example.com"
Port = 587
User = "service-user"
Password = "service-password"

Important

By default, email in Connect is off until you configure it. Posit recommends that you configure email during setup, so that all Connect features are available.

If you choose not to configure email, set Server.EmailProvider = "none" and ensure Server.Address is set. New users can then be confirmed by clicking Add User in the Connect dashboard, which generates a confirmation link to share directly.

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

[Server]
Address = "http://posit-connect.example.com"
EmailProvider = "none"

Save your changes and restart Connect:

Terminal

sudo systemctl restart rstudio-connect

For more information about configuring these properties, see the Editing the Configuration File section.

Authentication

You can configure Connect by customizing the Authentication.Provider property in the /etc/rstudio-connect/rstudio-connect.gcfg file. The Authentication section provides detailed explanations and additional information about configuring authentication in Connect.

Warning

If you do not configure authentication before you log in for the first time, serious problems can occur later. You can change the authentication method later, but the change is difficult. The change can also cause the loss of user content subscriptions and other assets. If you use Connect on a trial basis with Password authentication (not recommended), go to the next step and log in to Connect.

Step 6: Log in and verify configuration

Important

By default, Connect gives administrator privileges to the first user who logs in. After the configuration is complete, an administrator can promote other users to administrators.

Log in:
- Open a web browser and navigate to the public URL that you defined for your Connect server.
- Click Sign Up.
- Populate the fields with the required information, then click Sign Up. Log in to Connect, and the Content List UI displays.
Verify email:
- Click System in the top menu bar. The Info tab opens by default.
- Under Email Settings, click Send Test Email.
- Wait a few moments and then verify that the test email was successfully delivered.
Verify configuration:
- To verify the initial configuration that you applied during the installation, we recommend deploying example content from the Connect Gallery or publishing content to Connect using one of the Publish to Posit Connect How to Guides.
- If a user can publish content to Connect, then you successfully configured Connect.
Verify the deployment with VIP:
- For an automated end-to-end check, use Verified Installation of Posit (VIP), a non-destructive test suite that validates authentication, content deployment, data source connectivity, packages, email, and runtimes against a running deployment.
- Install VIP on a machine that can reach the server. VIP requires uv:
```
Terminal
```
  uv tool install posit-vip vip install
- Run the verification against your deployment, replacing <product-url> with the URL of your Connect server:
```
Terminal
```
  vip verify --connect-url <product-url> --interactive-auth
  The --interactive-auth flag opens a browser so that VIP can complete the login flow through your identity provider. On a server without a display, use --headless-auth instead. Headless authentication drives a username and password login rather than an interactive single sign-on (SSO) session, so you must first export the credentials VIP logs in with:
```
Terminal
```
  export VIP_TEST_USERNAME="<username>" export VIP_TEST_PASSWORD="<password>" vip verify --connect-url <product-url> --headless-auth
- Alternatively, run most checks without a browser by providing an Administrator API key. This mode runs only the tests that authenticate with an API key and skips the tests that require a browser login:
```
Terminal
```
  export VIP_CONNECT_API_KEY="<administrator-api-key>" vip verify --connect-url <product-url> --api-auth
- Review the results. vip verify reports pass or fail for each check in the terminal and writes the results to report/results.json. To render a shareable HTML report of the results, run vip report. This command requires the Quarto CLI:
```
Terminal
```
  vip report
  If any checks fail, the report identifies the failing area so that you can correct the configuration before rolling out the server. VIP is an open-source project; see the VIP documentation for the full list of checks and configuration options.

Step 7: Start using Connect

Congratulations! You have verified that users can log in, deploy content, and view content on the server.

You can enable several more features and configuration options.

Continue to the Initial Configuration section of the documentation for more information.