Environment:SeleniumHQ Selenium Grid Deployment Environment

Knowledge Sources	SeleniumHQ/selenium Grid Documentation
Domains	Infrastructure, Grid, Deployment
Last Updated	2026-02-11 23:00 GMT

Overview

JDK 17 runtime environment with network port allocation, optional Redis/JDBC session storage, and SE_* environment variable configuration for deploying Selenium Grid.

Description

Selenium Grid requires a Java runtime to execute the Grid JAR. The Grid server allocates network ports dynamically (avoiding ephemeral port ranges), supports distributed topologies (Hub+Node, fully distributed), and optionally integrates with Redis or JDBC databases for session map persistence. Docker deployments propagate all `SE_*` environment variables to browser containers automatically.

Usage

Use this environment when deploying Selenium Grid in Standalone, Hub+Node, or fully distributed mode. It is the mandatory prerequisite for running the Grid Bootstrap, Router, Distributor, and Node components.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	Linux recommended for production
Hardware	2+ CPU cores per node	Max sessions defaults to available processor count
RAM	2GB+ per node	More for concurrent sessions
Network	Ports 1024-65535 available	Minimum 5000 free ports recommended; avoids ephemeral range
Network	TCP ports for EventBus	Default: 4442 (publish), 4443 (subscribe)

Dependencies

System Packages

Java Runtime: JDK 17+ (from `java/version.bzl`: `TOOLS_JAVA_VERSION = "17"`)
Browser binaries: Chrome, Firefox, Edge (auto-detected or configured)
Driver binaries: ChromeDriver, GeckoDriver, MSEdgeDriver (auto-managed by Selenium Manager)

Optional Backing Stores

Redis: For distributed session map (`GridRedisClient`)
JDBC Database: For persistent session map (`JdbcSessionMap`)
ZeroMQ: Default event bus implementation (bundled)

Credentials

The following environment variables are used at runtime:

`SE_DEBUG`: Enable verbose FINE-level logging across all Grid components.
`SE_MANAGER_PATH`: Custom path to Selenium Manager binary (optional).
`SE_CACHE_PATH`: Override cache directory for downloaded binaries (default: `~/.cache/selenium`).
`SE_CHROMEDRIVER`: Path to ChromeDriver executable (overrides auto-detection).
`SE_GECKODRIVER`: Path to GeckoDriver executable (overrides auto-detection).
`SE_ROUTER_USERNAME`: Authentication username for Docker-to-Router communication.
`SE_ROUTER_PASSWORD`: Authentication password for Docker-to-Router communication.
`SE_START_XVFB`: Flag for Xvfb availability in container environments.
`SE_START_VNC`: Flag for VNC stream availability.
`SE_START_NO_VNC`: Flag for noVNC web client availability.
`SE_RECORD_VIDEO`: Enable video recording of browser sessions.
`SE_VIDEO_FILE_NAME`: Video output filename (default: "auto").
`SE_SCREEN_WIDTH`: Browser screen resolution width in pixels.
`SE_SCREEN_HEIGHT`: Browser screen resolution height in pixels.

WARNING: Never commit actual values for `SE_ROUTER_USERNAME` or `SE_ROUTER_PASSWORD`.

Quick Install

# Build Grid from source:
bazel build //java/src/org/openqa/selenium/grid:executable-grid

# Run Standalone Grid:
java -jar bazel-bin/java/src/org/openqa/selenium/grid/executable-grid_deploy.jar standalone

# Run Hub:
java -jar selenium-server.jar hub

# Run Node (connecting to Hub):
java -jar selenium-server.jar node --hub http://hub-host:4444

Code Evidence

Port allocation avoidance of ephemeral range from `java/src/org/openqa/selenium/net/PortProber.java:33-34,88`:

private static final int HIGHEST_PORT = 65535;
private static final int START_OF_USER_PORTS = 1024;
// ...
Require.stateCondition(
    ephemeralRange >= 5000,
    "Ephemeral port range too small: %s", ephemeralRange);

Max server threads from `java/src/org/openqa/selenium/grid/server/BaseServerOptions.java:76`:

int maxThreads = Runtime.getRuntime().availableProcessors() * 3;

Default max sessions from `java/src/org/openqa/selenium/grid/node/config/NodeFlags.java:57-61`:

@Parameter(
    names = {"--max-sessions"},
    description =
        "Maximum number of concurrent sessions. Default value is the number "
            + "of available processors.")
public int maxSessions = DEFAULT_MAX_SESSIONS;

Override warning from `java/src/org/openqa/selenium/grid/node/config/NodeFlags.java:67-70`:

description =
    "The # of available processors is the recommended max sessions value (1 browser "
        + "session per processor). Setting this flag to true allows the recommended max "
        + "value to be overwritten. Session stability and reliability might suffer as "
        + "the host could run out of resources."

Docker SE_* variable propagation from `java/src/org/openqa/selenium/grid/node/docker/DockerSessionFactory.java:356-362`:

Map<String, String> seEnvVars = System.getenv();
seEnvVars.entrySet().stream()
    .filter(entry ->
        entry.getKey().startsWith("SE_") || entry.getKey().equalsIgnoreCase("LANGUAGE"))
    .forEach(entry -> envVars.put(entry.getKey(), entry.getValue()));

Common Errors

Error Message	Cause	Solution
`Could not start a new session. No free slots available`	All node slots occupied	Increase `--max-sessions` or add more nodes
`Session stability and reliability might suffer`	`--override-max-sessions` enabled	Keep max-sessions at processor count for stability
`Could not find a matching driver`	Browser/driver not on PATH	Set `SE_CHROMEDRIVER` or enable `--selenium-manager`
`Ephemeral port range too small`	Less than 5000 available ports	Check OS port settings; reduce concurrent sessions

Compatibility Notes

Docker: All `SE_*` environment variables are automatically propagated to browser containers.
Kubernetes: Use `--drain-after-session-count` and `--register-shutdown-on-failure` for pod lifecycle management.
Container VNC: Set `SE_START_VNC=true` and `SE_START_NO_VNC=true` for visual debugging; noVNC port defaults to 7900.
Distributed Mode: Requires ZeroMQ event bus (default) with publish (4442) and subscribe (4443) ports.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment