A Production TOML Baseline for Selenium Grid 4

A production Selenium Grid TOML configuration should make topology, trust, capacity, and browser identity explicit. It should not be a transcript of every default. Start from the options whose drift would change scheduling or security, validate them against the exact Selenium Server artifact being deployed, and keep runtime secrets outside ordinary source control.

The baseline below uses Hub and Node roles because their ownership is easy to review: the Hub contains the user-facing and scheduling components, while Nodes advertise and execute browser slots. The same discipline applies to Standalone or fully distributed roles, but their component endpoints and startup order differ.

Define the startup contract before the file

The official Grid configuration help recommends querying the Selenium Server artifact itself because executable help reflects the options that artifact accepts. Record the exact server artifact or container digest, Java runtime, component role, config checksum, public Grid URL, internal Hub URL, and secret revision in deployment metadata.

Run java -jar selenium-server.jar info config and the relevant role's --help during image build or release validation. Fail promotion when a required key is no longer recognized. Documentation is the design reference; executable help is the compatibility check for the binary actually shipped.

Keep Hub responsibilities explicit

This Hub template fixes the public listener, internal registration secret, client authentication, queue policy, and machine-readable logging. Values beginning with RENDER_ are tokens for the deployment system. Selenium does not promise shell-style interpolation inside TOML, so the rendered file must contain final values before startup.

[server]
port = 4444
registration-secret = "RENDER_GRID_REGISTRATION_SECRET"

[router]
username = "RENDER_GRID_USERNAME"
password = "RENDER_GRID_PASSWORD"

[sessionqueue]
session-request-timeout = 180
session-request-timeout-period = 10
session-retry-interval = 50
sessionqueue-batch-size = 12

[logging]
structured-logs = true
plain-logs = false
tracing = true

The queue numbers are an illustrative coherent set, not universal production recommendations. Timeout and timeout-check period are seconds, while retry interval is milliseconds. Derive them from measured startup distributions, job cancellation budgets, and Distributor pressure. The dedicated queue-tuning process should own changes rather than allowing each incident to add another arbitrary delay.

Router authentication is appropriate at the user-facing Grid boundary, but credentials in a rendered file still need strict filesystem permissions and rotation. Prefer a deployment mechanism that writes the file into a protected runtime volume and removes it with the workload.

Make Node capacity deterministic

The Node template disables discovery, caps concurrent sessions, and defines one browser slot type. The driver executable and stereotype must agree with the image or host that receives this file.

[server]
port = 5555
registration-secret = "RENDER_GRID_REGISTRATION_SECRET"

[node]
detect-drivers = false
max-sessions = 2
session-timeout = 300
grid-url = "https://grid.example.internal"

[[node.driver-configuration]]
display-name = "Linux Chrome"
max-sessions = 2
webdriver-executable = "/opt/selenium/drivers/chromedriver"
stereotype = "{\"browserName\": \"chrome\", \"platformName\": \"linux\"}"

[logging]
structured-logs = true
plain-logs = false
tracing = true

Two layers limit concurrency here: the Node maximum and the driver-configuration maximum. Keep their relationship intentional. Multiple driver configurations may advertise more slots than the Node can execute concurrently, which is valid when the Node-wide limit protects the host, but dashboards must not confuse slot count with simultaneous capacity.

Avoid adding browserVersion unless the deployment guarantees the value and clients need to match it. Returned session capabilities should still be recorded so reports identify the actual browser. A stale exact version in a stereotype can strand every request after an image update.

Connect roles without exposing internal ports

Start the Hub with its config, then start each Node with the matching secret and the Hub address. The exact invocation should be generated by one deployment definition and verified in staging.

java -jar selenium-server.jar hub --config /etc/selenium/hub.toml
java -jar selenium-server.jar node --hub http://grid-hub.internal:4444 --config /etc/selenium/node.toml

The public grid-url is what sessions and UI links should report, while the Node's --hub route is internal connectivity. DNS, proxies, and TLS termination can make those addresses different. Test reachability from the Node namespace rather than from an operator laptop.

Do not publish Node ports, Event Bus ports, or Distributor internals to client networks. The Router or Hub is the client entry point. A firewall mistake that exposes a Node directly can bypass Router authentication and split audit evidence.

Separate registration trust from user authentication

The registration-secret must match on the Hub or Distributor and every Node. It prevents an untrusted Node from registering merely because it can reach the internal component. Rotate it as an infrastructure credential, with a coordinated rollout that does not leave old and new components unable to communicate.

Router username and password protect UI access and new-session calls. The official TOML examples show these values under [router]. They do not replace the registration secret, and neither mechanism replaces HTTPS.

Terminate TLS at a trusted proxy or configure Selenium's supported HTTPS options, then restrict direct HTTP access. Basic-auth credentials are recoverable by anyone who can read unencrypted traffic. Keep browser tests from printing the Grid URL when it contains credentials.

