posit/workbench repository overview

⁠

⁠Posit Workbench container image

This container image provides Workbench⁠, an integrated development environment for data science teams that supports R, Python, and VS Code.

⁠Related images

For Kubernetes deployments, Workbench uses these images together. See the repository README⁠ for Helm configuration.

⁠Quick reference

⁠How to use this image

⁠Quick start

PWB_VERSION="latest"  # or a specific version like "2026.08.2"
PWB_IMAGE="ghcr.io/posit-dev/workbench"  # or docker.io/posit/workbench
PWB_LICENSE_FILE_HOST_PATH="/path/to/license.lic"
PWB_LICENSE_FILE_PATH="/etc/rstudio-server/license.lic"  # this is the default path for the `PWB_LICENSE_FILE_PATH` container environment variable, included for illustrative purposes
PWB_DATA_STORAGE_HOST_PATH="/path/to/data"
PWB_HOME_STORAGE_HOST_PATH="/path/to/home"
docker run -d \
  --name workbench \
  -p 8787:8787 \
  -e PWB_TESTUSER=posit \
  -e PWB_TESTUSER_PASSWD=posit \
  -e PWB_LICENSE_FILE_PATH=${PWB_LICENSE_FILE_PATH} \
  -v ${PWB_LICENSE_FILE_HOST_PATH}:${PWB_LICENSE_FILE_PATH} \
  -v ${PWB_DATA_STORAGE_HOST_PATH}:/var/lib/rstudio-server \
  -v ${PWB_HOME_STORAGE_HOST_PATH}:/home \
  ${PWB_IMAGE}:${PWB_VERSION}

Access Workbench at http://localhost:8787. Log in with username posit and password posit.

⁠With a custom configuration file

PWB_VERSION="latest"  # or a specific version like "2026.08.2"
PWB_IMAGE="ghcr.io/posit-dev/workbench"  # or docker.io/posit/workbench
PWB_LICENSE_FILE_HOST_PATH="/path/to/license.lic"
PWB_CONFIG_HOST_PATH="/path/to/rstudio"
docker run -d \
  --name workbench \
  -p 8787:8787 \
  -v ${PWB_LICENSE_FILE_HOST_PATH}:/etc/rstudio-server/license.lic \
  -v ${PWB_CONFIG_HOST_PATH}:/etc/rstudio:ro \
  ${PWB_IMAGE}:${PWB_VERSION}

⁠With Docker Compose

services:
  workbench:
    image: docker.io/posit/workbench:latest  # or ghcr.io/posit-dev/workbench:latest
    ports:
    - "8787:8787"
    environment:
      PWB_TESTUSER: posit
      PWB_TESTUSER_PASSWD: posit
    volumes:
    - /path/to/license.lic:/etc/rstudio-server/license.lic
    - /path/to/rstudio:/etc/rstudio:ro
    - workbench-home:/home
    - workbench-shared:/var/lib/rstudio-server
    restart: unless-stopped

volumes:
  workbench-home:
  workbench-shared:

⁠Image variants

Two variants are available:

Each tagged image bundles a fixed set of dependencies. Both variants ship the YYYY.MM release of Workbench at the latest patch release available when the image was built. The std variant additionally ships one R version and one Python version, locked to the latest available at build time. The Containerfiles in this repository under workbench/<version>/ document the exact versions in any tag. No arguments are overridden at build time.

See server extending examples⁠ for how to build on the Minimal image.

⁠Image tags

Posit publishes images to:

• Docker Hub: docker.io/posit/workbench
• GitHub Container Registry: ghcr.io/posit-dev/workbench

Ubuntu 24.04 is the default OS. Ubuntu 26.04 is also supported for the latest version.

Tag formats where YYYY.MM.P is any supported Workbench version:

• YYYY.MM.P - Latest OS, standard variant
• YYYY.MM.P-ubuntu-24.04 - Explicit OS, standard variant
• YYYY.MM.P-ubuntu-24.04-std - Explicit OS and variant
• YYYY.MM.P-ubuntu-24.04-min - Minimal variant
• YYYY.MM.P-ubuntu-26.04 - Ubuntu 26.04 (latest version only)
• latest - Latest version, default OS, standard variant

⁠Architectures

Posit publishes Workbench images for linux/amd64 only. linux/arm64 builds remain in developer preview until Workbench supports ARM in production.

⁠Environment variables

If you are migrating from rstudio/rstudio-workbench, see Environment variables⁠ under the migration guide for the legacy RSW_ names and deprecation timeline.

⁠Exposed ports

