Lab 1 – Install Posit Connect and R

In this first hands-on lab, you will set up a minimal installation of Posit Connect. In this first lab, you will:

  1. install Posit Connect
  2. install R
  3. activate the license
  4. configure Connect

At that point, Connect will run but will not be ready to render most of the content that your users may create (in particular, Python and Quarto will not be installed). You will take care of these steps in the next lab. The following labs will teach you how to secure your installation by setting up HTTPS and integrating Connect into an authentication system.

NoteTimings for this chapter
  • Reading time: 15 minutes
  • Documentation reading time: 30-50 minutes
  • Hands-on exercise time: 30-50 minutes
TipRequired Reading

  • Read this section on Server installation.

  • Read this section on installing R. Note that this section is not part of the Posit Connect Admin Guide but is the recommended guide to install R across all Posit Products. Read also the Overview section about how to configure Connect to interact with the R executables present on the system.

  • License Management. Note that there are only rare cases where you will want to use a license key instead of a license file to activate your installation. If you use a license file, you won’t need to worry about Floating Licensing.

1. Install Posit Connect

Install version 2025.11.0 of Posit Connect using the following commands in the terminal:

Terminal
## Set up the repository from which Posit Connect will be installed.
curl -1sLf   'https://dl.posit.co/public/pro/setup.deb.sh'   | sudo -E bash

## Install Posit Connect 2025.11.0
sudo apt install rstudio-connect=2025.11.0

## Prevent Posit Connect from unintended upgrades during routine system maintenance.
sudo apt-mark hold rstudio-connect

Posit Connect gets installed in /opt/rstudio-connect/. The bin/ folder contains the executables. You can check if the installation was successful by running:

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

which should produce the following output:

Version: 20XX.YY.ZZ
Build: v20XX.YY.ZZ-W-abcedf1234
TipWhat is the version of the latest release of Posit Connect?

To determine the version of the latest release of Posit Connect, you can navigate to the landing page of the Posit Connect documentation. It displays the version number. Clicking on “Previous Versions” card brings you to a page with all currently supported versions, their associated documentation, release notes, and links to their installers.

To check if Connect is running, you can use the systemd command (type q on your keyboard to go back to the shell prompt):

sudo systemctl status rstudio-connect.service
× rstudio-connect.service - Posit Connect
     Loaded: loaded (/usr/lib/systemd/system/rstudio-connect.service; enabled; preset: enabled)
     Active: failed (Result: exit-code) since Fri 2025-12-05 09:16:45 UTC; 1min 13s ago
   Duration: 430ms
    Process: 3209 ExecStart=/opt/rstudio-connect/bin/connect --config /etc/rstudio-connect/rstud>
   Main PID: 3209 (code=exited, status=1/FAILURE)
        CPU: 206ms

Dec 05 09:16:45 connect-vm systemd[1]: rstudio-connect.service: Main process exited, code=exited>
Dec 05 09:16:45 connect-vm systemd[1]: rstudio-connect.service: Failed with result 'exit-code'.
Dec 05 09:16:45 connect-vm systemd[1]: rstudio-connect.service: Scheduled restart job, restart c>
Dec 05 09:16:45 connect-vm systemd[1]: rstudio-connect.service: Start request repeated too quick>
Dec 05 09:16:45 connect-vm systemd[1]: rstudio-connect.service: Failed with result 'exit-code'.
Dec 05 09:16:45 connect-vm systemd[1]: Failed to start rstudio-connect.service - Posit Connect.

For now, Connect is not running as it fails to start. Let’s inspect the logs to understand why. The logs for Connect are located in /var/log/rstudio/rstudio-connect/, with rstudio-connect.log being the application log. Let’s inspect the end of this file:

sudo tail /var/log/rstudio/rstudio-connect/rstudio-connect.log 
time="2025-12-05T09:16:44.988Z" level=info msg="Configuration task: Python environment cache visibility: complete"
time="2025-12-05T09:16:44.988Z" level=info msg="Configuration task: Git repository cache visibility: starting"
time="2025-12-05T09:16:44.988Z" level=info msg="Configuration task: Git repository cache visibility: complete"
time="2025-12-05T09:16:44.988Z" level=info msg="Configuration tasks: complete"
time="2025-12-05T09:16:44.988Z" level=info msg="Resource limits: {\"nofile\":{\"soft\":1000000,\"hard\":1000000}}"
time="2025-12-05T09:16:44.990Z" level=info msg="Configuring licensing to use a local license..."
time="2025-12-05T09:16:45.052Z" level=warning msg="Unable to obtain a valid license: Your Posit Connect license has expired. Please contact your dedicated Posit Customer Success contact or email sales@posit.co to obtain a current license."
time="2025-12-05T09:16:45.052Z" level=info msg="Running startup tasks using rsandbox."
time="2025-12-05T09:16:45.133Z" level=info msg="Python support is disabled"
time="2025-12-05T09:16:45.133Z" level=fatal msg="Error: Unable to configure execution environments: unable to initialize local environment: Unable to use R on this system: Could not locate an R installation"

The logs point to two issues:

  • one with a 'warning' level indicating that the license is expired;
  • one with a 'fatal' level indicating that R cannot be located.

Let’s start with installing R.

TipTroubleshooting

In some cases, especially if there are parsing issues with your configuration file, you may have to look at the logs from systemd for the Connect service. To get the logs from the last 5 minutes, you can use:

sudo journalctl -u rstudio-connect.service --since "5 min ago"

Configuration file syntax errors occur before Connect can initialize its file-based logging, so journalctl is the only place to find them. Once Connect successfully parses the config and initializes logging, they will also appear in /var/log/rstudio/rstudio-connect/rstudio-connect.log.

2. Install R

