Docker images for the Selenium Grid Server

The project is made possible by volunteer contributors who have put in thousands of hours of their own time, and made the source code freely available under the Apache License 2.0.

These Docker images come with a handful of tags to simplify its usage, have a look at them in one of our releases.

To get notifications of new releases, add yourself as a "Releases only" watcher.

These images are published to the Docker Hub registry at Selenium Docker Hub.

Community

Do you need help to use these Docker images? Talk to us at https://www.selenium.dev/support/

Contents

<!-- TOC -->

• Community
• Contents
• Quick start
  • Try them out in a ready-to-use GitPod environment!
• Experimental Multi-Arch amd64/aarch64/armhf Images
• Nightly Images
• Dev and Beta Channel Browser Images
  • Dev and Beta Standalone Mode
  • Dev and Beta on the Grid
• Execution modes
  • Standalone
  • Hub and Nodes
  • Fully distributed mode - Router, Queue, Distributor, EventBus, SessionMap and Nodes
• Video recording
• Video recording with dynamic file name based on metadata in tests
• Video recording and uploading
• Dynamic Grid
  • Configuration example
  • Share volumes config of Dynamic Grid container to node browser containers
  • Execution with Hub & Node roles
  • Execution with Standalone roles
  • Using Dynamic Grid in different machines/VMs
  • Execution with Docker Compose
  • Configuring the child containers
  • Video recording, screen resolution, and time zones in a Dynamic Grid
• Deploying to Kubernetes
• Configuring the containers
  • SE_OPTS Selenium Configuration Options
  • SE_JAVA_OPTS Java Environment Options
  • SE_BROWSER_ARGS_* Add arguments for launching browser
  • Node configuration options
  • Node configuration relay commands
  • Setting Sub Path
  • Setting Screen Resolution
  • Grid Url and Session Timeout
  • Session request timeout
  • Increasing session concurrency per container
  • Running in Headless mode
  • Stopping the Node/Standalone after N sessions have been executed
  • Automatic browser leftovers cleanup
  • Mask sensitive information in console logs
  • Secure Connection
• Building the images
• Build the images with specific versions
• Upgrade browser version in the images
• Waiting for the Grid to be ready
  • Adding a HEALTHCHECK to the Grid
  • Using a bash script to wait for the Grid
• Install certificates for Chromium-based browsers
• Alternative method: Add certificates to existing Selenium based images for browsers
• Debugging
  • Using a VNC client
  • Using your browser (no VNC client is needed)
  • Disabling VNC
• Tracing in Grid
• Troubleshooting
  • --shm-size="2g"
  • Headless
  • Mounting volumes to retrieve downloaded files
  • Mounting volumes to retrieve video files
• Stargazers over time

<!-- TOC -->

Quick start

1. Start a Docker container with Firefox

docker run -d -p 4444:4444 -p 7900:7900 --shm-size="2g" selenium/standalone-firefox:4.23.1-20240813

2. Point your WebDriver tests to http://localhost:4444

3. That's it!

4. (Optional) To see what is happening inside the container, head to http://localhost:7900/?autoconnect=1&resize=scale&password=secret.

For more details about visualising the container activity, check the Debugging section.

:point_up: When executing docker run for an image that contains a browser please use the flag --shm-size=2g to use the host's shared memory.

:point_up: Always use a Docker image with a full tag to pin a specific browser and Grid version. See Tagging Conventions for details.

Try them out in a ready-to-use GitPod environment!

---

Experimental Multi-Arch amd64/aarch64/armhf Images

From image tag based 4.21.0 onwards, the architectures supported by this project are as below:

Architecture	Available
x86_64 (aka amd64)	✅
aarch64 (aka arm64/armv8)	✅
armhf (aka arm32/armv7l)	❌

Browser images in multi-arch

The following browsers are available in multi-arch images:

Architecture	Chrome	Chromium	Firefox	Edge
x86_64 (aka amd64)	✅	✅	✅	✅
aarch64 (aka arm64/armv8)	❌	✅	✅	❌
armhf (aka arm32/armv7l)	❌	❌	❌	❌

Note:

• Google does not build Chrome (google-chrome) for Linux/ARM platforms. Hence, the Chrome (node and standalone) images are only available for AMD64. Similarly, Microsoft does not build Edge (microsoft-edge) for Linux/ARM platforms.

• Running an AMD64 image under emulation on an ARM64 platform is not recommended due to performance and stability issues.

