Lab 1 – Install Posit Workbench
1 Learning Objectives
By the end of this lab, you will be able to:
- Install and configure interpreters and tools for Workbench (R, Python, Quarto, and Posit Professional ODBC Drivers)
- Install and activate Workbench using a license file
- Verify a Workbench installation using built-in utilities
- Troubleshoot Workbench issues using logs and system commands
- Access and test multiple integrated development environments (IDEs) (Positron, VS Code, RStudio Pro) through the Workbench interface
2 Introduction
In this first hands-on lab, you will set up a minimal installation of Workbench. This foundational lab walks you through the complete installation process, from installing the interpreters and tools (R, Python, Quarto, and Professional Drivers) Workbench needs, to activating your Workbench license and verifying that all major IDEs work correctly.
By the end of this lab, you will have a functioning Workbench server with multiple IDE options available to users, including Positron, RStudio Pro, VS Code, and JupyterLab. You will use Pluggable Authentication Module (PAM) authentication with a single test user to verify the installation.
This lab provides the foundation for subsequent modules where you will explore more advanced configuration options, authentication mechanisms, and administrative tasks. Understanding the basic installation process is essential for troubleshooting issues that might arise in production deployments.
- Reading time: 15 minutes
- Documentation reading time: 30-50 minutes
- Hands-on exercise time: 45-75 minutes
As a system administrator, understanding the complete installation process for Workbench is critical for several reasons:
- Troubleshooting: When users report issues, knowing how each component was installed helps you diagnose problems faster
- Upgrades: Future version upgrades will follow similar patterns; this foundation helps you plan maintenance windows
- User Support: Data scientists will ask about available R and Python versions, IDE options, and package installations. Know how these are configured.
- Runtimes: Understanding the relationship between R, Python, Quarto, and Workbench prevents common configuration errors
3 Installing Runtime Interpreters and Tools
3.1 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.
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).debThe 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 --versionwhich 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/.In addition to the latest R version, also install R 4.4.3.
Workbench allows users to switch between multiple R versions. This is essential in production environments where different projects may require different R versions for compatibility. In this lab, you will install two R versions: a current release and R 4.4.3, to practice managing multiple versions.
3.2 Install Python
Review the “Installing Python” section in the Admin Guide.
Using the Python installation guide, complete the following steps:
- install
uv - install Python 3.13.10
- install Python 3.14.1
## Install uv (only needed once)
curl -LsSf https://astral.sh/uv/install.sh | sudo env UV_INSTALL_DIR=/usr/local/bin sh
## Configure the Python version you want to install (repeat this step and the steps below for each version you want to install)
export PYTHON_VERSION="3.13.10"
## Install the specified Python version
sudo /usr/local/bin/uv python install "${PYTHON_VERSION}" --install-dir=/opt/python
sudo ln -s /opt/python/cpython-$PYTHON_VERSION-* /opt/python/$PYTHON_VERSION
## Verify the installation
/opt/python/"${PYTHON_VERSION}"/bin/python --version/root/.local/bin not being in your $PATH
When installing different versions of Python using uv, a warning message will be displayed:
warning: `/root/.local/bin` is not on your PATH. To use installed Python executables, run `export PATH="/root/.local/bin:$PATH"` or `uv python update-shell`This warning can be safely ignored in the context of a Posit Connect installation. By default, uv creates links in /root/.local/bin to the Python executables installed (in /opt/python/ in our case). This is useful if you want to call Python directly from the command line. However, Posit Connect uses the paths specified in its configuration file to find the Python executables, so having /root/.local/bin in your $PATH is not necessary. You can disable the creation of these links, and the associated warning by adding the --no-bin flag to the installation command.
The latest version of Python should be checked against the Python.org to make sure you are providing your users the latest version of Python that isn’t in pre-release status. Always install the latest patch version of these major.minor versions. The latest patch version generally includes the most bugfixes and security patches.
3.3 Install Quarto
Using the Quarto Installation Guide, install the latest version of Quarto.
To identify Quarto’s latest version, you can visit the Get Started page on the Quarto website, which lists download links for the different platforms and includes the version number. Alternatively, you can find all releases (including pre-releases) on GitHub.
To use Quarto with Positron, VS Code, or JupyterLab, it must be available in the PATH. You can add the Quarto installation location to the PATH or create a symlink in /usr/local/bin. This lab uses the symlink approach:
Terminal
sudo ln -s /opt/quarto/${QUARTO_VERSION}/bin/quarto /usr/local/bin/quarto3.4 Install the Posit Professional Drivers
Using instructions found in the Pro Drivers Installation Guide, install the Posit Professional ODBC Drivers.
4 Installing and Configuring Workbench
4.1 Install Workbench
Using the instructions found in the Workbench Admin Guide, download and install it. Given that you already installed R and Python, you can proceed directly to Step 2 in the documentation. Download the installer for version 2026.01.1 to the /tmp directory and install it from there1. For example, run the following commands:
Terminal
curl --output-dir /tmp -O https://download2.rstudio.org/server/jammy/amd64/rstudio-workbench-2026.01.1-amd64.deb
sudo apt-get install /tmp/rstudio-workbench-2026.01.1-amd64.debTo verify the installation, create a test user with the user name posit_admin and password posit_admin.
Terminal
export USERNAME=posit_admin
export PASSWORD=posit_admin
sudo useradd --create-home --home-dir /home/posit_admin -s /bin/bash $USERNAME;
echo -e "$PASSWORD\n$PASSWORD" | sudo passwd $USERNAME;4.2 Activate your license
A license file for Workbench is available in the home directory of the ubuntu user.
Follow the instructions in the documentation to use this license file to activate your installation.
You can determine the license status with the following command:
Terminal
sudo /usr/sbin/rstudio-server license-manager statusAfter restarting Workbench, check that it is running as expected by checking the output of sudo systemctl status rstudio-server.service.
Workbench relies on two different, semi-independent, services for its operation: rstudio-server and rstudio-launcher. Each of these services can be restarted and reloaded independently and logs separately. The command below works to restart these services in the “right” order so that no errors are recorded in the application logs. Other restart orders might work, but they will generate transient errors into the rstudio-server logs.
Terminal
sudo /usr/sbin/rstudio-server stop && \
sudo /usr/bin/rstudio-launcher stop && \
sudo /usr/bin/rstudio-launcher start && \
sudo /usr/sbin/rstudio-server start && sleep 2 && \
sudo systemctl --no-pager -l status rstudio-server.service && \
sudo systemctl --no-pager -l status rstudio-launcher.serviceThis command also shows the systemctl status output for both services so you can confirm they are running. You can create a bash alias to make it easier to restart Workbench correctly:
Terminal
alias restart="sudo /usr/sbin/rstudio-server stop && sudo /usr/bin/rstudio-launcher stop && sudo /usr/bin/rstudio-launcher start && sudo /usr/sbin/rstudio-server start"4.3 Install JupyterLab (optional)
Follow the instructions listed in the Admin Guide to install JupyterLab using the most recent version of Python you have installed. For instance, if you installed Python 3.14.1, set the environment variable and run:
Terminal
# Set the Python version if not already set
export PYTHON_VERSION=3.14.1
sudo /opt/python/${PYTHON_VERSION}/bin/pip install jupyterlab==4.2.5 notebook pwb_jupyterlab~=1.1 ipykernel --break-system-packages --root-user-action=ignore
## Register the kernel with JupyterLab so that it shows up as an option when launching a new session
sudo /opt/python/${PYTHON_VERSION}/bin/python -m ipykernel install --name py${PYTHON_VERSION} --display-name "Python ${PYTHON_VERSION}"--break-system-packages flag
You might need to add the --break-system-packages flag when using pip to install packages globally for all users. This flag is necessary because pip will not allow global installations if it detects potential interference with the system’s package manager. For Workbench deployments where packages must be available system-wide, this flag tells pip to proceed with the installation.
The --root-user-action=ignore flag is also recommended when running pip as root to prevent warnings about running pip with elevated privileges. This is common in Workbench installations where global package availability is required.
Update the /etc/rstudio/jupyter.conf file to point to the correct JupyterLab installation path. For instance, if you installed JupyterLab in /opt/python/3.14.1, the configuration file should look like this:
/etc/rstudio/jupyter.conf
jupyter-exe=/opt/python/3.14.1/bin/jupyter
labs-enabled=1
default-session-cluster=LocalYour JupyterLab installation is functional. Users can only use Python 3.14.1 until you add more kernels. To support other Python versions, install the ipykernel package for each version and register its kernel. For instance, if you also have Python 3.13.10 installed, you can run:
Terminal
export PYTHON_VERSION=3.13.10
sudo /opt/python/${PYTHON_VERSION}/bin/pip install ipykernel --break-system-packages --root-user-action=ignore
sudo /opt/python/${PYTHON_VERSION}/bin/python -m ipykernel install --name py${PYTHON_VERSION} --display-name "Python ${PYTHON_VERSION}"5 Testing and Validation
5.1 Verify Installation
Now that you have installed and activated Workbench, verify that both the rstudio-server and rstudio-launcher services show ‘active (running)’ status:
Terminal
sudo systemctl status rstudio-server.service
sudo systemctl status rstudio-launcher.serviceThere will be additional output. Verify that both the Server and Launcher services show active (running) status:
Terminal
● rstudio-server.service - RStudio Server
Loaded: loaded (/usr/lib/systemd/system/rstudio-server.service; enabled; preset: enabled)
Active: active (running) since Fri 2026-01-23 15:14:23 UTC; 2s ago
.....
● rstudio-launcher.service - RStudio Launcher
Loaded: loaded (/usr/lib/systemd/system/rstudio-launcher.service; enabled; preset: enabled)
Active: active (running) since Fri 2026-01-23 15:09:03 UTC; 5min ago5.2 Test the Web Interface
Access the Workbench web interface by clicking the “Posit Workbench” tab at the top of your screen. Log in with the username and password you created above (username posit_admin, password posit_admin), and verify that you can see Positron, VSCode, RStudio Pro, and JupyterLab in the list of IDEs.
- Launch a Positron session, and verify that you can start the R and Python interpreters for the versions you installed above.
- Launch a RStudio Pro session to check that it starts correctly and that R is working as expected.
- Launch a JupyterLab session and make sure that both Python 3.14.1 and Python 3.13.10 kernels are available.
- Launch a VS Code session and verify that you can open a terminal and start R and Python from there.
5.3 Understanding Workbench Logs
By default, logs for rstudio-server and rstudio-launcher are available in /var/log/rstudio/rstudio-server and /var/log/rstudio/launcher. Additional logs per users are available in ~/.local/share/rstudio/log.
The logging section of the Workbench Admin Guide has more details, and information on how to configure logging.
6 Check your understanding
Before proceeding to the next lab, make sure you can answer these questions:
Troubleshooting: How can you check from the command line that Workbench is running? Where would you look at logs to check if there are any issues?
R, Python, and Quarto: What command would you use to check what versions of these languages are installed and available? Where on disk do these tools install by default? Why does Posit not recommend installing R, Python, or Quarto using your Linux distribution’s package manager for Workbench deployments? What is the recommended approach instead?
Workbench: What port is Workbench listening on?
6.1 Question 1
To check if Workbench is running from the command line, use:
Terminal
sudo systemctl status rstudio-server.service
sudo systemctl status rstudio-launcher.serviceBoth services must show active (running) status. You can also use:
Terminal
ps aux | grep rstudioView logs with:
Terminal
sudo tail -f /var/log/rstudio/rstudio-server/rserver.log
sudo tail -f /var/log/rstudio/launcher/launcher.log6.2 Question 2
When using the installation instructions Posit provides, R, Python, and Quarto will be installed in /opt/. To identify the versions installed on your system you can use something like:
Terminal
ls -1d /opt/R/*to list the different versions of R you might have installed. For instance, if you have version 4.4.3 installed, you can run:
Terminal
/opt/R/4.4.3/bin/R --versionPosit does not recommend using Linux distribution package managers (apt, yum, etc.) for Workbench deployments because:
- Version control: Package managers might not have the specific versions needed for production
- Consistency: Different distributions have different versions, making deployments inconsistent
- Multiple versions: Workbench often needs multiple R versions available simultaneously, which package managers do not support
Use the Posit-recommended approach for installing these tools. This ensures you have controlled, supported versions installed in /opt/ with proper isolation from system packages.
6.3 Question 3
Workbench listens on port 8787 by default.
Footnotes
We download and install Workbench from the
/tmpdirectory to avoid a confusing message that appears when installing a deb archive from the home directory.↩︎