vip.toml.example

# VIP Configuration
# Documentation: https://posit-dev.github.io/vip/getting-started/
#
# Copy this file to vip.toml and fill in your deployment details.
# Secrets should be set via environment variables (see comments below).
#
# Quick start (no config file needed):
#   vip verify --connect-url https://connect.example.com
#
# With this config file:
#   vip verify --config vip.toml --no-interactive-auth
#
# Headless auth (OIDC/SAML/OAuth2 requires [auth] idp):
#   vip verify --config vip.toml --headless-auth

[general]
# Human-readable name for this deployment (appears in reports)
deployment_name = "My Posit Team"

# Additional directories containing custom test cases.
# These are collected and run alongside the built-in test suite.
extension_dirs = []

[connect]
# Set enabled = false to skip all Connect tests.
enabled = true
url = "https://connect.example.com"
# Product version - used by @min_version markers to skip version-specific tests.
# version = "2024.09.0"

# API key for a Connect admin user.
# Prefer setting the VIP_CONNECT_API_KEY environment variable.
# api_key = "..."

# Timeout in seconds for content deployments (default: 1200)
# Increase this for environments with slower package installation.
deploy_timeout = 1200

[workbench]
enabled = true
url = "https://workbench.example.com"
# version = "2024.09.0"

# API key for a Workbench admin user.
# Prefer setting the VIP_WORKBENCH_API_KEY environment variable.
# api_key = "..."
#
# Session capacity testing (requires --interactive-auth).
# If omitted, VIP auto-detects available profiles from the UI and launches one
# session in each of the two smallest, because a deployment that offers a set of
# profiles cannot necessarily run all of them at once. List them explicitly to
# test more than that -- an explicit list is never capped, and session_count
# then applies per profile.
# session_profiles = ["Small", "Medium", "Large"]
# session_count = 3

# Idle session timeout testing.
# Set idle_timeout_minutes to match the deployment's session-timeout-minutes
# from rsession.conf.  Must be ≤ 15 for the idle scenarios to run within
# practical time budgets; values above 15 cause those scenarios to skip.
# idle_timeout_minutes = 5   # must be ≤ 15 for the idle scenarios to run
# idle_grace_seconds = 60    # seconds added on top of idle_timeout_minutes before asserting suspend

# The in-session Chronicle data-collection test is gated by the top-level
# [chronicle] enabled flag (see below); it launches an RStudio session and reads
# Chronicle's raw data chunks to verify it has collected queryable telemetry.
# Base path of Chronicle's data on the Workbench server. Defaults to the
# embedded-Workbench location below; override if chronicle-storage-location is set.
# chronicle_data_path = "/var/lib/rstudio-server/shared-storage/chronicle"

# Additional IDE extensions to validate beyond the built-in Posit Workbench
# integration (which is always checked).  Use extension IDs for VS Code and
# Positron, and package names for JupyterLab.
# [workbench.extensions]
# vscode = ["quarto.quarto", "posit.shiny", "posit.publisher"]
# positron = ["quarto.quarto"]
# jupyterlab = []

# Kubernetes-specific capacity and autoscaling tests.
# Cluster credentials are read from the ambient environment (kubeconfig /
# KUBECONFIG env var / in-cluster service account) — no separate credential
# fields required.  Requires the 'kubernetes' Python package: uv add kubernetes
# [workbench.kubernetes]
# enabled = false
# namespace = "posit-team"
#
# Map node-pool names to resource profile labels for routing verification.
# [workbench.kubernetes.node_pool_profiles]
# "cpu-pool" = "Small"
# "gpu-pool" = "GPU Large"
#
# Hard session ceiling (for capacity limit test).
# max_sessions = 10
#
# Expected CPU limits (cores) per resource profile.
# [workbench.kubernetes.profile_cpu_limit]
# "Small" = 1.0
# "Large" = 4.0
#
# Expected memory limits (GiB) per resource profile.
# [workbench.kubernetes.profile_memory_limit_gib]
# "Small" = 2.0
# "Large" = 8.0

# Git operations testing.
# Validates that users can clone, commit, and push from Workbench sessions
# (RStudio terminal, VS Code terminal, and Positron terminal).
#
# This block is optional. When absent, clone/connectivity scenarios run
# out-of-the-box against a default public repo (auth_method "none", no token
# required); push/commit scenarios auto-skip as read-only. Add this block
# only to (a) override the default clone repo, or (b) enable push scenarios.
#
# auth_method = "https-token": set VIP_GIT_TOKEN in the environment (never in
#   this file); clone and push scenarios run.
#   export VIP_GIT_TOKEN="ghp_..."
# auth_method = "none": anonymous HTTPS clone of a public repo; no token needed;
#   only the clone/connectivity scenarios run (push/commit scenarios skip).
#
# [workbench.git_test]
# clone_url = "https://github.com/org/repo.git"
# auth_method = "https-token"    # "https-token" or "none"; SSH is out of scope