• For Linux/ARM use the open source Chromium browser. The Chromium (node and standalone) images are available in multi-arch.

$ docker run --rm -it -p 4444:4444 -p 5900:5900 -p 7900:7900 --shm-size 2g selenium/standalone-chromium:latest

• Mozilla Firefox now is available for Linux/ARM64 via Nightly channel. The Firefox version in ARM64 will be different with the AMD64 until the stable release is available. The Firefox (node and standalone) images are available in multi-arch.

Multi-arch images are tested on CircleCI with resource class Linux/ARM64. See the status below.

History of the multi-arch images

For experimental docker container images, which run on platforms such as the Apple M-series or Raspberry Pi, the repository at seleniumhq-community/docker-seleniarm provided images which are published on the Seleniarm Docker Hub registry.

See issue #1076 for more information on these images.

Now, the fork seleniumhq-community/docker-seleniarm was merged.

Build the multi-arch images locally

We recommend to enable the experimental feature containerd image store in Docker Engine. containerd understands multiplatform images, where a single image tag can refer to different variants covering a range of OS and hardware architectures. It simplifies the process of building, storing, and distributing images across different platforms.

A single command to enable that feature in Docker Engine:

make set_containerd_image_store

To build all the images for multiplatform, run the following command:

PLATFORMS=linux/amd64,linux/arm64 make build

To build the images for a specific platform, run the following command:

PLATFORMS=linux/arm64 make build

By default, without specifying the PLATFORMS variable, the images are built for the linux/amd64 platform.

---

Nightly Images

Nightly images are built on top of the Nightly build on the upstream project Selenium with the latest changes on main branch in this repository. The image tag is nightly. This is not recommended to use images in production. It is only for testing purpose.

$ docker run -d -p 4442-4444:4442-4444 --name selenium-hub selenium/hub:nightly

Dev and Beta Channel Browser Images

To run tests or otherwise work with pre-release browsers, Google, Mozilla, and Microsoft maintain a Dev and Beta release channel for those who need to see what's soon to be released to the general population.

Dev and Beta Standalone Mode

Here are the instructions to run them in Standalone mode:

Chrome Beta:

$ docker run --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-chrome:beta

Chrome Dev:

$ docker run --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-chrome:dev

Firefox Beta:

$ docker run --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-firefox:beta

Firefox Dev:

$ docker run --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-firefox:dev

Edge Beta:

$ docker run --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-edge:beta

Edge Dev:

$ docker run --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-edge:dev

Dev and Beta on the Grid

docker-compose-v3-beta-channel.yml:

# To execute this docker compose yml file use `docker compose -f docker-compose-v3-beta-channel.yml up`
# Add the `-d` flag at the end for detached execution
# To stop the execution, hit Ctrl+C, and then `docker compose -f docker-compose-v3-beta-channel.yml down`
version: "3"
services:
  chrome:
    image: selenium/node-chrome:beta
    shm_size: 2gb
    depends_on:
      - selenium-hub
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443

  edge:
    image: selenium/node-edge:beta
    shm_size: 2gb
    depends_on:
      - selenium-hub
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443

  firefox:
    image: selenium/node-firefox:beta
    shm_size: 2gb
    depends_on:
      - selenium-hub
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443

  selenium-hub:
    image: selenium/hub:latest
    container_name: selenium-hub
    ports:
      - "4442:4442"
      - "4443:4443"
      - "4444:4444"

docker-compose-v3-dev-channel.yml:

# To execute this docker compose yml file use `docker compose -f docker-compose-v3-dev-channel.yml up`
# Add the `-d` flag at the end for detached execution
# To stop the execution, hit Ctrl+C, and then `docker compose -f docker-compose-v3-dev-channel.yml down`
version: "3"
services:
  chrome:
    image: selenium/node-chrome:dev
    shm_size: 2gb
    depends_on:
      - selenium-hub
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443

  edge:
    image: selenium/node-edge:dev
    shm_size: 2gb
    depends_on:
      - selenium-hub
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443

  firefox:
    image: selenium/node-firefox:dev
    shm_size: 2gb
    depends_on:
      - selenium-hub
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443

  selenium-hub:
    image: selenium/hub:latest
    container_name: selenium-hub
    ports:
      - "4442:4442"
      - "4443:4443"
      - "4444:4444"

For more information on the Dev and Beta channel container images, see the blog post on Dev and Beta Channel Browsers via Docker Selenium.

Execution modes

Standalone

Firefox

docker run -d -p 4444:4444 --shm-size="2g"