Posit Workbench

https://docs.posit.co/ide/server-pro/
Admin
Posit Workbench is a professional, server-based integrated development environment (IDE) designed...
Tokens:337,264
Snippets:3,668
Trust Score:10
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Extension with PWB Code Server Binary

Source: https://docs.posit.co/ide/server-pro/admin/vscode_sessions/pwb_code_server

This example demonstrates how to install a VS Code extension using the PWB Code Server binary. It involves setting an environment variable for the PWB Code Server path and then executing the install command with a specified extensions directory.

```bash
export PWB_CODE_SERVER=/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server
$PWB_CODE_SERVER --extensions-dir=/opt/code-server/extensions --install-extension <your-extension-here>
```

--------------------------------

### Install Posit License Server as a Service (Windows)

Source: https://docs.posit.co/ide/server-pro/admin/license_management/license_management

Command to install and run the Posit License Server as a background service on Windows. This ensures the server starts automatically with the system.

```batch
TurboFloatServer.exe -i
```

--------------------------------

### Install and Activate Posit License Server (Linux)

Source: https://docs.posit.co/ide/server-pro/admin/license_management/license_management

Commands to install the Posit License Server package, activate your product key, and start the server on a Linux system. This enables floating license distribution.

```bash
sudo dpkg -i rsp-license-server-1.1.2-x86_64.deb
sudo rsp-license-server activate <product-key>
sudo rsp-license-server start
```

--------------------------------

### VS Code Session Configuration Example

Source: https://docs.posit.co/ide/server-pro/admin/vscode_sessions/configuration

An example of how to configure VS Code sessions in the `vscode.conf` file. This snippet demonstrates enabling sessions, specifying the code server executable, setting a default cluster, and defining a default container image.

```bash
# /etc/rstudio-server/vscode.conf
exe=/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server
enabled=1
default-session-cluster=Kubernetes
default-session-container-image=rstudio:vscode-session
```

--------------------------------

### Start Posit Workbench Server

Source: https://docs.posit.co/ide/server-pro/admin/server_management/backup_guide

This command is used to start the Posit Workbench server after user state has been restored from a backup. It should be run after the restoration steps are complete.

```bash
sudo rstudio-server start
```

--------------------------------

### Launch Session Example

Source: https://docs.posit.co/ide/server-pro/admin/workbench_api/workbench_api

An example demonstrating how to launch a session using `curl` with the Workbench API.

```APIDOC
## Example: Launch Session

### Description
Demonstrates how to launch a session using the `launch_session` API method via `curl`.

### Method
`POST /api/launch_session`

### Request Example
```bash
#!/bin/bash
method="launch_session"

# Replace with your 32 character API token
apiToken=<api-token-key>

# Replace the username value with a valid user account on the system
# Additional launch_parameters required for other session types.
paramsJson=', "kwparams": {"launch_parameters":{"name":"Test RStudio Session","cluster":"Local"}, "username":"replace-this-user-name"}'

# Replace with your Posit Workbench server URL
workbenchServerUrl="http://localhost:8787"

curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer $apiToken" \
     -d "{\"method\":\"$method\" $paramsJson}" \
     "$workbenchServerUrl/api/$method"
```

### Parameters
- **method** (string) - The API method to call (`launch_session`).
- **kwparams** (object) - Key-value parameters for the method.
  - **launch_parameters** (object) - Parameters for launching the session.
    - **name** (string) - The name of the session.
    - **cluster** (string) - The cluster to launch the session on (e.g., `Local`).
  - **username** (string) - The username for whom to launch the session.

### Headers
- **Content-Type**: `application/json`
- **Authorization**: `Bearer <api-token-key>`

### Response Example (Success)
```json
{
   "result": {
      "session_id": "some_session_id",
      "status": "running"
   }
}
```

### Response Example (Error)
```json
{
   "error": {
      "code": 123,
      "message": "Failed to launch session for user."
   }
}
```
```

--------------------------------

### Run Uvicorn with Dynamic Root Path from Command Line

Source: https://docs.posit.co/ide/server-pro/user/posit-workbench/guide/python

This command-line example illustrates how to start a Uvicorn server with a dynamically generated root path. It uses command substitution `$()` to pass the output of `rserver-url -l 8050` directly to the `--root-path` argument, simplifying configuration.

```bash
uvicorn main:app --port=8050 --root-path=$(rserver-url -l 8050)
```

--------------------------------

### Resource Profile Configuration Example

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/kubernetes_plugin

Example configuration for resource profiles in `/etc/rstudio/launcher.kubernetes.resources.conf`. This file defines presets for CPU, memory, and GPU allocations.

```properties
[default]
name = "Default" # optional, derived from the section name when absent
cpus=1
mem-mb=4096

[small]
cpus=1
mem-mb=512

[default-gpu]
cpus=1
mem-mb=4096
nvidia-gpus=1
amd-gpus=0

[hugemem]
name = "Huge Memory"
cpus=8
mem-mb=262144
```

--------------------------------

### Slurm Profiles Configuration Example

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/slurm_plugin

This example demonstrates the structure and syntax for the `/etc/rstudio/launcher.slurm.profiles.conf` file. It showcases global, per-group, and per-user profile definitions with various resource and partition settings.

```configuration
[*]
default-cpus=1
default-mem-mb=512
max-cpus=2
max-mem-mb=1024
max-gpus-v100=1
max-gpus-tesla=1
allowed-partitions=mars,jupiter
singularity-image-directory=/singularity-images

[@posit-power-users]
default-cpus=4
default-mem-mb=4096
max-cpus=20
max-mem-mb=20480
max-gpus-tesla=10
default-gpus-tesla=2
max-gpus-v100=8
default-gpus-v100=0
allowed-partitions=mars,jupiter,saturn,titan

[jsmith]
max-cpus=3
```

--------------------------------

### Example: Register Shiny Test Kernel

Source: https://docs.posit.co/ide/server-pro/user/jupyter-lab/guide/jupyter-kernel-management

Provides a concrete example of registering a Jupyter kernel with specific names for machine and display. This demonstrates the usage of the registration command.

```bash
python -m ipykernel install --name shiny-test --display-name "Shiny Test" --user
```

--------------------------------

### Example Workflow: Accessing S3 Bucket with R paws package

Source: https://docs.posit.co/ide/server-pro/user/posit-workbench/managed-credentials/aws

Demonstrates how to use the 'paws' package in R to interact with AWS S3 buckets after confirming credential availability. The example includes listing objects, uploading a file, and downloading a file from an S3 bucket. Ensure the 'paws' package is installed and the specified bucket exists.

```r
library(paws)

# create an S3 service object in the region you are working on
s3 <- paws::s3(config = list(region = "us-east-2"))

# locate the s3 bucket you want
bucket = 'colorado-projects'
s3$list_objects(Bucket = bucket)

# upload data to s3 bucket
s3$put_object(
  Bucket = bucket,
  Key = 'data.csv'
)

# read data from s3 bucket
s3_download <- s3$get_object(
  Bucket = bucket,
  Key = 1
)
```

--------------------------------

### Example NFS Mount Output

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/troubleshooting/storage-server

This is an example of the expected output when running the 'mount -l | grep nfs' command, indicating that the /home directory is successfully mounted via NFS. This confirms the NFS server is accessible and configured correctly.

```text
172.31.0.123:/home on /home type nfs4 (rw,relatime,vers=4.1,rsize=1048576,wsize=1048576,namlen=255,hard,proto=tcp,timeo=600,retrans=2,sec=sys,clientaddr=172.31.6.220,local_lock=none,addr=172.31.0.123)
```

--------------------------------

### Install NFS Client and Mount Shared Storage on Workbench Nodes

Source: https://docs.posit.co/ide/server-pro/admin/getting_started/installation/multi_server_installation

These commands install the necessary NFS client package and mount shared NFS directories on each Workbench node. It includes updating package lists, installing `nfs-common`, creating mount point directories, and mounting the NFS exports. Remember to replace the placeholder NFS_HOST with your actual NFS server IP address.

```shell
# Install nfs-common
sudo apt-get update
sudo apt-get install -y nfs-common

# Replace this value with the IP address for your NFS server
NFS_HOST="<REPLACE-WITH-YOUR-NFS-HOST>"

# Create the directories for the NFS mount
sudo mkdir -p /nfs/workbench/home
sudo mkdir -p /nfs/workbench/shared-storage

# Mount the NFS directories (example for home directories)
sudo mount -t nfs ${NFS_HOST}:/var/nfs/workbench/home /nfs/workbench/home
sudo mount -t nfs ${NFS_HOST}:/var/nfs/workbench/shared-storage /nfs/workbench/shared-storage
```

--------------------------------

### Verify User Home Directory Paths (Terminal)

Source: https://docs.posit.co/ide/server-pro/admin/authenticating_users/authentication_migration

Provides example commands to verify user home directory paths after authentication migration. This helps confirm that the system is referencing the correct directories for users, especially when transitioning from local accounts to LDAP/AD.

```bash
echo ~suzy_local
echo ~suzy_ad
```

--------------------------------

### Install Nginx on Debian/Ubuntu

Source: https://docs.posit.co/ide/server-pro/admin/access_and_security/running_with_a_proxy

Installs the Nginx web server on Debian or Ubuntu systems. This is a prerequisite for using Nginx as a reverse proxy.

```bash
sudo apt-get install nginx
```

--------------------------------

### Install Posit Workbench on SUSE/openSUSE

Source: https://docs.posit.co/ide/server-pro/admin/getting_started/installation/installation

Downloads and installs Posit Workbench version 2025.05.1 on SUSE 15 SP6 / openSUSE 15.6 using curl and zypper. Requires appropriate permissions for file download and package installation.

```bash
curl -O https://download2.rstudio.org/server/opensuse15/x86_64/rstudio-workbench-2025.05.1-x86_64.rpm
sudo zypper install rstudio-workbench-2025.05.1-x86_64.rpm
```

--------------------------------

### Test Extension Installation with positron-server CLI

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/extension_configuration

This command allows administrators to test the installation of a single extension line from the `positron.extensions.conf` file directly via the command line. Replace `<test-line>` with the actual extension configuration string.

```bash
positron-server --install-extension <test-line>
```

--------------------------------

### Positron Pro Configuration Example

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/configuration

An example of how the /etc/rstudio/positron.conf file can be configured to enable Positron Pro sessions and specify the default session cluster.

```bash
# /etc/rstudio/positron.conf
exe=/usr/lib/rstudio-server/bin/positron-server/bin/positron-server
enabled=1
default-session-cluster=Kubernetes
```

--------------------------------

### User Resource Profile Access Control Example

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/kubernetes_plugin

Example configuration for controlling user access to resource profiles and custom resources in `/etc/rstudio/launcher.kubernetes.profiles.conf`. This file demonstrates how to restrict access based on user groups.

```properties
[*]
resource-profiles=default,small
allow-custom-resources=0

[@bioinformatics]
resource-profiles=default,small,default-gpu,hugemem

[@posit-power-users]
resource-profiles=default,small,default-gpu,hugemem
allow-custom-resources=1
```

--------------------------------

### Install Nginx on Red Hat

Source: https://docs.posit.co/ide/server-pro/admin/access_and_security/running_with_a_proxy

Installs the Nginx web server on Red Hat-based systems. This is a prerequisite for using Nginx as a reverse proxy.

```bash
sudo yum install nginx
```

--------------------------------

### Install SELinux Policy Module

Source: https://docs.posit.co/ide/server-pro/admin/access_and_security/selinux_configuration

This command installs the compiled SELinux policy module (.pp file) into the system. This step is necessary to activate the custom policy for RStudio Workbench.

```bash
semodule -i ./workbench.pp
```

--------------------------------

### Install Extension via Command Line (Positron Pro)

Source: https://docs.posit.co/ide/server-pro/user/positron/guide/extensions

This command-line argument is used to install an extension by providing the VSIX file path. This method is applicable when manual installation is allowed and an administrator has not set up a global extensions directory.

```bash
--install-extension <extension publisher>.<extension>
```

--------------------------------

### Configure Python Package Repositories and Timeouts in Posit Workbench

Source: https://docs.posit.co/ide/server-pro/admin/python/package_installation

This configuration snippet for `/etc/rstudio/launcher-env` sets custom primary and backup Python package repositories for Positron sessions using `PIP_INDEX_URL`, `UV_INDEX_URL`, `PIP_EXTRA_INDEX_URL`, and `UV_EXTRA_INDEX_URL`. It also configures a 60-second timeout for all session types using `PIP_TIMEOUT` and `UV_HTTP_TIMEOUT`. This allows for localized package management and improved session stability.

```bash
JobType: session
Workbench: positron
Environment: PIP_INDEX_URL="primary.example.index.site"
UV_INDEX_URL="primary.example.index.site"
PIP_EXTRA_INDEX_URL="backup.example.index.site"
UV_EXTRA_INDEX_URL="backup.example.index.site"

JobType: session
Workbench: any
Environment: PIP_TIMEOUT=60
UV_HTTP_TIMEOUT=60
```

--------------------------------

### Install Posit Workbench on Ubuntu 20 or Debian 11

Source: https://docs.posit.co/ide/server-pro/admin/getting_started/installation/installation

Installs Posit Workbench version 2025.05.1 on Ubuntu 20 or Debian 11. This involves installing gdebi-core, downloading the .deb package, and then installing it.

```bash
sudo apt-get install gdebi-core
curl -O https://download2.rstudio.org/server/focal/amd64/rstudio-workbench-2025.05.1-amd64.deb
sudo gdebi rstudio-workbench-2025.05.1-amd64.deb
```

--------------------------------

### Install Posit Workbench on Ubuntu 24/22 or Debian 12

Source: https://docs.posit.co/ide/server-pro/admin/getting_started/installation/installation

Installs Posit Workbench version 2025.05.1 on Ubuntu 24/22 or Debian 12. It first installs the gdebi-core package, then downloads the .deb file, and finally installs it using gdebi.

```bash
sudo apt-get install gdebi-core
curl -O https://download2.rstudio.org/server/jammy/amd64/rstudio-workbench-2025.05.1-amd64.deb
sudo gdebi rstudio-workbench-2025.05.1-amd64.deb
```

--------------------------------

### Nginx Reverse Proxy Configuration for Multiple Node Routing

Source: https://docs.posit.co/ide/server-pro/admin/load_balancing/access_and_availability

An example Nginx configuration to act as a reverse proxy for a Posit Workbench cluster. This setup routes traffic to multiple nodes, with one designated as primary and others as backups, enabling failover. It requires Nginx to be installed and configured on a separate host or one of the cluster nodes.

```nginx
http {
  upstream rstudio-server {
    server rstudio1.example.com;
    server rstudio2.example.com backup;
    server rstudio3.example.com backup;
  }
  server {
    listen 80;
    location / {
      proxy_pass http://rstudio-server;
      proxy_redirect http://rstudio-server/ $scheme://$host/;
    }
  }
}
```

--------------------------------

### Install Extension from Open VSX using Positron Server

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/extension_configuration

Installs an extension from the Open VSX registry using the `positron-server` command-line tool. Requires write access to the specified extensions directory. The command takes the extensions directory and the publisher.extension name as arguments.

```bash
positron-server --extensions-dir <extensions directory> --install-extension <extension publisher>.<extension name>
```

```bash
/usr/lib/rstudio-server/bin/positron-server/bin/positron-server --extensions-dir=/opt/positron-server/extensions --install-extension streetsidesoftware.code-spell-checker
```

--------------------------------

### Start Job Launcher Service

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/launcher_administration

Command to start the Job Launcher service. Requires root privileges for initial authentication and authorization.

```bash
sudo rstudio-launcher start
```

--------------------------------

### Install VS Code Extensions Globally

Source: https://docs.posit.co/ide/server-pro/admin/vscode_sessions/extension_configuration

Command to install VS Code extensions globally from a configuration file. This is useful for system administrators to manage extensions for all users.

```bash
rstudio-server install-vs-code-ext
```

--------------------------------

### Get Compute Environments using Bash

Source: https://docs.posit.co/ide/server-pro/admin/workbench_api/workbench_api

This script retrieves a list of available compute environments. It makes a GET request to the /api/get_compute_envs endpoint. Authentication with an API token and the server URL are required.

```bash
#!/bin/bash
method="get_compute_envs"

# Replace with your 32 character API token
apiToken=<api-token-key>

# Replace with your Posit Workbench server URL
workbenchServerUrl="http://localhost:8787"

curl  -H "Content-Type: application/json" \
      -H "Authorization: Bearer $apiToken" \
      -d "{\"method\":\"$method\"}" \
      "$workbenchServerUrl/api/$method"
```

--------------------------------

### Example Host Aliases JSON for Kubernetes

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/kubernetes_plugin

Provides an example JSON structure for defining host aliases, which can be used with 'job-json-overrides' to configure entries in a Pod's host file. This JSON should be placed in the file specified by the 'job-json-overrides' configuration.

```json
[
  {
    "ip": "10.2.141.12",
    "hostnames": ["db01"]
  },
  {
    "ip": "10.2.141.13",
    "hostnames": ["db02"]
  }
]
```

--------------------------------

### Get Compute Environments (GET)

Source: https://docs.posit.co/ide/server-pro/admin/workbench_api/interface

Fetches metadata about supported compute environments and resource limits for launching new sessions. This GET request retrieves general information about available environments.

```http
GET /api/get_compute_envs
```

--------------------------------

### Specify Custom R Installation Folders (JSON)

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/interpreter_settings

Use `positron.r.customRootFolders` to provide additional directories where Positron Pro should search for R installations. This setting is searched in addition to the default system locations. Ensure the R executable exists at `bin/R` within the specified installation directories.

```json
"positron.r.customRootFolders": [
    "/custom/R/location",
    "/another/custom/R"
]
```

--------------------------------

### Example: Launch Session API Request (Bash)

Source: https://docs.posit.co/ide/server-pro/admin/workbench_api/workbench_api

A bash script demonstrating how to make a `launch_session` API call to Posit Workbench using `curl`. It includes placeholders for the API token, username, and server URL.

```bash
#!/bin/bash
method="launch_session"

# Replace with your 32 character API token
apiToken=<api-token-key>

# Replace the username value with a valid user account on the system
# Additional launch_parameters required for other session types.
paramsJson=', "kwparams": {"launch_parameters":{"name":"Test RStudio Session","cluster":"Local"}, "username":"replace-this-user-name"}'

# Replace with your Posit Workbench server URL
workbenchServerUrl="http://localhost:8787"

curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer $apiToken" \
     -d "{\"method\":\"$method\" $paramsJson}" \
     "$workbenchServerUrl/api/$method"
```

--------------------------------

### Override Available R Interpreters (JSON)

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/interpreter_settings

Configure `positron.r.interpreters.override` to define an explicit list of R installations that Positron Pro should consider available. This setting takes precedence over all other discovery and exclusion settings. Paths can point to R binaries, R installation directories, or parent directories containing R installations.

```json
"positron.r.interpreters.override": [
    "/custom/R/location/4.3.0/bin/R"
]
```

--------------------------------

### Tutorial API

Source: https://docs.posit.co/ide/server-pro/admin/authenticating_users/customizing_signin

Documentation for the Tutorial API, covering its overview, configuration, interface, methods, and callbacks.

```APIDOC
## Tutorial API

### Description
Provides an overview, configuration details, interface specifications, available methods, and callback mechanisms for the Tutorial API.

### Endpoint
`/admin/tutorial_api` (and related sub-paths)

### Parameters
N/A (This section describes the API's capabilities, not specific endpoint parameters.)

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Test Posit Workbench with Kubernetes Integration

Source: https://docs.posit.co/ide/server-pro/admin/integration/launcher-kubernetes

Tests the installation and configuration of Posit Workbench with Launcher and Kubernetes by stopping, verifying, and starting the RStudio server. This command verifies that Workbench and Launcher can successfully communicate with Kubernetes and start sessions/jobs.

```bash
sudo rstudio-server stop
sudo rstudio-server verify-installation --verify-user=<USER>
sudo rstudio-server start
```

--------------------------------

### Customize Workbench Session Docker Image

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/configuration

Example Dockerfile to extend the official Posit Workbench session image. It installs system dependencies like gdebi-core.

```dockerfile
FROM rstudio/workbench-session:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10
ARG R_VERSION

# install system dependencies
RUN apt-get update
    && apt-get install -y gdebi-core

```

--------------------------------

### Kubernetes Profile Configuration Example

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/kubernetes_plugin

An example configuration file for the Posit Workbench Kubernetes plugin, demonstrating global, per-group, and per-user profile settings. This file specifies resource constraints and allowed container images for different user and group scopes.

```ini
[*]
placement-constraints=node,region:us,region:eu
default-cpus=1
default-cpus-request=0.5
default-mem-mb=512
default-mem-mb-request=256
max-cpus=2
max-mem-mb=1024
container-images=r-session:3.4.2,r-session:3.5.0
allow-unknown-images=0

[@posit-power-users]
default-cpus=4
default-mem-mb=4096
default-nvidia-gpus=0
default-amd-gpus=0
max-nvidia-gpus=2
max-amd-gpus=3
max-cpus=20
max-mem-mb=20480
container-images=r-session:3.4.2,r-session:3.5.0,r-session:preview
allow-unknown-images=1

[jsmith]
max-cpus=3
```

--------------------------------

### Install LDAP Client Dependencies for RHEL/Ubuntu

Source: https://docs.posit.co/ide/server-pro/admin/authenticating_users/active_directory

Installs the required system dependencies for joining an Active Directory domain on RHEL and Ubuntu systems. These packages include tools for Samba, realmd, SSSD, and Kerberos.

```bash
sudo yum install samba-common-tools realmd oddjob oddjob-mkhomedir \
    sssd adcli krb5-workstation
```

```bash
sudo dnf install samba-common-tools realmd oddjob oddjob-mkhomedir \
    sssd adcli krb5-workstation
```

```bash
sudo apt install realmd sssd sssd-tools libnss-sss libpam-sss adcli \
    samba-common-bin oddjob oddjob-mkhomedir packagekit
```

--------------------------------

### Install Apache Proxy Modules on Debian/Ubuntu

Source: https://docs.posit.co/ide/server-pro/admin/access_and_security/running_with_a_proxy

Installs Apache and necessary proxy modules (mod_proxy, mod_proxy_html) on Debian-based systems like Ubuntu. Requires libxml2-dev for certain functionalities.

```bash
sudo apt-get install apache2
sudo apt-get install libapache2-mod-proxy-html
sudo apt-get install libxml2-dev
```

--------------------------------

### Set Manual Interpreter Startup - R

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/interpreter_settings

Configures the R interpreter startup behavior to 'manual' in Positron Pro sessions. This prevents R from starting automatically but allows users to start an R interpreter manually when needed. This is useful for teams that primarily use Python.

```json
{
    "[r]": {
        "interpreters.startupBehavior": "manual"
    }
}
```

--------------------------------

### Manually List R Versions - r-versions

Source: https://docs.posit.co/ide/server-pro/admin/r/using_multiple_versions_of_r

This configuration file allows administrators to manually specify the paths to R installations that should be recognized by Posit Workbench. This is an alternative to automatic scanning and is useful for custom R installations. Each R home path should be on a new line.

```plaintext
/opt/R-4.1.2
/opt/R-devel-4.2
```

--------------------------------

### Install Extension from Open VSX using CLI

Source: https://docs.posit.co/ide/server-pro/admin/vscode_sessions/extension_configuration

Installs an extension from the Open VSX registry using the `code-server --install-extension` command. Requires specifying the extensions directory and the extension publisher and name. Ensure the correct path to `code-server` is used.

```bash
code-server --extensions-dir <extensions directory> --install-extension <extension publisher>.<extension name>
```

```bash
/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server --extensions-dir=/opt/code-server/extensions --install-extension ms-python.python
```

--------------------------------

### Override pip Index URL with Command-Line Option

Source: https://docs.posit.co/ide/server-pro/admin/python/package_installation

Overrides all other pip index URL configurations by specifying the index URL directly on the command line. This has the highest precedence.

```bash
pip install --index-url https://example.index.site package_name
```

--------------------------------

### Install Extension from VSIX File using Positron Server

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/extension_configuration

Installs an extension from a local VSIX file using the `positron-server` command-line tool. Requires write access to the specified extensions directory. The command takes the extensions directory and the path to the VSIX file as arguments.

```bash
/usr/lib/rstudio-server/bin/positron-server/bin/positron-server --extensions-dir=/opt/positron-server/extensions --install-extension ./my-extension.vsix
```

--------------------------------

### Get RStudio Workbench Node Status (Shell)

Source: https://docs.posit.co/ide/server-pro/admin/load_balancing/configuration

Retrieves the status of online nodes and their allocated sessions from a specific RStudio Workbench node. The output is a JSON object used by the load balancing algorithm to determine where to start new sessions.

```shell
rstudio-server node-status
```

--------------------------------

### Configure uv Index URL via Configuration File

Source: https://docs.posit.co/ide/server-pro/admin/python/package_installation

Sets the index-url within the uv configuration file (/etc/uv/uv.toml). This method has lower precedence than environment variables and command-line options.

```toml
[global]
index-url = "https://packagemanager.posit.co/pypi/latest/simple"
```

--------------------------------

### Configure Open VSX Extensions in positron.extensions.conf

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/extension_configuration

Administrators can specify extensions to install from Open VSX by listing them in the `positron.extensions.conf` file. Each line should be in the format `${publisher}.${name}`. This requires network access to Open VSX and may increase initial session load times.

```plaintext
databricks.databricks
```

--------------------------------

### Configure pip Index URL via Configuration File

Source: https://docs.posit.co/ide/server-pro/admin/python/package_installation

Sets the index-url within the pip configuration file (/etc/pip.conf). This method has lower precedence than environment variables and command-line options.

```ini
[global]
index-url = https://packagemanager.posit.co/pypi/latest/simple
```

--------------------------------

### Set WORKBENCH_JUPYTER_PATH Environment Variable

Source: https://docs.posit.co/ide/server-pro/admin/jupyter_sessions/configuration

This example shows how to set the `WORKBENCH_JUPYTER_PATH` environment variable, typically within a container build or a `launcher-env` file. This variable dictates the priority for locating the `jupyter` executable, ensuring Workbench uses the desired installation.

```bash
export WORKBENCH_JUPYTER_PATH=/path/to/your/jupyter/installation
```

--------------------------------

### Configure PAM Profile for Kerberos Authentication

Source: https://docs.posit.co/ide/server-pro/admin/access_and_security/pam_sessions

This example shows the necessary directives for the `/etc/pam.d/rstudio-session` PAM profile to integrate with `pam_sss.so` for Kerberos authentication.

```pam
/etc/pam.d/rstudio-session

auth        required      pam_sss.so
account     [default=bad success=ok user_unknown=ignore] pam_sss.so
password    sufficient    pam_sss.so use_authtok
session     requisite     pam_sss.so
```

--------------------------------

### Get Traefik Ingress Controller Service IP using kubectl

Source: https://docs.posit.co/ide/server-pro/admin/getting_started/installation/kubernetes_installation

This command retrieves the details of the Traefik service in Kubernetes, specifically focusing on identifying the `EXTERNAL-IP`. This IP address is essential for configuring DNS records to point to your Posit Workbench installation.

```bash
kubectl get svc traefik
```

--------------------------------

### Configure Global Extensions Directory in positron.conf

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/extension_configuration

To set a global directory for Positron Pro extensions, add the `args=--extensions-dir=/opt/positron/extensions` line to the `positron.conf` file. Extensions should then be manually installed into the specified directory.

```ini
args=--extensions-dir=/opt/positron/extensions
```

--------------------------------

### Include Additional Python Interpreter Paths

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/interpreter_settings

Adds Python installations to Positron Pro's discovery process when default strategies fail. Specify absolute paths to executables or directories containing Python installations. This setting is ignored if `python.interpreters.override` is configured and does not take effect for interpreters also listed in `python.interpreters.exclude`. The paths provided are searched in addition to default system locations.

```json
{
    "python.interpreters.include": [
        "/custom/python/location",
        "/another/custom/python/3.12.0/bin/python"
    ]
}
```

--------------------------------

### Configure uv Index URL via Environment Variable

Source: https://docs.posit.co/ide/server-pro/admin/python/package_installation

Sets the UV_INDEX_URL environment variable, which uv uses to determine the package index. This method has higher precedence than configuration files like /etc/uv/uv.toml.

```bash
export UV_INDEX_URL=https://packagemanager.posit.co/pypi/latest/simple
```

--------------------------------

### Install Extension from VSIX File using CLI

Source: https://docs.posit.co/ide/server-pro/admin/vscode_sessions/extension_configuration

Installs an extension from a local VSIX file using the `code-server --install-extension` command. The path to the VSIX file is provided as the extension name. If the extension version is incompatible, specify a compatible version.

```bash
/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server --extensions-dir=/opt/code-server/extensions --install-extension ./my-extension.vsix
```

--------------------------------

### Apache Proxy Configuration Examples

Source: https://docs.posit.co/ide/server-pro/admin/access_and_security/running_with_a_proxy

This section provides Apache configuration examples for proxying requests to Posit Workbench. It includes 'ProxyPass' and 'RewriteRule' directives for scenarios with and without a path prefix ('/rstudio'), and for direct root ('/') proxying.

```apache
RewriteRule /rstudio/(.*)     http://localhost:8787/$1 [P,L]
ProxyPass /rstudio/ http://localhost:8787/
```

```apache
ProxyPass / http://localhost:8787/
```

--------------------------------

### Configure pip Index URL via Environment Variable

Source: https://docs.posit.co/ide/server-pro/admin/python/package_installation

Sets the PIP_INDEX_URL environment variable, which pip uses to determine the package index. This method has higher precedence than configuration files like /etc/pip.conf.

```bash
export PIP_INDEX_URL=https://packagemanager.posit.co/pypi/latest/simple
```

--------------------------------

### Initialize Userspace Licensing (Bash)

Source: https://docs.posit.co/ide/server-pro/admin/license_management/license_management

Command to initialize the license system in userspace mode. This command must be run as the Posit Workbench account (e.g., 'rstudio-server') and *not* with elevated privileges.

```bash
rstudio-server license-manager initialize --userspace
```

--------------------------------

### Exclude R Interpreters from Discovery (JSON)

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/interpreter_settings

The `positron.r.interpreters.exclude` setting allows you to specify absolute paths to R binaries or directories containing R installations that should not be available in Positron Pro. This setting is ignored if `positron.r.interpreters.override` is configured.

```json
"positron.r.interpreters.exclude": [
    "/opt/R/4.2.0/bin/R",
    "/custom/R/location"
]
```

--------------------------------

### Set Manual Interpreter Startup - General

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/interpreter_settings

Sets the interpreter startup behavior to 'manual' for all interpreters in Positron Pro sessions. This means interpreters will only start when explicitly selected by the user. This setting can be overridden by per-language configurations.

```json
{
    "interpreters.startupBehavior": "manual"
}
```

--------------------------------

### Navigate to Help Topic (JavaScript)

Source: https://docs.posit.co/ide/server-pro/admin/tutorial_api/tutorial_api_methods

Navigates the help pane to a specific documentation topic. Topics should be namespace-qualified (e.g., 'graphics::plot'), though base package topics do not require qualification.

```javascript
helpTopic('graphics::plot');
```

```javascript
helpTopic('mean');
```

--------------------------------

### Set Python Package Index URL in rserver.conf

Source: https://docs.posit.co/ide/server-pro/admin/python/package_installation

This configuration sets the default Python package index URL for sessions. It is added to the session environment via PIP_INDEX_URL and UV_INDEX_URL, overriding any index-url set in /etc/pip.conf.

```text
/etc/rstudio/rserver.conf

session-python-index-url=https://packagemanager.posit.co/pypi/latest/simple
```

--------------------------------

### Tutorial API

Source: https://docs.posit.co/ide/server-pro/admin/load_balancing/load_balancing_vs_job_launcher

Documentation for the Tutorial API, including its overview, configuration, interface, methods, and callbacks.

```APIDOC
## Tutorial API

### Description
Provides an overview, configuration details, interface specifications, methods, and callbacks for the Tutorial API.

### Method
N/A (Documentation Overview)

### Endpoint
N/A (Documentation Overview)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Get Session API Request

Source: https://docs.posit.co/ide/server-pro/admin/workbench_api/interface

This is an example of a POST request to the /api/get_session endpoint. It demonstrates how to retrieve session and job information for a specific user, with options to filter fields and include job details. An admin token is required for cross-user queries.

```json
POST /api/get_session {
   "method": "get_session",
   "kwparams": {
      "session_id": "id1,id2",
      "user": "username",
      "fields" : ["id", "url", "activity_state"],
      "include_jobs" : true
   }
}
```

--------------------------------

### Example Custom PAM Profile (/etc/pam.d/rstudio-session) for Ubuntu

Source: https://docs.posit.co/ide/server-pro/admin/access_and_security/pam_sessions

This is an example of a custom PAM profile for Posit Workbench sessions, based on a modified Ubuntu 'su' profile. It includes modules for root authentication, environment variable parsing, user limits, and standard authentication/account/session management.

```pam
# This allows root to su without passwords (this is required)
auth       sufficient pam_rootok.so

# This module parses environment configuration file(s)
# and also allows you to use an extended config
# file /etc/security/pam_env.conf.
# parsing /etc/environment needs "readenv=1"
session    required   pam_env.so readenv=1

# Locale variables are also kept into /etc/default/locale in etch
# reading this file *in addition to /etc/environment* does not hurt
session    required   pam_env.so readenv=1 envfile=/etc/default/locale

# Enforces user limits defined in /etc/security/limits.conf
session    required   pam_limits.so

# The standard Unix authentication modules
@include common-auth
@include common-account
@include common-session
```

--------------------------------

### Override Python Interpreters

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/interpreter_settings

Limits the displayed Python installations in Positron Pro to a specific set of absolute paths. This setting takes precedence over include/exclude settings. Ensure the interpreter executable exists at `bin/python` within the specified directory.

```json
"python.interpreters.override": [
    "/custom/python/location/3.13.0/bin/python"
]
```

--------------------------------

### Disable Python Interpreter Startup - Python

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/interpreter_settings

Configures the Python interpreter to be disabled in Positron Pro sessions. This prevents Python from starting automatically and hides it from user selection. This setting is applied within the user or group settings templates.

```json
{
    "[python]": {
        "interpreters.startupBehavior": "disabled"
    }
}
```

--------------------------------

### Serve Example Page using Python HTTP Server

Source: https://docs.posit.co/ide/server-pro/admin/tutorial_api/configuration

Provides instructions to serve the Posit Workbench example page using Python's built-in HTTP server. This allows local testing and demonstration of the Tutorial API.

```bash
cd /usr/lib/rstudio-server/extras/tutorial
python2 -m SimpleHTTPServer 8080
```

```bash
cd /usr/lib/rstudio-server/extras/tutorial
python3 -m http.server 8080
```

--------------------------------

### Disable R Interpreter Startup - R

Source: https://docs.posit.co/ide/server-pro/admin/positron_sessions/interpreter_settings

Configures the R interpreter to be disabled in Positron Pro sessions. This prevents R from starting automatically and hides it from user selection. This setting is applied within the user or group settings templates.

```json
{
    "[r]": {
        "interpreters.startupBehavior": "disabled"
    }
}
```

--------------------------------

### Configure launcher.conf for SSL

Source: https://docs.posit.co/ide/server-pro/admin/hardening/example_secure_configuration

This snippet configures the launcher.conf file to enable SSL for secure connections to the Job Launcher. It specifies the certificate and key files required for SSL.

```ini
enable-ssl=1
certificate-file=/var/certs/your_domain_name.crt
certificate-key-file=/var/certs/your_domain_name.key
```

--------------------------------

### Posit Workbench Startup Failure Log Example

Source: https://docs.posit.co/ide/server-pro/admin/getting_started/installation/kubernetes_installation

An example of Posit Workbench container logs indicating a startup failure due to an inability to connect to the PostgreSQL database. It highlights a 'Name or service not known' error when resolving the database host.

```log
2023-06-28T21:03:24.048603Z [rserver] INFO Reading database configuration from '/mnt/secret-configmap/rstudio/database.conf'
2023-06-28T21:03:24.048907Z [rserver] INFO Connecting to Postgres database: postgres://workbench@workbench.posit.co:5432/workbench?sslmode=disable
2023-06-28T21:03:24.049003Z [rserver] INFO Creating database connection pool of size 2 (source: logical CPU count)
2023-06-28T21:03:24.049414Z [rserver] WARNING A plain text value is potentially being used for the PostgreSQL password, or an encrypted password could not be decrypted. The RStudio Server documentation for PostgreSQL shows how to encrypt this value.; LOGGED FROM: rstudio::core::Error rstudio::core::database::ConnectVisitor::getPassword(const rstudio::core::database::PostgresqlConnectionOptions&, std::string&) const src/cpp/core/Database.cpp:426
2023-06-28T21:03:24.088341Z [rserver] ERROR database error 7 (Cannot establish connection to the database.
could not translate host name "workbench.posit.co" to address: Name or service not known
); OCCURRED AT rstudio::core::Error rstudio::core::database::ConnectVisitor::operator()(const rstudio::core::database::PostgresqlConnectionOptions&) const src/cpp/core/Database.cpp:235; LOGGED FROM: int main(int, char* const*) src/cpp/server/ServerMain.cpp:769
+ deactivate
+ echo '== Exiting =='
+ rstudio-server stop
== Exiting ==
+ echo 'Deactivating license ...'
```

--------------------------------

### Example Get Session Result

Source: https://docs.posit.co/ide/server-pro/admin/workbench_api/interface

This JSON represents the successful result of a get_session API call. It contains an array of session objects, each with details like URL, ID, creation time, and activity state. If include_jobs was true, job information would also be present.

```json
{
  "result": {
    "sessions": [
      {
        "url": "/s/0da29cfc78a316124d41f/",
        "id": "6124d41f",
        "launch_parameters": {
          "name": "RStudio Pro Session",
          "cluster": "Local",
          "placement_constraints": [],
          "resource_limits": [],
          "queues": [],
          "container_image": "",
          "default_image": "",
          "container_images": [
            ""
          ]
        },
        "created": 1721684073175,
        "activity_state": "suspended",
        "last_state_updated": 1721695376181,
        "label": "RStudio Pro Session",
        "display_name": "RStudio Pro Session",
        "status_detail": "",
        "project": null,
        "project_id": "none",
        "running": false,
        "working_dir": "~",
        "executing": false,
        "save_prompt_required": false,
        "last_used": 1721694685914,
        "r_version": "4.3.0",
        "r_version_label": "",
        "r_version_home": "/usr/lib/R",
        "suspend_size": 20324197,
        "workbench": "RStudio"
      }
    ]
  }
}
```

--------------------------------

### Combine Global and API-Triggered Session Hooks

Source: https://docs.posit.co/ide/server-pro/admin/sessions/session_hooks

This example shows a combined approach where global session hooks are enabled and API calls can trigger additional or specific hooks. It demonstrates configuring global start/stop scripts and using the API to trigger a separate start hook.

```shell
session-hooks-enabled=1
session-hooks-path=/tmp/mysessionhooks
session-hooks-start=start.sh
session-hooks-stop=stop.sh
```

```json
{
  "method": "launch_session",
  "kwparams": {
    "workbench": "RStudio",
      "name": "My RStudio Session",
      "start_hooks": [
         {"exe": "other-start.sh"}
      ],
      ... other contents ...
  }
}
```

--------------------------------

### Configure R Version Scanning - rserver.conf

Source: https://docs.posit.co/ide/server-pro/admin/r/using_multiple_versions_of_r

This configuration snippet disables the automatic scanning of default directories for R versions. It is useful when R versions are installed in non-standard locations or when manual control is preferred. This setting is applied in the `/etc/rstudio/rserver.conf` file.

```plaintext
r-versions-scan=0
```

--------------------------------

### getState Callback Examples - JSON

Source: https://docs.posit.co/ide/server-pro/admin/tutorial_api/tutorial_api_callbacks

Examples of the JSON payload returned by the 'getState' callback. This callback provides information about the currently loaded .Rproj file and any associated git remotes. It demonstrates scenarios with remotes, without remotes, and when no project is loaded.

```json
{
  "message": "getState",
  "callerID": "abcd",
  "project": "~/aaa/aaa.Rproj",
  "remotes": [
    {
      "active": true,
      "remote": "origin",
      "type": "fetch",
      "url": "https://github.com/rstudio/aaa"
    },
    {
      "active": true,
      "remote": "origin",
      "type": "push",
      "url": "https://github.com/rstudio/aaa"
    }
  ]
}
```

```json
{
  "message": "getState",
  "callerID": "abcd",
  "project": "~/localproj/localproj.Rproj",
  "remotes": []
}
```

```json
{
  "message": "getState",
  "callerID": "abcd",
  "project": null,
  "remotes": []
}
```

--------------------------------

### Assign IAM Roles using kiam in Kubernetes Jobs

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/kubernetes_plugin

This example illustrates how to use kiam (a deprecated tool) to assign different IAM roles to Kubernetes job users based on their group membership. It shows a scenario where users in the 'admin-grp' group get the 'rs-admin-role', while all other users receive the 'rs-user-role'. This allows for fine-grained access control to cloud resources.

```yaml
job.tpl
```

--------------------------------

### Enable Job Launcher Service on System Startup (System V)

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/launcher_administration

Command to configure the Job Launcher service to automatically start when the system boots using the System V init system.

```bash
chkconfig --add rstudio-launcher
```

--------------------------------

### Specify R Versions Path - rserver.conf

Source: https://docs.posit.co/ide/server-pro/admin/r/using_multiple_versions_of_r

This configuration snippet allows administrators to specify a custom path for the R version report file. This is typically used when the default location is not suitable, for example, when mounting configuration files across multiple nodes. The setting is applied in `/etc/rstudio/rserver.conf`.

```plaintext
r-versions-path=/mnt/config/rstudio-server/r-versions
```

--------------------------------

### Kubernetes Setup for Job Launcher Service Account and Namespace

Source: https://docs.posit.co/ide/server-pro/admin/job_launcher/kubernetes_plugin

This script creates a 'rstudio' namespace, a 'job-launcher' service account within that namespace, and defines a Role with extensive permissions for managing pods, services, and batch jobs. It also sets up a RoleBinding to associate the service account with the defined role. Finally, it creates a ClusterRole and ClusterRoleBinding to grant read-only access to nodes, which is necessary for retrieving node IP addresses for job routing.

```shell
kubectl create namespace rstudio
kubectl create serviceaccount job-launcher --namespace rstudio
cat > job-launcher-role.yaml <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: job-launcher-role
  namespace: rstudio
rules:
  - apiGroups:
      - ""
    resources:
      - "pods"
      - "pods/log"
      - "pods/attach"
      - "pods/exec"
    verbs:
      - "get"
      - "create"
      - "update"
      - "patch"
      - "watch"
      - "list"
      - "delete"
  - apiGroups:
      - ""
    resources:
      - "events"
    verbs:
      - "watch"
  - apiGroups:
      - ""
    resources:
      - "services"
    verbs:
      - "create"
      - "get"
      - "watch"
      - "list"
      - "delete"
  - apiGroups:
      - "batch"
    resources:
      - "jobs"
    verbs:
      - "create"
      - "update"
      - "patch"
      - "get"
      - "watch"
      - "list"
      - "delete"
  - apiGroups:
      - "metrics.k8s.io"
    resources:
      - "pods"
    verbs:
      - "get"
  - apiGroups:
      - ""
    resources:
      - "serviceaccounts"
    verbs:
      - "list"
EOF
kubectl create -f job-launcher-role.yaml; rm job-launcher-role.yaml
kubectl create rolebinding job-launcher-role-binding --namespace rstudio \
   --role=job-launcher-role \
   --serviceaccount=rstudio:job-launcher
kubectl create clusterrole job-launcher-clusters \
   --verb=get,watch,list \
   --resource=nodes
kubectl create clusterrolebinding job-launcher-list-clusters \
  --clusterrole=job-launcher-clusters \
  --group=system:serviceaccounts:rstudio

```

--------------------------------

### Install JupyterLab Extensions with Pip

Source: https://docs.posit.co/ide/server-pro/user/jupyter-lab/guide/extensions

Users can install pre-built JupyterLab extensions from the Python Package Index (PyPI) using pip. This command installs or upgrades both jupyterlab and the specified extension. Note that installations typically default to the user's site-packages directory, and global installations require administrator privileges.

```bash
pip install --upgrade jupyterlab jupyterlab-git
```

--------------------------------

### Example User Data Structure

Source: https://docs.posit.co/ide/server-pro/admin/workbench_api/interface

This JSON snippet provides an example of the data structure returned when retrieving user information using the `/api/get_users` endpoint. It includes details such as username, status, admin privileges, user ID, and timestamps for last sign-in and creation.

```json
{
  "result": [
    {
      "username": "user1",
      "status": "Active",
      "isAdmin": false,
      "uid": 1037,
      "lastSignIn": "2024-07-30T23:45:28.351868Z",
      "created": "2024-07-30T23:41:28.109218Z"
    },
    {
      "username": "user2",
      "status": "Inactive",
      "isAdmin": false,
      "uid": 1038,
      "lastSignIn": "2024-07-25T13:43:25.231845Z",
      "created": "2024-07-30T23:41:28.109218Z"
    }
  ]
}
```

--------------------------------

### List Python Executables in Directory - Shell Command

Source: https://docs.posit.co/ide/server-pro/admin/python/configuring_default

This command lists all files in a Python installation's bin directory that contain 'python' in their name. It helps identify available Python executables, including symlinks and specific versioned commands, which is useful for understanding how to invoke different Python versions.

```shell
ls -l /opt/python/3.10.4/bin | grep python
```

--------------------------------

### Disable R Package Installation UI

Source: https://docs.posit.co/ide/server-pro/admin/rstudio_pro_sessions/package_installation

This setting disables the package installation user interface within RStudio Pro IDE. This is useful when packages are centrally managed and deployed to a site library, discouraging end-users from installing their own packages. Note that users can still install packages programmatically using R functions.

```ini
/etc/rstudio/rsession.conf

allow-package-installation=0
```

--------------------------------

### Display Help Document (JavaScript)

Source: https://docs.posit.co/ide/server-pro/admin/tutorial_api/tutorial_api_methods

Displays a Markdown (.md) or R Markdown (.Rmd) document within the help pane. This is useful for showing custom documentation or reports.

```javascript
helpDoc('~/my_report.Rmd');
```
Tokens:
Raw