[package_manager]
enabled = true
url = "https://packagemanager.example.com"
# version = "2024.09.0"

# Token for a Package Manager user.
# Prefer setting the VIP_PACKAGE_MANAGER_TOKEN environment variable.
# token = "..."

[auth]
# Authentication provider in use: "password", "ldap", "saml", "oidc", "oauth2"
provider = "password"

# Identity provider for --headless-auth: "keycloak", "okta", "snowflake"
# Only required when provider is "oidc", "saml", or "oauth2".
# For Snowflake Native App deployments, use provider = "oauth2" and
# idp = "snowflake"
# idp = "keycloak"

# Test user credentials.
# Prefer setting VIP_TEST_USERNAME and VIP_TEST_PASSWORD environment variables.
#
# For unattended MFA-protected runs (--headless-auth only), set
# VIP_TEST_TOTP_SECRET to the base32 TOTP seed of a DEDICATED TEST SERVICE
# ACCOUNT. The seed is equivalent to bypassing 2FA — never use a personal
# account's seed and never commit it to source control.
# username = "..."
# password = "..."

[email]
# Set enabled = true if email delivery is configured on Connect.
enabled = false
# smtp_server = "smtp.example.com"

[data_sources]
# External data sources to verify connectivity against.
# Each entry is a name and connection string (or env var reference).
# Example:
# [data_sources.postgres]
# type = "postgres"
# connection_string_env = "VIP_POSTGRES_CONN"

[runtimes]
# Expected R and Python versions.  Used to verify that the correct
# versions are available on Connect and Workbench.
# r_versions = ["4.3.2", "4.4.0"]
# python_versions = ["3.11.8", "3.12.2"]

[monitoring]
# Set enabled = true if monitoring / logging is configured.
enabled = false

[chronicle]
# Set enabled = true when Chronicle usage data collection is configured. This
# single flag gates every Chronicle test:
#   - Connect:   VIP verifies the embedded Chronicle subprocess is running/ready.
#   - Workbench: VIP launches an RStudio session and reads Chronicle's raw data
#                chunks (under [workbench] chronicle_data_path) to verify it has
#                collected queryable telemetry. It checks the two deterministically
#                collected paths: runtime metrics (Prometheus scrape) and user
#                information (Workbench admin API). Enable both in rserver.conf:
#                  chronicle-enabled=1
#                  metrics-enabled=1
#                  workbench-api-admin-enabled=1
#                The session user must be able to read chronicle_data_path.
#                Chronicle restricts data to the owning group by default
#                ([LocalStorage] Access = group); set Access = all in
#                /etc/rstudio/chronicle-local.gcfg (Workbench rewrites the
#                generated chronicle.gcfg on every restart) or add the session
#                user to the owning group.
enabled = false

[performance]
# Thresholds for performance tests.  All time values are in seconds.
# page_load_timeout = 10.0
# download_timeout = 30.0
# p95_response_time = 5.0
# concurrent_requests = 10
# disk_usage_max_pct = 90.0
# memory_available_min_pct = 10.0
#
# Load test settings (used by test_load scenarios).
# load_user_counts = [10, 100, 1000, 10000]
# load_max_connections = 200
# load_success_rate_threshold = 0.95
# load_test_tool = "auto"        # "auto" | "async" | "locust" | "threadpool"
# load_test_duration = 30         # seconds (locust only)
# load_test_spawn_rate = 10       # users/sec (locust only)
#
# Slow VMs: to scale every operation timeout up by 3×, set the env var:
#   VIP_TIMEOUT_SCALE=3 vip verify --connect-url https://connect.example.com
# This multiplies Playwright waits, API polling deadlines, and httpx timeouts
# uniformly. The per-section knobs above set absolute values; the scale
# multiplies on top of whatever effective value (default or configured) is in
# play. Values < 1.0 are valid for speeding up CI smoke checks.

