How to use this image

All examples in this guide use the public image. If you've mirrored the repository for your own use (for example, to your Docker Hub namespace), update your commands to reference the mirrored image instead of the public one.

For example:

• Public image: dhi.io/selenium-node-chromium:<tag>
• Mirrored image: <your-namespace>/dhi-selenium-node-chromium:<tag>

For the examples, you must first use docker login dhi.io to authenticate to the registry to pull the images.

What's included in this selenium-node-chromium image

This Docker Hardened Selenium Node image runs the Node role of a Selenium Grid and ships Chromium with chromedriver as its browser. The Node receives WebDriver session requests routed from a Selenium Hub, spawns a chromedriver subprocess per session, and drives Chromium for the lifetime of that session. It is the canonical browser node for arm64 Grids (where Google Chrome is not distributed) and a drop-in alternative to selenium/node-chrome on amd64.

The image ships:

• The selenium-server JAR (the same artifact used by the official Selenium project) built from source with Bazel.
• Chromium and chromedriver from the Debian trixie apt sources (trixie/main plus the trixie-security channel).
• An entrypoint script at /usr/local/bin/selenium-node. The script is a port of upstream selenium/node-chromium's start-selenium-node.sh that maps upstream's SE_* environment variables (node host/port, max sessions, timeouts, drain count, TLS, tracing, JVM options) onto selenium-server node flags, so an existing selenium/node-chromium configuration carries over. It also reads SE_HUB_HOST/SE_HUB_PORT (mapped to --grid-url), which upstream ignores.

Two functional differences from upstream:

1. No VNC / Xvfb / fluxbox stack. The image has no X server, so WebDriver clients must request headless mode (for example --headless=new in goog:chromeOptions); upstream's Xvfb also allows headful sessions. The upstream supervisord + x11vnc + noVNC + fluxbox debugging stack is intentionally omitted. See overview.md for the rationale.
2. No bundled Prometheus metrics exporter. Matches dhi/selenium-hub's same divergence.

Run the selenium-node-chromium container

A Node by itself does nothing useful: it must register with a Hub. The simplest deployment runs the Hub and at least one Node on the same Docker network. See Hub and Node with Docker Compose below for a complete example.

To start a Node manually, point it at a running Hub via SE_EVENT_BUS_* and SE_HUB_*:

docker run -d \
  --name chromium-node \
  --network selenium-grid \
  -p 5555:5555 \
  -e SE_EVENT_BUS_HOST=selenium-hub \
  -e SE_EVENT_BUS_PUBLISH_PORT=4442 \
  -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 \
  -e SE_HUB_HOST=selenium-hub \
  -e SE_HUB_PORT=4444 \
  dhi.io/selenium-node-chromium:<tag>

The Node is operational as soon as the log contains a line that looks like:

Node has been added

Confirm registration by querying the Hub's /status endpoint and looking for the new Node in value.nodes:

curl -s http://localhost:4444/status | python3 -c "import json,sys; print(len(json.load(sys.stdin)['value']['nodes']))"

Hub and Node with Docker Compose

The following compose.yml starts a Hub alongside a single Chromium Node. The Node connects back to the Hub over the shared Docker network.

services:
  selenium-hub:
    image: dhi.io/selenium-hub:<tag>
    container_name: selenium-hub
    ports:
      - "4442:4442"
      - "4443:4443"
      - "4444:4444"

  chromium-node:
    image: dhi.io/selenium-node-chromium:<tag>
    depends_on:
      - selenium-hub
    environment:
      SE_EVENT_BUS_HOST: selenium-hub
      SE_EVENT_BUS_PUBLISH_PORT: "4442"
      SE_EVENT_BUS_SUBSCRIBE_PORT: "4443"
      SE_HUB_HOST: selenium-hub
      SE_HUB_PORT: "4444"
      SE_NODE_MAX_SESSIONS: "1"

Start both services:

docker compose up -d

Point your WebDriver client at http://localhost:4444/wd/hub (or http://localhost:4444 for W3C-style clients). The Grid UI at http://localhost:4444/ui⁠ shows the registered Node and an available chromium slot.

Scaling: multiple Nodes against a single Hub

To run multiple Nodes on the same host, scale the compose service — each replica gets its own identity on the compose network, so no per-replica ports are needed. (Nodes started with docker run and published host ports instead need a distinct port and SE_NODE_HOST each.)

docker compose up -d --scale chromium-node=4

Each replica registers independently and the Hub round-robins sessions across them up to SE_NODE_MAX_SESSIONS slots per Node.

Configuration reference

The entrypoint script maps the following environment variables to Node CLI flags. All variables are optional; the defaults shown are the values baked into the image.

Image variants

Docker Hardened Images come in different variants depending on their intended use.

• Runtime variants are designed to run your application in production. These images are intended to be used either directly or as the FROM image in the final stage of a multi-stage build. These images typically:

  • Run as the nonroot user
  • Do not include a shell or a package manager
  • Contain only the minimal set of libraries needed to run the app

• Build-time variants typically include dev in the variant name and are intended for use in the first stage of a multi-stage Dockerfile. These images typically:

  • Run as the root user
  • Include a shell and package manager
  • Are used to build or compile applications

Migrate to a Docker Hardened Image

If you currently use selenium/node-chromium, swap the image reference:

- image: selenium/node-chromium:latest
+ image: dhi.io/selenium-node-chromium:<tag>

The upstream SE_* variables listed in the configuration reference above carry over unchanged; variables outside that set (for example SE_NODE_STEREOTYPE or SE_BROWSER_BINARY_LOCATION) are not mapped by this entrypoint. The image additionally reads a few variables upstream ignores (for example SE_HUB_HOST/SE_HUB_PORT, mapped to --grid-url). The functional differences (no VNC, no Prometheus exporter, no supervisord process stack) are described in overview.md and at the top of this guide.

Troubleshooting migration

General debugging

The runtime image contains bash but does not include coreutils, curl, a package manager, or broader debugging tooling. For more thorough debugging use Docker Debug⁠ to attach to running containers.

Permissions

By default image variants intended for runtime run as a nonroot user. Ensure that mounted directories (TLS material, heap-dump targets) are readable by uid 65532.

Privileged ports

Non-dev hardened images run as a nonroot user by default. As a result, applications in these images can't bind to privileged ports (below 1024) when running in Kubernetes or in Docker Engine versions older than 20.10. The Node's default port 5555 is well above 1024 so this rarely matters.

Entry point

The runtime image's entrypoint is /usr/local/bin/selenium-node. Override it with --entrypoint only if you need to inspect the container manually; for normal operation the entrypoint script is what consumes the SE_* environment contract and starts the JVM in node mode.