Skip to main content

Install managed services and tools

Use these steps for the web, Grid, healing, reporting, and cloud-tunnel services SHAFT can own locally. Every install follows the shared review and approve flow; policy options and exit codes are in the infrastructure reference.

Install managed Selenium Grid​

Not in a published release yet

The SELENIUM_GRID provider is available on SHAFT_ENGINE main after engine PR #5042. Use these commands with a source build until a containing SHAFT release is published.

Use this profile when you want SHAFT to own a local Selenium Grid compose project. Docker 26.1.4+ is a host prerequisite. SHAFT diagnoses Docker; it does not install the engine or daemon.

The release plan binds image tag 4.47.0-20260808 for selenium/hub, selenium/node-chrome, selenium/node-edge, and selenium/node-firefox. The compose project name is shaft-selenium-grid. CLI planning uses the release defaults: hub port 4444, one Chrome replica, zero Edge replicas, and zero Firefox replicas. Bind a different port or replica count through Java selection components such as port_4445 and chrome_2. Those tokens are not CLI flags.

SHAFT never sets container_name and never adopts an unknown compose project or port.

shaft-cli setup status --profile SELENIUM_GRID --mode MANAGED
shaft-cli setup plan \
  --profile SELENIUM_GRID \
  --mode MANAGED \
  --output /absolute/path/selenium-grid-plan.json
shaft-cli setup install \
  --plan /absolute/path/selenium-grid-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup verify --profile SELENIUM_GRID --mode MANAGED
shaft-cli setup start \
  --plan /absolute/path/selenium-grid-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup logs --profile SELENIUM_GRID
shaft-cli setup stop \
  --plan /absolute/path/selenium-grid-plan.json \
  --approve sha256:<reviewed-digest>

start brings up only the owned shaft-selenium-grid project and accepts the hub when /wd/hub/status is healthy. stop runs compose down for that project only.

Install managed Healenium​

Not in a published release yet

The HEALENIUM provider is available on SHAFT_ENGINE main after engine PR #5044. Use these commands with a source build until a containing SHAFT release is published.

Use this profile when tests need a local Healenium backend. Docker 26.1.4+ is a host prerequisite. SHAFT diagnoses Docker; it does not install the engine or daemon. The release plan pins healenium/hlm-backend:3.4.6, healenium/hlm-selector-imitator:1.4, and postgres:15.5-alpine in compose project shaft-healenium. CLI defaults are backend port 7878 and imitator port 8000. Bind different ports through Java selection components backend_7879 and imitate_8001; the two ports must differ. Those tokens are not CLI flags.

shaft-cli setup status --profile HEALENIUM --mode MANAGED
shaft-cli setup plan \
  --profile HEALENIUM \
  --mode MANAGED \
  --output /absolute/path/healenium-plan.json
shaft-cli setup install \
  --plan /absolute/path/healenium-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup verify --profile HEALENIUM --mode MANAGED
shaft-cli setup start \
  --plan /absolute/path/healenium-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup logs --profile HEALENIUM
shaft-cli setup stop \
  --plan /absolute/path/healenium-plan.json \
  --approve sha256:<reviewed-digest>

Point SHAFT.Properties.healenium at localhost and the reviewed backend port. See self-healing locators for the opt-in engine property.

Install managed ReportPortal​

Not in a published release yet

The REPORT_PORTAL provider is available on SHAFT_ENGINE main after engine PR #5046. Use these commands with a source build until a containing SHAFT release is published.

Use this profile only for local development. SHAFT owns an official-core ReportPortal compose project named shaft-reportportal and does not start the analyzer. Docker 26.1.4+ is a host prerequisite. SHAFT diagnoses Docker; it does not install the engine or daemon. The CLI default UI port is 8080. Bind a different UI port through Java selection component ui_8081. That token is not a CLI flag.

shaft-cli setup status --profile REPORT_PORTAL --mode MANAGED
shaft-cli setup plan \
  --profile REPORT_PORTAL \
  --mode MANAGED \
  --output /absolute/path/reportportal-plan.json
shaft-cli setup install \
  --plan /absolute/path/reportportal-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup verify --profile REPORT_PORTAL --mode MANAGED
shaft-cli setup start \
  --plan /absolute/path/reportportal-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup logs --profile REPORT_PORTAL
shaft-cli setup stop \
  --plan /absolute/path/reportportal-plan.json \
  --approve sha256:<reviewed-digest>

The stack uses official ReportPortal local-dev defaults. Change those credentials before exposing the UI beyond loopback.

Install managed BrowserStack Local​

Not in a published release yet

The BROWSERSTACK_LOCAL provider is available on SHAFT_ENGINE main after engine PR #5048 and stop-until-dead follow-up #5049. Use these commands with a source build until a containing SHAFT release is published.

Use this profile when cloud sessions need a SHAFT-owned BrowserStack Local tunnel to a private network. The plan pins official BrowserStack Local v8.9 archives for Windows, Linux x64, and macOS. Linux ARM64 has no versioned v8.9 archive; use x64 or a later pin.

shaft-cli setup status --profile BROWSERSTACK_LOCAL --mode MANAGED
shaft-cli setup plan \
  --profile BROWSERSTACK_LOCAL \
  --mode MANAGED \
  --output /absolute/path/browserstack-local-plan.json
shaft-cli setup install \
  --plan /absolute/path/browserstack-local-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup verify --profile BROWSERSTACK_LOCAL --mode MANAGED

Set BROWSERSTACK_ACCESS_KEY in the environment before start. Do not put the key in the plan file or in a checked-in properties example.