⁠Volumes

For persistent data, add these volume mounts to your docker run command:

-v /data/workbench-home:/home \
-v /data/rstudio-server:/var/lib/rstudio-server \
-v /data/rstudio-server-config:/etc/rstudio

⁠Configuration

⁠License activation

Workbench requires a product license⁠. If you don't have a license yet, request a free 30-day trial at posit.co/trial-license⁠.

Posit recommends activating with a license file. Choose one method:

⁠Option 1: License file (recommended)

Mount the license file to any path in the container and set PWB_LICENSE_FILE_PATH to that path. The default search path is /etc/rstudio-server/license.lic, so mounting to that path does not require setting the environment variable. The environment variable is only included for illustrative purposes below.

docker run -v /path/to/license.lic:/etc/rstudio-server/license.lic -e PWB_LICENSE_FILE_PATH=/etc/rstudio-server/license.lic ...

To ensure correct permissions on the license file, set the owner and mode on the host before mounting:

sudo chown 999:999 /path/to/license.lic
sudo chmod 0600 /path/to/license.lic

If the license file does not successfully activate, the container fails to start under most circumstances. See the Licensing FAQ⁠ for usage and troubleshooting information.

⁠Option 2: License key

docker run -e PWB_LICENSE="your-license-key" ...

License key activations can leak when a container shuts down ungracefully, consuming an activation slot that cannot be recovered through normal means. To help preserve license state across container restarts, mount these directories to persistent storage:

• /var/lib/.local
• /var/lib/.prof
• /var/lib/rstudio-workbench

The license manager hardware-locks these state files to a single host; they do not transfer between machines. Mounting these paths reduces the chance of a leak but does not eliminate it. To avoid the leak risk entirely, use a license file (Option 1). See the License keys⁠ caveat for more detail.

⁠Option 3: Floating license server

docker run -e PWB_LICENSE_SERVER="http://license-server:8989" ...

Floating license activations can also leak on ungraceful shutdown. To help preserve license state across container restarts, mount this directory to persistent storage:

• /var/lib/.TurboFloat

State files are hardware-locked and not transferable between hosts. To avoid the leak risk entirely, use a license file (Option 1).

⁠User provisioning

By default, Workbench creates a test user controlled by the PWB_TESTUSER, PWB_TESTUSER_PASSWD, and PWB_TESTUSER_UID environment variables. If PWB_TESTUSER is empty, no test user is created.

⁠LDAP, Active Directory, and sssd

The image installs sssd and starts it by default with a placeholder configuration. To provision users from a directory (LDAP server, Active Directory, etc.), mount your own configuration file into /etc/sssd/conf.d/.

Example sssd.conf:

[sssd]
config_file_version = 2
domains = LDAP

[domain/LDAP]
id_provider = ldap
auth_provider = ldap
chpass_provider = ldap
sudo_provider = ldap
# ... more configuration

Then run the container with the configuration mounted:

# sssd requires strict file permissions
chmod 600 sssd.conf

docker run -d \
  -p 8787:8787 -p 5559:5559 \
  -v /path/to/license.lic:/etc/rstudio-server/license.lic \
  -v $PWD/sssd.conf:/etc/sssd/conf.d/sssd.conf \
  ghcr.io/posit-dev/workbench:latest

For custom authentication or session behavior with PAM, you might also need to modify the PAM configuration files in the container. See the Workbench admin guide⁠ for more information.

To disable sssd entirely, set PWB_SSSD=false. sssd requires root, so it is also skipped automatically when the container runs as a non-root user.

⁠Custom configuration

Mount a custom configuration directory or file:

docker run -v /path/to/rstudio:/etc/rstudio ...

Or mount a single file:

docker run -v /path/to/rserver.conf:/etc/rstudio/rserver.conf ...

Changes take effect when the container is restarted. See the configuration documentation⁠ for available options.

If you replace rserver.conf with your own file, keep server-health-check-enabled=1 so the health check⁠ endpoint works.

⁠Health check

The image declares a Docker HEALTHCHECK⁠ that polls the Workbench /health-check endpoint:

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -fsS http://localhost:8787/health-check || exit 1

The endpoint requires server-health-check-enabled=1 in rserver.conf. The bundled configuration sets this by default, so no action is required unless you mount your own rserver.conf.

When the container is healthy, docker ps reports healthy in the status column and the endpoint returns 200 OK with a plain-text dump of server diagnostics. To inspect the response directly:

docker exec <container> curl -fsS http://localhost:8787/health-check

To disable the built-in health check, run the container with --no-healthcheck or override it in your orchestrator.

