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.
Prereleases are happening on a regular basis to get early feedback. This means that all other Selenium components can be currently at a different beta version (e.g. bindings on Beta 2, and Docker images on prerelease Beta 3).
Docker images for Grid 4 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 prereleases, add yourself as a "Releases only" watcher.
Doubts? Questions? Get in touch through the different communication channels available in the Community section.
Looking for Grid 3? Head to the Selenium 3 branch. This branch will be having new browser releases until Grid 4 has had its major release.
Do you need help to use these Docker images? All the contact points for the different Selenium projects can be seen at: https://www.selenium.dev/support/
$ docker run -d -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-firefox:4.0.0-beta-3-prerelease-20210402 # OR $ docker run -d -p 4444:4444 -p 7900:7900 -v /dev/shm:/dev/shm selenium/standalone-firefox:4.0.0-beta-3-prerelease-20210402
Point your WebDriver tests to http://localhost:4444/wd/hub
That's it!
(Optional) To see what is happening inside the container, head to http://localhost:7900 (password is
secret).
More details about visualising the container activity, check the Debugging section.
:point_up: When executing
docker runfor an image that contains a browser please either mount
-v /dev/shm:/dev/shmor use the flag
--shm-size=2gto 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.
Firefox
bash $ docker run -d -p 4444:4444 -v /dev/shm:/dev/shm selenium/standalone-firefox:4.0.0-beta-3-prerelease-20210402
Chrome
bash $ docker run -d -p 4444:4444 -v /dev/shm:/dev/shm selenium/standalone-chrome:4.0.0-beta-3-prerelease-20210402
Opera
bash $ docker run -d -p 4444:4444 -v /dev/shm:/dev/shm selenium/standalone-opera:4.0.0-beta-3-prerelease-20210402
Microsoft Edge
bash $ docker run -d -p 4444:4444 -v /dev/shm:/dev/shm selenium/standalone-edge:4.0.0-beta-3-prerelease-20210402
Note: Only one Standalone container can run on port
4444at the same time.
There are different ways to run the images and create a Grid with a Hub and Nodes, check the following options.
The Hub and Nodes will be created in the same network and they will recognize each other by their container name. A Docker network needs to be created as a first step.
$ docker network create grid $ docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.0.0-beta-3-prerelease-20210402 $ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \ -e SE_EVENT_BUS_PUBLISH_PORT=4442 \ -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 \ -v /dev/shm:/dev/shm \ selenium/node-chrome:4.0.0-beta-3-prerelease-20210402 $ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \ -e SE_EVENT_BUS_PUBLISH_PORT=4442 \ -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 \ -v /dev/shm:/dev/shm \ selenium/node-edge:4.0.0-beta-3-prerelease-20210402 $ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \ -e SE_EVENT_BUS_PUBLISH_PORT=4442 \ -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 \ -v /dev/shm:/dev/shm \ selenium/node-firefox:4.0.0-beta-3-prerelease-20210402 $ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \ -e SE_EVENT_BUS_PUBLISH_PORT=4442 \ -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 \ -v /dev/shm:/dev/shm \ selenium/node-opera:4.0.0-beta-3-prerelease-20210402
When you are done using the Grid, and the containers have exited, the network can be removed with the following command:
# Removes the grid network $ docker network rm grid
The Hub and Nodes will be created on different machines/VMs, they need to know each other's IPs to communicate properly.
Hub - Machine/VM 1
bash $ docker run -d -p 4442-4444:4442-4444 --name selenium-hub selenium/hub:4.0.0-beta-3-prerelease-20210402
Node Chrome - Machine/VM 2
bash $ docker run -d -p 5555:5555 -e SE_EVENT_BUS_HOST= \ -e SE_EVENT_BUS_PUBLISH_PORT=4442 \ -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 \ -e SE_NODE_HOST= \ -v /dev/shm:/dev/shm \ selenium/node-chrome:4.0.0-beta-3-prerelease-20210402
Node Edge - Machine/VM 3
bash $ docker run -d -p 5555:5555 -e SE_EVENT_BUS_HOST= \ -e SE_EVENT_BUS_PUBLISH_PORT=4442 \ -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 \ -e SE_NODE_HOST= \ -v /dev/shm:/dev/shm \ selenium/node-edge:4.0.0-beta-3-prerelease-20210402
Node Firefox - Machine/VM 4
bash $ docker run -d -p 5555:5555 -e SE_EVENT_BUS_HOST= \ -e SE_EVENT_BUS_PUBLISH_PORT=4442 \ -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 \ -e SE_NODE_HOST= \ -v /dev/shm:/dev/shm \ selenium/node-firefox:4.0.0-beta-3-prerelease-20210402
Node Opera - Machine/VM 5
bash $ docker run -d -p 5555:5555 -e SE_EVENT_BUS_HOST= \ -e SE_EVENT_BUS_PUBLISH_PORT=4442 \ -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 \ -e SE_NODE_HOST= \ -v /dev/shm:/dev/shm \ selenium/node-opera:4.0.0-beta-3-prerelease-20210402
Docker Compose is the simplest way to start a Grid. Use the linked resources below, save them locally, and check the execution instructions on top of each file.
docker-compose-v2.yml
docker-compose-v3.yml
To stop the Grid and cleanup the created containers, run
docker-compose down.
docker-compose-v3-swarm.yml
It is possible to start a Selenium Grid with all its components apart. For simplicity, only an example with docker-compose will be provided. Save the file locally, and check the execution instructions on top of it.
docker-compose-v3-full-grid.yml
Tests execution can be recorded by using the
selenium/video:ffmpeg-4.3.1-20210402Docker image. One container is needed per each container where a browser is running. This means if you are running 5 Nodes/Standalone containers, you will need 5 video containers, the mapping is 1-1.
Currently, the only way to do this mapping is manually (either starting the containers manually, or through
docker-compose). We are iterating on this process and probably this setup will be more simple in the future.
The video Docker image we provide is based on the ffmpeg Ubuntu image provided by the jrottenberg/ffmpeg project, thank you for providing this image and simplifying our work :tada:
Notes: - If you have questions or feedback, please use the community contact points shown here. - Please report any bugs through GitHub issues, and provide all the information requested on the template. - Video recording for headless browsers is not supported. - Video recording tends to use considerable amounts of CPU. Normally you should estimate 1CPU per video container, and 1 CPU per browser container. - Videos are stored in the
/videosdirectory inside the video container. Map a local directory to get the videos. - If you are running more than one video container, be sure to overwrite the video file name through the
FILE_NAMEenvironment variable to avoid unexpected results.
This example shows how to start the containers manually:
$ docker network create grid $ docker run -d -p 4444:4444 -p 6900:5900 --net grid --name selenium -v /dev/shm:/dev/shm selenium/standalone-chrome:4.0.0-beta-3-prerelease-20210402 $ docker run -d --net grid --name video -v /tmp/videos:/videos selenium/video:ffmpeg-4.3.1-20210402 # Run your tests $ docker stop video && docker rm video $ docker stop selenium && docker rm selenium
After the containers are stopped and removed, you should see a video file on your machine's
/tmp/videosdirectory.
Here is an example using a Hub and a few Nodes:
docker-compose-v3-video.yml
Grid 4 has the ability to start Docker containers on demand, this means that it starts a Docker container in the background for each new session request, the test gets executed there, and when the test completes, the container gets thrown away.
This execution mode can be used either in the Standalone or Node roles. The "dynamic" execution mode needs to be told what Docker images to use when the containers get started. Additionally, the Grid needs to know the URI of the Docker daemon.
You can save this file locally and name it, for example,
config.toml. ```toml [docker]
configs = [ "selenium/standalone-firefox:4.0.0-beta-3-prerelease-20210402", "{\"browserName\": \"firefox\"}", "selenium/standalone-chrome:4.0.0-beta-3-prerelease-20210402", "{\"browserName\": \"chrome\"}", "selenium/standalone-opera:4.0.0-beta-3-prerelease-20210402", "{\"browserName\": \"operablink\"}", "selenium/standalone-edge:4.0.0-beta-3-prerelease-20210402", "{\"browserName\": \"msedge\"}" ]
docker runinstruction or 172.17.0.1 in the URI below.
url = "http://host.docker.internal:2375"
video-image = "selenium/video:ffmpeg-4.3.1-20210402"
### Execution with Hub & Node rolesThis can be expanded to a full Grid deployment, all components deployed individually. The overall idea is to have the Hub in one virtual machine, and each of the Nodes in separate and more powerful virtual machines.
``` bash $ docker network create grid $ docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.0.0-beta-3-prerelease-20210402 $ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub
-e SE_EVENT_BUS_PUBLISH_PORT=4442
-e SE_EVENT_BUS_SUBSCRIBE_PORT=4443
-v ${PWD}/config.toml:/opt/bin/config.toml
-v /path/on/your/host/machine:/opt/selenium/assets
selenium/node-docker:4.0.0-beta-3-prerelease-20210402
To have the assets saved on your host, please mount your host path to
/opt/selenium/assets.
When you are done using the Grid, and the containers have exited, the network can be removed with the following command:
# Removes the grid network $ docker network rm grid
docker run --rm -ti --name selenium-docker -p 4444:4444 \ -v ${PWD}/config.toml:/opt/bin/config.toml \ -v /path/on/your/host/machine:/opt/selenium/assets \ selenium/standalone-docker:4.0.0-beta-3-prerelease-20210402
To have the assets saved on your host, please mount your host path to
/opt/selenium/assets.
Here is an example using a Hub and a Node:
docker-compose-v3-dynamic-grid.yml
To record your WebDriver session, you need to add a
se:optionssection to your capabilities and inside it, configure the desired settings, for example:
{ "browserName": "firefox", "platformName": "linux", "se:recordVideo": "true", "se:timeZone": "US/Pacific", "se:screenResolution": "1920x1080" }
After running a test, check the path you mounted to the Docker container, (
/path/on/your/host/machine), and you should see videos and session information.
Here are the steps to deploy the Grid 4 to a Kubernetes cluster. ``` bash
$ kubectl apply -f k8s-deployment-full-grid.yaml
$ kubectl expose deployment selenium-router-deployment --type=NodePort --port=4444
$ minikube service selenium-router-deployment --url
$ kubectl get all -l component=selenium-grid-4 ```
Check out the Kubernetes examples on how to deploy selenium hub and nodes on a Kubernetes cluster.
You can pass
SE_OPTSvariable with additional commandline parameters for starting a hub or a node.
$ docker run -d -p 4444:4444 -e SE_OPTS="--log-level FINE" --name selenium-hub selenium/hub:4.0.0-beta-3-prerelease-20210402
You can pass
JAVA_OPTSenvironment variable to java process.
$ docker run -d -p 4444:4444 -e JAVA_OPTS=-Xmx512m --name selenium-hub selenium/hub:4.0.0-beta-3-prerelease-20210402
The Nodes register themselves through the Event Bus. When the Grid is started in its typical Hub/Node setup, the Hub will be the one acting as the Event Bus, and when the Grid is started with all its five elements apart, the Event Bus will be running on its own.
In both cases, it is necessary to tell the Node where the Event Bus is, so it can register itself. That is the purpose of the
SE_EVENT_BUS_HOST,
SE_EVENT_BUS_PUBLISH_PORTand
SE_EVENT_BUS_SUBSCRIBE_PORTenvironment variables.
Here is an example with the default values of these environment variables:
$ docker run -d --e SE_EVENT_BUS_HOST= -e SE_EVENT_BUS_PUBLISH_PORT=4442 -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 -v /dev/shm:/dev/shm selenium/node-chrome:4.0.0-beta-3-prerelease-20210402
By default, nodes start with a screen resolution of 1360 x 1020 with a color depth of 24 bits and a dpi of 96. These settings can be adjusted by specifying
SCREEN_WIDTH,
SCREEN_HEIGHT,
SCREEN_DEPTH, and/or
SCREEN_DPIenvironmental variables when starting the container.
docker run -d -e SCREEN_WIDTH=1366 -e SCREEN_HEIGHT=768 -e SCREEN_DEPTH=24 -e SCREEN_DPI=74 selenium/standalone-firefox
In some use cases you might need to set the Grid url to the Node, for example if you'd like to access the CDP endpoint. You can do that through the
SE_NODE_GRID_URLenvironment variable.
Grid has a default session timeout of 300 seconds, where the session can be on a stale state until it is killed. You can use
SE_NODE_SESSION_TIMEOUTto overwrite that value in seconds.
By default, only one session is configured to run per container through the
SE_NODE_MAX_SESSIONSenvironment variable. It is possible to increase that number up to the maximum available processors, this is because more stability is achieved when one container/browser has 1 CPU to run.
However, if you have measured performance and based on that, you think more sessions can be executed in each container, you can override the maximum limit by setting both
SE_NODE_MAX_SESSIONSto a desired number and
SE_NODE_OVERRIDE_MAX_SESSIONSto
true. Nevertheless, running more browser sessions than the available processors is not recommended since you will be overloading the resources.
Overriding this setting has a undesired side effect when video recording is enabled, since more than one browser session might be captured in the same video.
Firefox, Chrome, Opera and Edge support running tests in the headless mode. When using headless mode, there's no need for the Xvfb server to be started.
To avoid starting the server you can set the
START_XVFBenvironment variable to
false(or any other value than
true), for example:
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub -e SE_EVENT_BUS_PUBLISH_PORT=4442 -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 -e START_XVFB=false -v /dev/shm:/dev/shm selenium/node-chrome
For more information, see this GitHub issue.
Clone the repo and from the project directory root you can build everything by running:
$ VERSION=local make build
If you need to configure environment variable in order to build the image (http proxy for instance), simply set an environment variable
BUILD_ARGSthat contains the additional variables to pass to the docker context (this will only work with docker >= 1.9)
$ BUILD_ARGS="--build-arg http_proxy=http://acme:3128 --build-arg https_proxy=http://acme:3128" make build
Note: Omitting
VERSION=localwill build the images with the released version but replacing the date for the current one.
It is a good practice to check first if the Grid is up and ready to receive requests, this can be done by checking the
/wd/hub/statusendpoint.
A Grid that is ready, composed by a hub and two nodes, could look like this:
{ "value": { "ready": true, "message": "Selenium Grid ready.", "nodes": [ { "id": "6c0a2c59-7e99-469d-bbfc-313dc638797c", "uri": "http:\u002f\u002f172.19.0.3:5555", "maxSessions": 4, "stereotypes": [ { "capabilities": { "browserName": "firefox" }, "count": 4 } ], "sessions": [ ] }, { "id": "26af3363-a0d8-4bd6-a854-2c7497ed64a4", "uri": "http:\u002f\u002f172.19.0.4:5555", "maxSessions": 4, "stereotypes": [ { "capabilities": { "browserName": "chrome" }, "count": 4 } ], "sessions": [ ] } ] } }
The
"ready": truevalue indicates that the Grid is ready to receive requests. This status can be polled through a script before running any test, or it can be added as a HEALTHCHECK when the docker container is started.
The script check-grid.sh, which is included in the images, can be used to poll the Grid status.
This example checks the status of the Grid every 15 seconds, it has a timeout of 30 seconds when the check is done, and it retries up to 5 times until the container is marked as unhealthy. Please use adjusted values to fit your needs, (if needed) replace the
--hostand
--portparameters for the ones used in your environment.
$ docker network create grid $ docker run -d -p 4444:4444 --net grid --name selenium-hub \ --health-cmd='/opt/bin/check-grid.sh --host 0.0.0.0 --port 4444' \ --health-interval=15s --health-timeout=30s --health-retries=5 \ selenium/hub:4.0.0-beta-3-prerelease-20210402 $ docker run -d --net grid -e HUB_HOST=selenium-hub -v /dev/shm:/dev/shm selenium/node-chrome:4.0.0-beta-3-prerelease-20210402 $ docker run -d --net grid -e HUB_HOST=selenium-hub -v /dev/shm:/dev/shm selenium/node-edge:4.0.0-beta-3-prerelease-20210402 $ docker run -d --net grid -e HUB_HOST=selenium-hub -v /dev/shm:/dev/shm selenium/node-firefox:4.0.0-beta-3-prerelease-20210402 $ docker run -d --net grid -e HUB_HOST=selenium-hub -v /dev/shm:/dev/shm selenium/node-opera:4.0.0-beta-3-prerelease-20210402
Note: The
\line delimiter won't work on Windows based terminals, try either
^or a backtick.
The container health status can be checked by doing
docker psand verifying the
(healthy)|(unhealthy)status or by inspecting it in the following way:
$ docker inspect --format='{{json .State.Health.Status}}' selenium-hub "healthy"
A common problem known in docker is that a running container does not always mean that the application inside it is ready. A simple way to tackle this is by using a "wait-for-it" script, more information can be seen here.
The following script is an example of how this can be done using bash, but the same principle applies if you want to do this with the programming language used to write the tests.
#!/bin/bash # wait-for-grid.shset -e
cmd="[email protected]"
while ! curl -sSL "http://localhost:4444/wd/hub/status" 2>&1
| jq -r '.value.ready' 2>&1 | grep "true" >/dev/null; do echo 'Waiting for the Grid' sleep 1 done>&2 echo "Selenium Grid is up - executing tests" exec $cmd
Will require
jqinstalled viaapt-get, else the script will keep printingWaitingwithout completing the execution.
Note: If needed, replace
localhostand
4444for the correct values in your environment. Also, this script is polling indefinitely, you might want to tweak it and establish a timeout.
Let's say that the normal command to execute your tests is
mvn clean test. Here is a way to use the above script and execute your tests:
$ ./wait-for-grid.sh mvn clean test
Like this, the script will poll until the Grid is ready, and then your tests will start.
This project uses x11vnc as VNC server to allow users inspect what is happening inside the container. Users can connect to this server in two ways:
The VNC server is listening to port 5900, you can use a VNC client and connect to it. Feel free to map port 5900 to any free external port that you wish.
The internal 5900 port remains the same because that is the configured port for the VNC server running inside the container.
Here is an example with the standalone images, the same concept applies to the node images.
bash $ docker run -d -p 4444:4444 -p 5900:5900 -v /dev/shm:/dev/shm selenium/standalone-chrome:4.0.0-beta-3-prerelease-20210402 $ docker run -d -p 4444:4444 -p 5901:5900 -v /dev/shm:/dev/shm selenium/standalone-edge:4.0.0-beta-3-prerelease-20210402 $ docker run -d -p 4445:4444 -p 5902:5900 -v /dev/shm:/dev/shm selenium/standalone-firefox:4.0.0-beta-3-prerelease-20210402 $ docker run -d -p 4446:4444 -p 5903:5900 -v /dev/shm:/dev/shm selenium/standalone-opera:4.0.0-beta-3-prerelease-20210402
Then, you would use in your VNC client: - Port 5900 to connect to the Chrome container - Port 5901 to connect to the Edge container - Port 5902 to connect to the Firefox container - Port 5903 to connect to the Opera container
If you get a prompt asking for a password, it is:
secret. If you wish to change this, you should either change it in the
/NodeBase/Dockerfileand build the images yourself, or you can define a Docker image that derives from the posted ones which reconfigures it:
#FROM selenium/node-chrome:4.0.0-beta-3-prerelease-20210402 #FROM selenium/node-edge:4.0.0-beta-3-prerelease-20210402 #FROM selenium/node-firefox:4.0.0-beta-3-prerelease-20210402 #FROM selenium/node-opera:4.0.0-beta-3-prerelease-20210402 #Choose the FROM statement that works for you.RUN x11vnc -storepasswd /home/seluser/.vnc/passwd
If you want to run VNC without password authentication you can set the environment variable
VNC_NO_PASSWORD=1.
This project uses noVNC to allow users inspect visually container activity with their browser. This might come handy if you cannot install a VNC client on your machine. Port 7900 is used to start noVNC, so you will need to connect to that port with your browser.
Similarly to the previous section, feel free to map port 5900 to any free external port that you wish.
Here is an example with the standalone images, the same concept applies to the node images.
bash $ docker run -d -p 4444:4444 -p 7900:7900 -v /dev/shm:/dev/shm selenium/standalone-chrome:4.0.0-beta-3-prerelease-20210402 $ docker run -d -p 4444:4444 -p 7901:7900 -v /dev/shm:/dev/shm selenium/standalone-edge:4.0.0-beta-3-prerelease-20210402 $ docker run -d -p 4445:4444 -p 7902:7900 -v /dev/shm:/dev/shm selenium/standalone-firefox:4.0.0-beta-3-prerelease-20210402 $ docker run -d -p 4446:4444 -p 7903:7900 -v /dev/shm:/dev/shm selenium/standalone-opera:4.0.0-beta-3-prerelease-20210402
Then, you would use in your browser: - http://localhost:7900/ to connect to the Chrome container - http://localhost:7901/ to connect to the Edge container - http://localhost:7902/ to connect to the Firefox container - http://localhost:7903/ to the Opera container
If you get a prompt asking for a password, it is:
secret.
All output gets sent to stdout, so it can be inspected by running:
bash $ docker logs -f
You can increase the log output by passing environment variable to the containers:
SE_OPTS="--log-level FINE"
-v /dev/shm:/dev/shmor
--shm-size 2g
Why is
-v /dev/shm:/dev/shmor
--shm-size 2gnecessary?
This is a known workaround to avoid the browser crashing inside a docker container, here are the documented issues for Chrome and Firefox. The shm size of 2gb is arbitrary but known to work well, your specific use case might need a different value, it is recommended to tune this value according to your needs. Along the examples
-v /dev/shm:/dev/shmwill be used, but both are known to work.
If you see the following selenium exceptions:
Message: invalid argument: can't kill an exited process
or
Message: unknown error: Chrome failed to start: exited abnormally
The reason might be that you've set the
START_XVFBenvironment variable to "false", but forgot to actually run Firefox, Chrome or Opera in the headless mode.