shaft-cli setup start \
  --plan /absolute/path/browserstack-local-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup logs --profile BROWSERSTACK_LOCAL
shaft-cli setup stop \
  --plan /absolute/path/browserstack-local-plan.json \
  --approve sha256:<reviewed-digest>

stop waits until the owned process is dead. A later start then cannot race the dying tunnel.

See BrowserStack sessions for direct cloud sessions and the optional SDK module.

Diagnose agent tools​

Not in a published release yet

The AGENT_TOOLS provider is available on SHAFT_ENGINE main after engine PR #5052. Use these commands with a source build until a containing SHAFT release is published.

Use this profile to diagnose host agent prerequisites. JAVA, MAVEN, PYTHON, and NODE stay diagnose-only: Java 25+, Maven 3.9.0+, Python 3.10+, and Node 20+. SHAFT does not install those host tools.

In MANAGED mode the AGENT_CLI action writes a pinned agent-clients.json that detects gh. It does not download vendor CLIs.

shaft-cli setup status --profile AGENT_TOOLS --mode MANAGED
shaft-cli setup plan \
  --profile AGENT_TOOLS \
  --mode MANAGED \
  --output /absolute/path/agent-tools-plan.json
shaft-cli setup install \
  --plan /absolute/path/agent-tools-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup verify --profile AGENT_TOOLS --mode MANAGED

start and stop are unsupported. Install a missing JDK, Maven, Python, or Node yourself, then rerun status or verify.

Install managed Playwright browsers​

Not in a published release yet

The PLAYWRIGHT provider is tracked by engine PR #4922. Use these commands with a source build until a containing SHAFT release is published.

Use the managed profile when local Playwright tests need SHAFT-owned browser payloads. The plan couples Playwright Java 1.62.0 to Chromium revision 1234, Firefox revision 1538, WebKit revision 2336, FFmpeg revision 1011, and the shared Node 24.19.0 owner. Each official archive URL, size, and SHA-256 digest is part of the reviewed release manifest and plan.

Run the shared command sequence. Stop after plan, inspect all five actions and the printed digest, then install that exact plan:

Prepare managed Playwright browsers
shaft-cli setup status --profile PLAYWRIGHT --mode MANAGED
shaft-cli setup plan \
  --profile PLAYWRIGHT \
  --mode MANAGED \
  --output /absolute/path/playwright-plan.json
shaft-cli setup install \
  --plan /absolute/path/playwright-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup verify --profile PLAYWRIGHT --mode MANAGED

SHAFT downloads each archive through the verified artifact store first. It then points Playwright's downloader at a temporary 127.0.0.1 mirror that serves only those verified files. Setup never runs install-deps, sudo, apt, dnf, brew, a GUI installer, or a package-manager elevation flow. Install required host libraries separately when a Linux browser diagnostic reports a missing shared library.

The release accepts Windows x64 or ARM64, Ubuntu 24.04 x64, and macOS 15 on x64 or ARM64. It rejects a different Linux distribution, Ubuntu release, macOS major version, or unsupported architecture instead of substituting a nearby browser build.

Pass --offline to both plan and install to prohibit network access. A warm verified artifact cache or a compatible published receipt can be reused. A cold, incomplete, corrupt, wrong-version, or linked state fails without an outbound fallback or partial final receipt.

Configure the engine to consume the reviewed installation:

src/main/resources/properties/custom.properties
infrastructure.mode=MANAGED
infrastructure.profile=PLAYWRIGHT
infrastructure.cacheDirectory=/absolute/path/shaft-playwright-cache

playwright.connectionMode=local
playwright.channel=
playwright.browserName=chromium
headlessExecution=true

Use an absolute cache directory. For a local session with no channel override, SHAFT validates the compatible receipt and supplies the owned browser root only to the Playwright child process. It does not install a missing browser during driver creation and does not change the parent process environment.

An explicit remote connection, Chromium channel, or existing PLAYWRIGHT_BROWSERS_PATH wins over managed lookup. This keeps caller-owned browser paths and remote endpoints unchanged.

Install managed Lighthouse​

Not released

This workflow depends on SHAFT Engine issue #4884. It is not yet available on SHAFT_ENGINE main or in a published SHAFT release. Keep using the current Lighthouse flow until a release that contains the managed LIGHTHOUSE provider is available.

Install the LIGHTHOUSE profile before a test calls generateLightHouseReport(). SHAFT manages its own Node 24.19.0 and Lighthouse 13.4.1 under the configured tool root. It does not use a global Node or npm installation.

Prepare managed Lighthouse
shaft-cli setup status --profile LIGHTHOUSE
shaft-cli setup plan \
  --profile LIGHTHOUSE \
  --mode MANAGED \
  --output /absolute/path/lighthouse-plan.json
shaft-cli setup install \
  --plan /absolute/path/lighthouse-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup verify --profile LIGHTHOUSE

Stop after plan and review the JSON plus its printed digest before running install. The plan binds the exact Node artifact, Lighthouse package archive, bundled dependency lock, destinations, and policy. Report generation only uses an already verified installation; it never installs a missing toolchain.

For a cold offline install, pass --offline to both plan and install. The SHAFT cache must already contain the verified Node and Lighthouse artifacts and the complete transitive npm cache required by the bundled lock. An already verified managed installation can be reused without those cached downloads. A missing or corrupt entry needed by a cold install fails without network access or a partially published Lighthouse installation.

Use the default SHAFT roots for this preview. The CLI can bind separate custom cache and data roots, but the Browser Actions runtime currently exposes only infrastructure.cacheDirectory and cannot reproduce every such layout.