[tls]
# TLS configuration for self-signed or corporate CAs.
#
# Disable TLS certificate verification (equivalent to curl -k).
# Use only in trusted environments; this silently ignores certificate errors.
# Also skips the certificate-validity test scenario (asserting a valid cert
# contradicts disabling verification).  Note: HTTPS-enforcement and TLS-version
# tests are governed by the URL scheme, not this flag — they skip automatically
# when a product URL is http://.
# Overridable on the command line with: vip verify --insecure
# insecure = false
#
# Path to a custom CA certificate bundle (PEM).  Useful for self-signed or
# corporate CAs.  For Playwright tests, sets NODE_EXTRA_CA_CERTS before
# launching Chromium (Chromium-level trust only).
# Overridable on the command line with: vip verify --ca-bundle /path/to/ca.pem
# ca_bundle = "/etc/ssl/corp-ca.pem"
#
# Fail the certificate-validity scenario if a certificate expires within this
# many days, even though the handshake itself still succeeds.  Catches
# renewals that were missed before they cause an outage.  Not checked when
# insecure = true (see above -- that scenario is skipped entirely).
# cert_expiry_warning_days = 30

[proxy]
# Outbound-proxy configuration for hosts that reach Posit deployments through a
# forward proxy. This covers VIP's core HTTP egress: the product API clients
# (Connect/Workbench/Package Manager), the auth and URL-probe requests, and the
# Playwright browser login. Without it, the API clients would silently ignore
# HTTP_PROXY/HTTPS_PROXY (httpx disables env-proxy resolution when a custom
# transport is used) while the browser and probe paths honored it -- a split
# that makes the Connect API-key flow fail behind a proxy.
#
# By default (this whole section omitted) VIP reads the ambient environment --
# HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY (upper- or lowercase) -- exactly
# as httpx does, and the environment variables cover every HTTP request VIP makes.
# They cannot cover the raw-socket TLS handshake probes (the SSL and HTTPS test
# suites, and the listener check behind scheme resolution) -- those open a TCP
# connection directly and have no proxy to speak through, so on a host with no
# direct route out they will fail regardless of proxy configuration.
# Set values here only to override that. (One convenience beyond httpx: if only
# HTTP_PROXY is set -- a single forward proxy used as the sole outbound tunnel --
# VIP routes https through it too via CONNECT rather than sending it direct the
# way httpx would. An explicit HTTPS_PROXY/ALL_PROXY wins.)
#
# Scope note: on a `vip verify` run VIP reconciles the test subprocess's
# environment with the values here, so an explicit url/no_proxy (or the lone
# HTTP_PROXY promotion above) applies uniformly -- the product API clients, the
# auth/probe requests, the browser login, AND the environment-honoring paths in
# the suites (some reachability probes, the performance/load engine). The one
# exception is the raw-socket TLS handshake checks (the SSL and HTTPS suites, and
# the listener check behind scheme resolution): they open a TCP connection
# directly and have no proxy to speak through, so on a host with no direct route
# out they fail regardless. (`vip status`/`vip cleanup` run in-process and honor
# this config directly.)
#
# Setup note: `vip install` reads no config file, so its Playwright Chromium
# download honors only the proxy environment variables. Export HTTPS_PROXY
# before running it -- a proxy configured only here cannot reach that download.
#
# Note on the CLI flags: --proxy/--no-proxy only apply when you pass product
# URLs directly (vip verify --connect-url ...), because they are woven into the
# config VIP generates for that run. On any run that loads a config file -- this
# one, whether via --config or found as ./vip.toml -- they have nothing to write
# into and VIP warns that it ignored them. Configure the proxy here instead, or
# set HTTP_PROXY/HTTPS_PROXY/NO_PROXY in the environment.
#
# Explicit proxy for all traffic. Overrides the environment -- including its
# NO_PROXY, which is NOT merged in, so repeat any bypass hosts under no_proxy.
# url = "http://proxy.corp.example:8080"
#
# Hosts to reach directly, bypassing the proxy (same semantics as NO_PROXY:
# a leading dot / bare domain matches subdomains).
# no_proxy = ["localhost", "127.0.0.1", ".internal.example.com"]
#
# Set enabled = false to force every request direct, ignoring any proxy
# environment variables. On a `vip verify` run this is enforced for the whole
# run -- VIP strips the proxy variables from the test subprocess too, so the
# environment-honoring probes and load engine also go direct.
# enabled = true
#
# Set trust_env = false to ignore proxy environment variables without setting an
# explicit url (has no effect when url is set). Default true.
# trust_env = true

[security]
# Set enabled = true to run security-policy compliance tests.
policy_checks_enabled = false