Authenticate Selenium clients deliberately

Java clients can provide Router credentials through Selenium's HTTP client configuration instead of embedding them in a URL. Centralize this construction and obtain secrets from the runtime secret store.

import java.net.URI;
import org.openqa.selenium.UsernameAndPassword;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.HttpCommandExecutor;
import org.openqa.selenium.remote.RemoteWebDriver;
import org.openqa.selenium.remote.http.ClientConfig;

var gridUrl = URI.create(System.getenv("SELENIUM_GRID_URL")).toURL();
var auth = new UsernameAndPassword(
    System.getenv("SELENIUM_GRID_USER"),
    System.getenv("SELENIUM_GRID_PASSWORD"));
var client = ClientConfig.defaultConfig()
    .baseUrl(gridUrl)
    .authenticateAs(auth);
var executor = new HttpCommandExecutor(client);
var driver = new RemoteWebDriver(executor, new ChromeOptions());
try {
  driver.get("https://test.example.internal/");
} finally {
  driver.quit();
}

Redact authorization and environment values from logs. Authentication failures should stop fixture setup immediately, not be retried as if Grid were temporarily out of browser slots.

Treat stereotypes as an API

Every stereotype affects which new-session request can use a slot. Standard properties must have valid values, and custom properties need a vendor prefix. If a custom capability is part of a Node stereotype, clients must include the matching value as documented in the Grid CLI guidance.

Maintain a small contract test for each offered stereotype. The test creates a session through the public Router, asserts returned browser and platform capabilities, executes a command, and quits. Run it after configuration changes, driver changes, image promotion, and Node replacement.

Do not hand-edit stereotypes independently across nominally identical Nodes. Generate them from one reviewed source and compare config checksums in inventory. Otherwise a request can succeed only on a subset of a pool and appear flaky.

Design logging and tracing for correlation

Structured logs make fields such as trace id, span id, event name, and attributes searchable. Tracing must remain enabled for Grid event logging. Route logs to a collector with component identity, deployment revision, and config checksum added outside the message when necessary.

Do not turn FINE logging on permanently without reviewing volume and sensitive fields. Use normal operational logging, retain warnings and errors, and raise detail for a bounded incident window. Browser URLs, capabilities, and exception data can contain secrets or customer-like test data.

Record WebDriver session id in the test report. That identifier is the practical join key between client evidence, Grid logs, Node activity, and browser artifacts. A later tracing layer can resolve one session to the relevant request traces.

Validate health as a sequence

First check the Hub's /status response through the same public route clients use. Next confirm that expected Nodes are registered, UP, and advertising the intended stereotypes. Then create one session for every contract, execute a simple command, and delete the session. Finally verify the slot becomes free and no browser or driver process remains.

A green status endpoint alone does not prove browser readiness. It can coexist with a registration-secret mismatch, missing driver executable, impossible stereotype, or failed browser startup. Readiness should include the smallest real session flow that exercises matching and teardown.

During rolling maintenance, drain Nodes before stopping them. Existing sessions should complete within policy, while new sessions route elsewhere. Abrupt shutdown makes the Session Map, queue, and test clients discover the failure at different times.

Diagnose configuration failures by ownership

A Node that never registers points to Hub address, Event Bus connectivity, DNS, TLS, or registration-secret mismatch. A registered Node with no expected slot points to driver discovery, driver configuration, executable permissions, or malformed stereotype JSON. A queued request with free slots points first to capability matching.

Authentication errors at the Router are client-boundary failures. Session creation reaching a Node and then failing belongs to driver or browser startup. Commands failing after a session exists belong to routing, Node health, browser behavior, or the application. Preserve the last successful boundary instead of responding to every case with a larger timeout.

If an option appears ignored, inspect the rendered TOML, file path, startup arguments, executable help, and startup logs. A valid TOML file can still place a valid key under the wrong section. Treat unknown or shadowed configuration as a release failure.

Production baseline checklist

• Pin the Selenium Server artifact or container by an immutable reference.
• Validate keys with info config and role-specific help.
• Render final secrets before startup; do not assume TOML interpolation.
• Use one matching registration secret across trusted components.
• Protect the Router with authentication and HTTPS.
• Keep internal component and Node ports off client networks.
• Disable driver detection where deterministic slots are required.
• Keep Node-wide and driver-specific concurrency limits intentional.
• Contract-test every advertised stereotype through the public endpoint.
• Enable structured logs and tracing with controlled retention.
• Record config checksum, deployment revision, and session id.
• Drain Nodes and verify teardown during rolling changes.

Promote configuration as executable infrastructure

The decisive baseline is not the longest TOML file. It is the smallest reviewed configuration that fixes trust, entry points, capacity, browser identity, and evidence, then proves those decisions with a real session. Render secrets safely, validate against the exact artifact, and reject drift before traffic arrives. Grid behavior then changes through an observable release process instead of through invisible defaults.