Use the instructions in the documentation to install the latest version of R version. When setting up your own installation, you will want to consult with the data scientists in your team to ensure that you install the versions (they will most likely need more than one version), required for their content.

NoteWhat is the latest version of R?

The Posit Install R documents are usually up to date, but should be checked against the CRAN Release Notes to make sure you’re providing customers the latest version of R.

The first line in this script specifies which version of R to install.

export R_VERSION=4.5.2
curl -O https://cdn.posit.co/r/ubuntu-2404/pkgs/r-${R_VERSION}_1_$(dpkg --print-architecture).deb
sudo apt-get update
sudo apt-get install ./r-${R_VERSION}_1_$(dpkg --print-architecture).deb

The installers that Posit provides for R, put the files required in /opt and allow you to install multiple versions side-by-side. You can check that R is correctly installed by running:

/opt/R/4.5.2/bin/R --version

which should produce the following output:

R version 4.5.2 (2025-10-31) -- "[Not] Part in a Rumble"
Copyright (C) 2025 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under the terms of the
GNU General Public License versions 2 or 3.
For more information about these matters see
https://www.gnu.org/licenses/.

Let’s restart Posit Connect by running:

sudo systemctl restart rstudio-connect

and let’s check the status of the service:

sudo systemctl status rstudio-connect.service

Posit Connect is now running, but not configured. It only uses default configuration values. If you navigate to the “Posit Connect” tab, you will see an error message indicating that the “Trial has ended” because there is no active license associated with the installation. Let’s take care of this.

3. Activate your License

We provide you with a license file for the purpose of this training, located in the home folder of your virtual machine (/home/ubuntu/<license-file>.lic). Follow the instructions in the documentation to use this license file to activate your installation.

You can determine the current license status with the following command:

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

After restarting Posit Connect, check that it is running as expected by checking the output of sudo systemctl status rstudio-connect.service. Click on the circular arrow icon on the tab “Posit Connect” in Instruqt to reload the content and check that Connect now loads.

4. Configure Posit Connect

Let’s now configure Posit Connect. We will only do a basic configuration for this exercise, and we will add more to it during the next labs.

The configuration file for Posit Connect is located at /etc/rstudio-connect/rstudio-connect.gcfg.

To explore the full list of options that can be configured, you can refer to the official documentation at https://docs.posit.co/connect/admin/appendix/configuration/.

For the purpose of this exercise, you will not set up a mailing system to send notifications to users. Instead, you will rely on a setting that prints emails to the console, by setting EmailProvider = "print". However, when you install Posit Connect on your system, we strongly recommend configuring it correctly from the start so all Connect features are available right away.

Within the Instruqt platform, you can get the URL of the Posit Connect instance using the environment variables $HOSTNAME and $_SANDBOX_ID. By default, Posit Connect is available on port 3939. You can get the URL at which your Posit Connect installation will be served with this command (note that the URL is also visible in the “Instructions” panel in the bottom right of the Instruqt interface):

echo http://$HOSTNAME.$_SANDBOX_ID.instruqt.io

For now, you will start with using passwords to authenticate users. However, when you install Posit Connect on your system, we suggest you configure Connect to use the Authentication system you intend to use in production from the start to avoid any issues down the road.

While R is enabled by default in Posit Connect, you will explicitly enable it and specify the path of the R executable. This ensures that R is properly configured, and will allow you to use and manage multiple versions of R in our Connect installation. By default, Connect scans the system to detect R installations. Here we disable scanning (using the R.ExecutableScanning setting) to have complete control over the R versions in use.

Then, use nano (or vi) with sudo, to edit the configuration file. The full rstudio-connect.gcfg file should look like this (use the actual values of the environment variables for your virtual machine for the Server.Address value):

[Server]
Address = "http://${HOSTNAME}.${_SANDBOX_ID}.instruqt.io/"
EmailProvider = "print"

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

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

[R]
Enabled = true
ExecutableScanning = false
Executable = "/opt/R/4.5.2/bin/R"

Once you have edited the configuration file, you will need to restart Posit Connect for the changes to take effect:

sudo systemctl restart rstudio-connect

You can now visit the “Posit Connect” tab to check that your installation is up and running, and click on the “Check” button to confirm that you have set up everything correctly.

The “Check” button in Instruqt to check that you completed all the tasks in the assignment

Check Your Understanding

Before proceeding to the next lab, make sure you can answer these questions:

  1. Troubleshooting: How can you check from the command line that Posit Connect is running? Where would you look at logs to check if there are any issues?

  2. License Management: What command would you use to check the current license status of your Posit Connect installation?

  3. R Configuration: In the configuration file, why did we set R.ExecutableScanning = false and explicitly specify the R executable path instead of letting Connect automatically detect R installations?

1. Troubleshooting

You can check that Posit Connect is running with:

sudo systemctl status rstudio-connect.service

The main application logs is located in /var/log/rstudio/rstudio-connect/rstudio-connect.log. You can inspect the 50 most recent log entries with:

sudo tail -50 /var/log/rstudio/rstudio-connect/rstudio-connect.log

2. License Management

You can check the status of your license with:

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

3. R Configuration

Setting R.ExecutableScanning = false and explicitly specifying the R executable path provides complete control over which R versions are available in the Connect installation. This approach:

  • Prevents Connect from automatically detecting and using unintended R installations on the system
  • Ensures predictable behavior and consistent R version management
  • Allows administrators to precisely control which R versions users can access
  • Facilitates managing multiple R versions side-by-side in a controlled manner

By disabling automatic scanning, you avoid potential issues with Connect finding and using R installations that may not be properly configured or intended for production use.

ImportantPlanning your Posit Connect Installation
  • Which version(s) of R will your end users need?