docs: add RHEL/CentOS installation guide for local mode

[samcofer]

Summary

VIP works on RHEL-based distributions (RHEL, CentOS, Rocky, Alma) in local mode, but the current documentation and setup tooling assume Debian/Ubuntu. Users on RHEL will hit a wall at playwright install --with-deps chromium since Playwright's --with-deps flag only supports Debian/Ubuntu for automatic system dependency installation.

What needs updating

1. Document manual Playwright system dependencies for RHEL

playwright install --with-deps fails on RHEL because it shells out to apt-get. Users need to manually install Chromium's shared library dependencies before running playwright install chromium (without --with-deps).

Minimum required packages (dnf/yum):

dnf install -y nss nspr atk at-spi2-atk cups-libs libdrm \
  libXcomposite libXdamage libXrandr mesa-libgbm pango \
  alsa-lib libxshmfence libXtst

Then install the browser only:

uv run playwright install chromium

2. Update justfile setup recipe

The current setup recipe runs playwright install --with-deps chromium. This should either:

• Detect the OS and adjust the command, or
• Document that --with-deps is Ubuntu-only and point RHEL users to the manual steps

3. Update CLAUDE.md environment setup section

The environment setup block in CLAUDE.md uses --with-deps unconditionally:

uv run playwright install --with-deps chromium

Should note the RHEL alternative.

4. Consider adding an OS-aware setup check

Optional: a vip doctor or vip setup --check command that validates system dependencies are present regardless of distro, rather than relying on Playwright's Debian-only --with-deps.

Context

• The Python codebase itself is fully OS-agnostic (no platform detection, no Debian assumptions in source)
• All subprocess calls are to portable tools (kubectl, quarto, pytest)
• The Docker/K8s mode is unaffected since the container image is Ubuntu-based
• This only affects users running vip verify --local directly on a RHEL host

[samcofer]

Validated on RHEL 9.6 — additional findings

Tested on a fresh RHEL 9.6 (Plow) instance with Python 3.14.4, Workbench 2026.04.0. The original package list in this issue is incomplete and there are two additional problems beyond system deps.

1. Missing package: libxkbcommon

The original dnf install list is not sufficient. After installing all listed packages, Chromium fails at launch:

error while loading shared libraries: libxkbcommon.so.0: cannot open shared object file: No such file or directory

Corrected install command:

dnf install -y nss nspr atk at-spi2-atk cups-libs libdrm \
  libXcomposite libXdamage libXrandr mesa-libgbm pango \
  alsa-lib libxshmfence libXtst libxkbcommon

This pulls in 25 packages total (11 explicit + 14 dependencies including xkeyboard-config, llvm-libs, mesa-dri-drivers, at-spi2-core, avahi-libs, libX11-xcb, libXfixes, libXi, libpciaccess, libwayland-server, llvm-filesystem, mesa-filesystem, spirv-tools-libs).

2. Playwright "unsupported OS" warning

Playwright does not recognize RHEL and downloads a fallback Ubuntu 24.04 build:

BEWARE: your OS is not officially supported by Playwright; downloading fallback build for ubuntu24.04-x64.

This works in practice but should be documented so users aren't alarmed by the warning.

3. VIP error message is misleading on RHEL

When Chromium can't launch (missing system libs), VIP prints:

ERROR: Chromium could not launch because required system libraries are missing on this host. Install them with:

    uv run playwright install --with-deps chromium

This advice doesn't work on RHEL — --with-deps shells out to apt-get and fails. The error message should detect the OS and suggest the correct dnf install command, or at minimum say "On RHEL, see for manual dependency installation."

This is in src/vip/auth.py around the _PLAYWRIGHT_DEPS_HINT constant.

4. Self-signed / private CA certificates — Playwright ignores env vars

Setting SSL_CERT_FILE, REQUESTS_CA_BUNDLE, and NODE_EXTRA_CA_CERTS does not fix Playwright's ERR_CERT_AUTHORITY_INVALID:

ERROR: Headless auth failed during login: Page.goto: net::ERR_CERT_AUTHORITY_INVALID at https://localhost/

Chromium uses NSS for certificate verification, not the system OpenSSL trust store. Env vars only help the Python ssl module and requests/httpx.

For Playwright, the options are:

• Pass ignore_https_errors=True on the browser context (requires a VIP code change — ties into the missing --insecure flag from the earlier review)
• Add the CA to the NSS shared database (certutil -d sql:/etc/pki/nssdb -A -t "C,," -n "My CA" -i /path/to/ca.crt)

Without one of these, --headless-auth and --interactive-auth are broken for any deployment using private CAs.

5. Python httpx/ssl also fails with private CAs

Even with --no-auth (skipping Playwright entirely), tests that make HTTPS calls fail:

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate

This affects httpx, which uses Python's ssl module. The SSL_CERT_FILE env var should help here if it points to a bundle that includes the private CA, but VIP should also support a config-level tls_ca_bundle or tls_verify = false option (as noted in the prior review of this repo).

Test environment

OS:      Red Hat Enterprise Linux 9.6 (Plow)
Python:  3.14.4
VIP:     0.26.7 (installed via `uv pip install posit-vip`)
Target:  Workbench 2026.04.0 on localhost with self-signed cert