The docker-selenium project provides Docker images and deployment configurations for running Selenium Grid, a platform for distributed browser automation testing. The project enables running browser tests in containerized environments, from local development setups to production-scale Kubernetes clusters.
The project is maintained by SeleniumHQ and distributed under the Apache License 2.0. Images are published to Docker Hub and Helm charts are available at Artifact Hub.
The repository provides:
For configuration details, see page 5. For Kubernetes deployment, see page 3. For advanced features like video recording and autoscaling, see page 6.
Sources: README.md15-30 Makefile1-40
Docker Selenium supports four primary deployment patterns, each suited for different use cases:
Deployment Diagram: Standalone Mode
Standalone mode combines the Selenium Hub and browser Node in a single container. This is the simplest deployment option, suitable for:
Quick Start:
Sources: README.md116-136 README.md408-430
Deployment Diagram: Hub-Node Architecture
Hub-Node mode separates the Grid orchestration (Hub) from browser execution (Nodes). The Hub manages session routing and load balancing across multiple Node containers. This pattern supports:
Quick Start:
Sources: README.md434-503 Hub/Dockerfile1-32 NodeBase/Dockerfile41-52
Deployment Diagram: Distributed Grid Components
Distributed Grid decomposes the Hub into separate microservices:
This pattern enables:
Sources: README.md623-637 Makefile151-168
Deployment Diagram: Dynamic Grid Provisioning
Dynamic Grid provisions browser containers on-demand for each session request. The selenium/node-docker or selenium/standalone-docker images communicate with the Docker daemon to create and destroy ephemeral browser containers. This pattern provides:
Sources: README.md822-829 Makefile225-229
| Aspect | Standalone | Hub-Node | Distributed Grid | Dynamic Grid |
|---|---|---|---|---|
| Container Count | 1 | 2+ (1 Hub + N Nodes) | 5+ (Router, Distributor, Sessions, Queue, EventBus + Nodes) | 1-2 + ephemeral |
| Use Case | Development, CI/CD | Small-to-medium scale | Production, high availability | Variable workloads |
| Scalability | None (single container) | Manual horizontal scaling | Component-level scaling | Automatic on-demand |
| Complexity | Low | Medium | High | Medium |
| Resource Efficiency | Fixed | Fixed | Fixed | Dynamic |
| Compose File | N/A | docker-compose-v3.yml | docker-compose-v3-full-grid.yml | docker-compose-v3-dynamic-grid.yml |
Sources: README.md406-629
Image Hierarchy Diagram
The image hierarchy follows a layered architecture:
selenium/base: Provides Java 21, Selenium server JAR, OpenTelemetry instrumentation, and Supervisor process manager. All other images extend from this base.selenium/hub, selenium/router, selenium/distributor, selenium/sessions, selenium/session-queue, selenium/event-bus extend base directly and implement specific Grid microservices.selenium/video: FFmpeg-based image for session recording, compiled with x264, xcb, and pulse audio codecs.selenium/node-base: Adds graphical display infrastructure (Xvfb virtual framebuffer, VNC server, noVNC web interface, Fluxbox window manager) on top of the video image.selenium/node-chrome, selenium/node-firefox, selenium/node-edge, selenium/node-chromium extend node-base with browser binaries and WebDrivers.For detailed image documentation, see page 2.
Sources: Makefile41-59 Makefile144-308 NodeBase/Dockerfile1-182 NodeChrome/Dockerfile1-59 NodeFirefox/Dockerfile1-95 Hub/Dockerfile1-32
The project supports both AMD64 and ARM64 architectures, though browser availability varies:
Browser Architecture Support Matrix
| Browser | AMD64 | ARM64 | Notes |
|---|---|---|---|
| Chrome | ✅ | ❌ | Google does not build Chrome for Linux/ARM |
| Edge | ✅ | ❌ | Microsoft does not build Edge for Linux/ARM |
| Firefox | ✅ | ✅ | Available from v136+ via APT stable channel |
| Chromium | ✅ | ✅ | Open source, multi-platform support |
The build system automatically detects the host architecture and builds appropriate images. Multi-architecture builds can be performed using:
Note: Running AMD64 images under emulation on ARM64 platforms is not recommended due to performance and stability issues.
Sources: README.md144-191 Makefile27-28 Makefile210-229
Images are tagged with multiple formats to support different use cases:
| Tag Format | Example | Use Case |
|---|---|---|
| Full version | selenium/hub:4.36.0-20251001 | Pin to specific Selenium and build date |
| Major.Minor.Patch | selenium/hub:4.36.0 | Pin to Selenium version |
| Major.Minor | selenium/hub:4.36 | Auto-update patch versions |
| Major | selenium/hub:4 | Auto-update minor and patch versions |
| latest | selenium/hub:latest | Always use newest stable release |
| nightly | selenium/hub:nightly | Nightly builds from Selenium main branch |
| dev/beta | selenium/standalone-chrome:dev | Pre-release browser channels |
For production deployments, always use full version tags to ensure reproducibility.
Sources: README.md20-21 README.md132-136 README.md232-284
The project provides three primary deployment methods:
Docker Compose files simplify multi-container orchestration for local development and small-scale deployments. Key configurations:
docker-compose-v3.yml: Basic Hub-Node griddocker-compose-v3-full-grid.yml: Distributed Grid with all componentsdocker-compose-v3-video.yml: Grid with video recordingdocker-compose-v3-dynamic-grid.yml: Dynamic Grid with on-demand provisioningdocker-compose-v3-tracing.yml: Grid with distributed tracing (Jaeger)See page 4 for Docker Compose deployment details.
The charts/selenium-grid Helm chart enables production Kubernetes deployments with:
See page 3 for Kubernetes deployment details.
Individual containers can be run manually using docker run commands, suitable for simple use cases or custom orchestration.
Sources: README.md607-629 README.md69
| Component | Minimum Version | Notes |
|---|---|---|
| Docker Engine | 26.1.4 | Required for all deployments |
| Docker Compose | v2.34.0 | For compose-based deployments |
| Docker Buildx | v0.25.0 | For building multi-arch images |
| Kubernetes | v1.26.15 | For Helm chart deployments |
Resource Recommendations:
--shm-size=2g minimumSources: README.md110-114 README.md132-133
Sessions can be recorded using the selenium/video:ffmpeg-8.0-latest image with automatic cloud upload via rclone:
Sources: README.md640-782
The dynamic grid feature enables on-demand browser container provisioning using selenium/node-docker and selenium/standalone-docker images:
Browser availability varies by architecture:
| Browser | AMD64 | ARM64 |
|---|---|---|
| Chrome | ✅ | ❌ |
| Edge | ✅ | ❌ |
| Firefox | ✅ | ✅ |
| Chromium | ✅ | ✅ |
Sources: README.md144-191 README.md368-387
The system uses environment variables with the SE_* prefix for configuration across all deployment modes. Key configuration areas include:
SE_EVENT_BUS_HOST, SE_NODE_HOSTSE_NODE_MAX_SESSIONS, SE_NODE_SESSION_TIMEOUTSE_RECORD_VIDEO, SE_VIDEO_FILE_NAMESE_ENABLE_TLS, SE_ROUTER_USERNAMESE_ENABLE_TRACING, SE_OTEL_SERVICE_NAMESources: README.md388-405 NodeBase/Dockerfile34-79
This overview establishes the foundational understanding of Docker Selenium's architecture and capabilities. Subsequent sections provide detailed implementation guidance for specific deployment scenarios and advanced features.
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.