⁠Process management

Workbench runs several services inside the container under supervisord⁠. supervisord exits the container if any required service exits, so the container fails fast on startup errors.

The image manages these services:

• Workbench: the main server process. The startup configuration mounts at /startup/base.
• Job Launcher: enables Positron, RStudio, JupyterLab, and VS Code sessions, as well as integration with job schedulers like Slurm and Kubernetes. Enabled by default. The startup configuration mounts at /startup/launcher. To disable, mount an empty volume over /startup/launcher.
• sssd: provides user provisioning when connected to an LDAP directory or other user store. Enabled by default with a placeholder domain that does nothing. To use your own directory, mount required .conf files into /etc/sssd/conf.d/ (see User provisioning⁠). To disable entirely, set PWB_SSSD=false or mount an empty volume over /startup/user-provisioning/.
• custom: to run additional services inside the container, mount supervisord configuration files into /startup/custom/. supervisord starts and manages them alongside the built-in services. In Kubernetes, initContainers or sidecar containers are often a better fit.

⁠User

The container starts as root and Workbench drops privileges to the rstudio-server user (UID and GID 999) for the server process.

⁠Examples

⁠Running with persistent home directories and configuration

docker run -d \
  --name workbench \
  -p 8787:8787 -p 5559:5559 \
  -v /data/workbench-home:/home \
  -v /path/to/rstudio:/etc/rstudio \
  -v /path/to/license.lic:/etc/rstudio-server/license.lic \
  -e PWB_TESTUSER=posit \
  -e PWB_TESTUSER_PASSWD=posit \
  ghcr.io/posit-dev/workbench:latest

Open http://localhost:8787 and log in as posit.

⁠Migrating from legacy image

This image replaces the legacy rstudio/rstudio-workbench⁠ image. Workbench itself is unchanged. The application reads /etc/rstudio/rserver.conf, listens on 8787, runs the Job Launcher on 5559, and runs as the rstudio-server user (UID/GID 999). Data and configuration volume mount points are unchanged. The differences are in how the image is published and configured.

⁠Image references

The legacy image was published as rstudio/rstudio-workbench on Docker Hub and ghcr.io/rstudio/rstudio-docker-products/rstudio-workbench on GHCR, tagged by OS (jammy, ubuntu2204, jammy-<version>, ubuntu2204-<version>) for linux/amd64 only. Update your image reference to one of the new locations and pick a tag that pins to your desired Workbench version, OS, and variant. See Image tags⁠ and Architectures⁠.

⁠Variants

The legacy image shipped a single variant containing two versions of R and two versions of Python alongside many extraneous system packages. The Standard (std) variant is closest to the legacy image; the Minimal (min) variant has no equivalent. See Image variants⁠ for what each includes.

⁠Environment variables

License, launcher, and test user environment variables use the PWB_ prefix:

The image accepts the legacy RSW_ names as a fallback.

⁠Privileged mode

The legacy image documented docker run --privileged for some examples. This image does not require --privileged.

⁠What did not change

• Application port (8787)
• Job Launcher port (5559)
• Configuration directory (/etc/rstudio)
• License file default path (/etc/rstudio-server/license.lic)
• Service user (rstudio-server, UID/GID 999)
• Process management with supervisord and the /startup/{base,launcher,user-provisioning,custom} mount points

⁠Caveats

⁠Security

Review these images before using them in production. Organizations with specific Common Vulnerabilities and Exposures (CVE) or vulnerability requirements can rebuild these images to meet their security standards.

Posit rebuilds published images weekly for Posit product editions under active support to pull in operating system patches.

⁠License keys

License keys used in containers risk activation slot loss if the container does not shut down gracefully. The license deactivates on container exit, but ungraceful shutdowns (crashes, docker kill) can leave the activation slot consumed on the Posit license server.

To ensure proper license deactivation, use a sufficient stop timeout for both docker run and docker stop:

docker run -d --stop-timeout 120 -e PWB_LICENSE="your-license-key" ...
docker stop --time 120 <container>

For production deployments, use license files rather than license keys.

⁠Hardware locking

Workbench hardware-locks license state files to a specific machine. Changes to MAC addresses, hostnames, or container orchestration platforms, such as Kubernetes, can invalidate the license state, requiring reactivation. See License activation⁠ for the directories to mount for each license type.

Gracefully shut down containers and allow license deactivation before changing host hardware or firmware (for example, upgrading a network card or updating BIOS). Apply the same caution before changing container resources (for example, the network driver or allocated CPU cores).