Component Startup and Lifecycle

Relevant source files

• .gitignore
• Base/check-grid.sh
• Distributor/start-selenium-grid-distributor.sh
• EventBus/start-selenium-grid-eventbus.sh
• Hub/start-selenium-grid-hub.sh
• NodeBase/generate_config
• NodeBase/start-selenium-node.sh
• NodeDocker/start-selenium-grid-docker.sh
• Router/start-selenium-grid-router.sh
• SessionQueue/start-selenium-grid-session-queue.sh
• Sessions/start-selenium-grid-sessions.sh
• Standalone/start-selenium-standalone.sh
• StandaloneDocker/start-selenium-grid-docker.sh
• Video/Dockerfile
• Video/video.sh
• Video/video_graphQLQuery.sh
• charts/selenium-grid/configs/distributor/distributorProbe.sh
• charts/selenium-grid/configs/node/nodeGridUrl.sh
• charts/selenium-grid/configs/node/nodePreStop.sh
• charts/selenium-grid/configs/node/nodeProbe.sh
• charts/selenium-grid/configs/router/routerProbe.sh
• tests/CDPTests/bootstrap.sh

This page documents the startup sequence, initialization patterns, and lifecycle management of Selenium Grid components in Docker containers. It covers how components configure themselves from environment variables, perform initialization tasks, start their Java processes, and handle graceful shutdown scenarios.

For information about environment variable configuration and their effects, see Environment Variables Reference. For details on configuration file generation, see Configuration File Generation.

Startup Sequence Overview

All Selenium Grid components follow a consistent startup pattern implemented through shell scripts that prepare the environment, process configuration, and launch the Java-based Selenium server process.

Sources: Standalone/start-selenium-standalone.sh1-228 NodeBase/start-selenium-node.sh1-226 Hub/start-selenium-grid-hub.sh1-201

Component-Specific Startup Scripts

Each Grid component type has its own startup script that handles component-specific initialization requirements:

Component	Startup Script	Java Command
Standalone	start-selenium-standalone.sh	java ... standalone
Hub	start-selenium-grid-hub.sh	java ... hub
Router	start-selenium-grid-router.sh	java ... router
Distributor	start-selenium-grid-distributor.sh	java ... distributor
Session Queue	start-selenium-grid-session-queue.sh	java ... sessionqueue
Sessions Map	start-selenium-grid-sessions.sh	java ... sessions
Event Bus	start-selenium-grid-eventbus.sh	java ... event-bus
Browser Node	start-selenium-node.sh	java ... node

Sources: Standalone/start-selenium-standalone.sh218 Hub/start-selenium-grid-hub.sh199 Router/start-selenium-grid-router.sh195 Distributor/start-selenium-grid-distributor.sh219

Environment Variable Processing

All startup scripts use a common pattern for processing environment variables into Selenium command-line options through the append_se_opts function:

The append_se_opts function handles option deduplication and provides logging for configuration transparency:

Sources: Standalone/start-selenium-standalone.sh22-39 NodeBase/start-selenium-node.sh25-42 Hub/start-selenium-grid-hub.sh8-25

Audio System Initialization

Browser node components require audio system setup for proper media handling in tests. This initialization occurs early in the startup sequence:

Sources: NodeBase/start-selenium-node.sh10-18 Standalone/start-selenium-standalone.sh12-20

Configuration File Generation

Components that support dynamic configuration generation call the generate_config script when GENERATE_CONFIG=true:

Sources: Standalone/start-selenium-standalone.sh139-143 NodeBase/start-selenium-node.sh136-140 Sessions/start-selenium-grid-sessions.sh99-102

Dependency Validation

Distributed Grid components validate that required dependencies are available before startup:

Components exit with error codes if required dependencies are not configured:

Sources: Router/start-selenium-grid-router.sh27-55 Distributor/start-selenium-grid-distributor.sh31-73 NodeBase/start-selenium-node.sh48-61

TLS Configuration

When SE_ENABLE_TLS=true, components configure SSL/TLS settings for secure communication:

Sources: Standalone/start-selenium-standalone.sh102-125 Router/start-selenium-grid-router.sh92-115 NodeBase/start-selenium-node.sh107-130

OpenTelemetry Tracing Setup

Components conditionally enable distributed tracing when SE_ENABLE_TRACING=true and SE_OTEL_EXPORTER_ENDPOINT is configured:

Sources: Standalone/start-selenium-standalone.sh154-181 Router/start-selenium-grid-router.sh138-165 Distributor/start-selenium-grid-distributor.sh161-188

Java Process Launch

All components conclude their startup by launching the Selenium server JAR with accumulated options:

Example final command structure:

Sources: Standalone/start-selenium-standalone.sh213-227 NodeBase/start-selenium-node.sh218-225 Hub/start-selenium-grid-hub.sh196-200

Health Check and Probe System

Components implement health checking through probe scripts that verify component readiness and operational status:

Node Startup Probe

The nodeProbe.sh script verifies node registration with the Grid:

1. Queries local node /status endpoint for NODE_ID
2. Queries Grid GraphQL endpoint to confirm node registration
3. Exits successfully when node appears in Grid

Sources: charts/selenium-grid/configs/node/nodeProbe.sh30-80

Grid Component Probes

Router and Distributor probes use GraphQL queries to assess component health:

Sources: charts/selenium-grid/configs/router/routerProbe.sh20-28 charts/selenium-grid/configs/distributor/distributorProbe.sh20-44

Graceful Shutdown

The nodePreStop.sh script implements graceful node shutdown by draining active sessions before termination:

The preStop script supports two strategies controlled by SE_NODE_PRESTOP_WAIT_STRATEGY:

• deployment (default): Drains node and waits for sessions to complete
• job: Waits for Java process termination

Sources: charts/selenium-grid/configs/node/nodePreStop.sh12-115

Error Handling and Heap Dumps

Components configure heap dump collection for troubleshooting when SE_JAVA_HEAP_DUMP=true:

Sources: Standalone/start-selenium-standalone.sh199-205 NodeBase/start-selenium-node.sh204-210 Hub/start-selenium-grid-hub.sh182-188