Installation Overview

By the end of this lesson, you will be able to:

  • Describe the steps required for a functional single-server installation of Posit Workbench
  • Explain why Workbench needs interpreters such as R, Python, and Quarto installed before users can start sessions
  • Identify the configuration files and logs Workbench uses on a Linux system
  • Describe how the rstudio-server and rstudio-launcher services work together

1 Introduction

In the introduction chapter, you learned how Workbench is organized: the rserver process handles authentication and session management, the Session Launcher starts IDE sessions, and users work in Positron, RStudio Pro, VS Code, or JupyterLab sessions. Before diving into the hands-on installation lab, this lesson provides a high-level overview of what you will install and how the labs in this chapter are organized.

For this training, we install Posit Workbench on a single server running Ubuntu 24.04. These steps give you an overview of what is required to get a functional Workbench installation on your own infrastructure. We don’t cover every feature Workbench offers in this training. Refer to the Admin Guide to configure other features your team is interested in.

2 The Road Map for This Chapter

A complete installation proceeds through the following steps:

  1. Install the interpreters and tools: Workbench sessions need R, Python, and Quarto on the server, and the Posit Professional ODBC Drivers let users connect to databases.
  2. Install Posit Workbench: Posit distributes Workbench as a Linux package for supported distributions.
  3. Activate your license: After your purchase is complete, you receive a license file from Posit. In this training, you use the license file we provide to learn how license activation works.
  4. Verify the installation: You confirm that both Workbench services are running, then launch sessions in each IDE to check that the interpreters are available.
  5. Configure SSL: To secure communication with your server, you configure Workbench to use your TLS certificates.
  6. Configure authentication: Workbench integrates with enterprise authentication systems. In this training, you use OpenID Connect (OIDC) with just-in-time provisioning.
  7. Enable the administrative endpoints: The admin dashboard, the health check endpoint, and the Workbench API support monitoring, load balancing, and automation.
  8. Configure resource management: Resource profiles limit the CPU and memory each session can consume, so one user’s workload cannot degrade the server for everyone.

Lab 1 covers steps 1 to 4, Lab 2 covers step 5, Lab 3 covers step 6, Lab 4 covers step 7, and Lab 5 covers step 8.

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

3 What You Will Install

A minimal Workbench installation has a few distinct pieces, and it helps to understand each before you begin.

  • The interpreters and tools. Workbench sessions need R, Python, and Quarto installed on the server. Use the installers Posit provides rather than your Linux distribution’s package manager: users often need multiple versions of R and Python side by side, and the Posit installers place them in /opt/ where Workbench can find and manage them.
  • Posit Workbench. You download and install the Workbench package for your distribution. Pin the version you install so routine system maintenance does not upgrade it without your control.
  • A license. Workbench is a licensed product and must be activated before use. You will use license file activation in this course.
  • A test user. Workbench gives each user their own Linux account and sessions. Before you connect an external authentication system, you create a local test user to verify the installation with PAM authentication.

4 Two Services, One Product

Workbench runs as two semi-independent services. The rstudio-server service handles authentication, the web interface, and session brokering. The rstudio-launcher service starts and manages the session processes. Both must be running for Workbench to work. They log separately and can be restarted independently.

This also means there is a right order to restart them. The lab provides a restart sequence that avoids transient errors in the application logs.

5 Files and Locations You Should Know

Throughout the labs you will edit configuration, inspect logs, and run the command-line tools. It helps to know up front where Workbench places things on a Linux system.

What Path Notes
Configuration files /etc/rstudio/ Workbench uses several configuration files, including rserver.conf, rsession.conf, jupyter.conf, and the launcher resource files. Edit them with sudo, then restart Workbench for changes to take effect.
R installations /opt/R/<version>/ One directory per R version, installed from the binaries Posit provides.
Python installations /opt/python/<version>/ One directory per Python version, installed with uv.
Quarto /opt/quarto/<version>/ Add it to the PATH or symlink it into /usr/local/bin so Positron and VS Code can find it.
Server log /var/log/rstudio/rstudio-server/rserver.log The main Workbench log.
Launcher log /var/log/rstudio/launcher/launcher.log The session launcher log.
Per-user logs ~/.local/share/rstudio/log Logs for each user’s sessions.

Workbench listens on port 8787 by default. For details on each configuration file, see the Admin Guide.

TipWhy is it relevant to me?

As you work through the labs, keep your own installation in mind:

  • Architecture: The labs use a single server, which suits teams of roughly ten users. Larger teams need load balancing, Kubernetes, or Slurm, so review the Reference Architecture Guide before you size your own deployment.
  • Versions: Consult your data science teams about the R, Python, and Quarto versions they need. They will most likely need more than one version of each.
  • System requirements: Review the System Requirements and check that they are acceptable for your infrastructure.

In the accompanying lab, you will install the interpreters and tools, install and license Workbench, and verify that sessions start in every IDE.