Build System and Image Management

Relevant source files

This document covers the Docker image build process, multi-stage builds, and image management workflows for the Docker Selenium project. The build system centers around a Makefile-based orchestration that coordinates Docker image creation, multi-architecture support, version management, and registry operations integrated with comprehensive CI/CD workflows.

The build process follows a hierarchical multi-stage approach starting with the base Ubuntu image in Base/Dockerfile progressing through infrastructure layers, and culminating in browser-specific nodes and standalone containers.

For information about the specific Docker image contents and configurations, see page 2.2 (Base and Infrastructure Images), page 2.3 (Grid Component Images), and page 2.4 (Browser Node and Standalone Images). For CI/CD workflows that use this build system, see page 7.1 (Build and Test Workflows).

Multi-Stage Build Architecture

The Docker Selenium build system implements a multi-stage architecture where each image builds upon its dependencies, starting from the foundational Ubuntu base and progressing through specialized layers.

Base Image Multi-Stage Process

The foundation begins with Base/Dockerfile1 which establishes the core infrastructure:

Sources: Base/Dockerfile1 Base/Dockerfile53-68 Base/Dockerfile119-155 Base/Dockerfile136-151

Build Arguments and Version Management

The multi-stage build process uses consistent build arguments defined in Base/Dockerfile7-27:

Build Argument	Purpose	Default Value	Line Reference
`VERSION`	Selenium Grid version	-	Base/Dockerfile7
`OPENTELEMETRY_VERSION`	OpenTelemetry library version	`1.53.0`	Base/Dockerfile10
`GRPC_VERSION`	gRPC library version	`1.74.0`	Base/Dockerfile11
`NETTY_VERSION`	Netty library version	`4.1.126.Final`	Base/Dockerfile12
`SEL_USER`	Selenium user name	`seluser`	Base/Dockerfile18
`UID`	User ID	`1200`	Base/Dockerfile21
`GID`	Group ID	`1201`	Base/Dockerfile22
`JRE_VERSION`	Java Runtime version	`21`	Base/Dockerfile24

Sources: Base/Dockerfile7-27

Build Orchestration with Makefile

The build system centers around a comprehensive Makefile that defines build targets, dependency relationships, and orchestration logic for the entire Docker image ecosystem.

Core Build Targets and Dependencies

Sources: Makefile41-59 Makefile144-171 Makefile184-306

Build Variables and Configuration

The build system uses extensive variable configuration for version management and build customization, integrated with CI/CD environment variables:

Variable	Purpose	Default	Workflow Usage
`NAME` / `NAMESPACE`	Docker namespace	`selenium`	.github/workflows/deploy.yml96
`VERSION` / `BASE_VERSION`	Selenium Grid version	Latest upstream	.github/workflows/deploy.yml104
`BUILD_DATE`	Build timestamp	`$(date '+%Y%m%d')`	.github/workflows/deploy.yml88
`TAG_VERSION`	Combined version-date tag	`${VERSION}-${BUILD_DATE}`	.github/workflows/deploy.yml111
`PLATFORMS`	Target architectures	Set by workflow	.github/workflows/deploy.yml94
`AUTHORS`	Image authors	`SeleniumHQ`	.github/workflows/deploy.yml97

CI/CD Environment Integration

The build variables are populated from GitHub Actions environment variables in the deployment workflow:

Sources: .github/workflows/deploy.yml86-94 .github/workflows/deploy.yml96-98

Multi-Architecture Support

The build system supports multi-architecture image creation using Docker Buildx, with platform-specific logic for browser compatibility.

Platform Detection and Configuration

The build system automatically detects the current platform and sets appropriate defaults:

To build for specific platforms, set the PLATFORMS variable:

Sources: Makefile27-28 README.md210-228

Platform Support Matrix

Component	linux/amd64	linux/arm64	Notes
Base Images	✅	✅	Universal support
Hub/Router/Distributor	✅	✅	Grid components
Chrome Node/Standalone	✅	❌	Google Chrome binary not available for ARM
Edge Node/Standalone	✅	❌	Microsoft Edge binary not available for ARM
Firefox Node/Standalone	✅	✅	Multi-arch support since v136+
Chromium Node/Standalone	✅	✅	Open-source alternative for ARM

Sources: README.md148-162 README.md177-178

Platform-Specific Build Logic

The Makefile implements conditional platform checks for browser images:

The conditional logic for Chrome:

Similar logic exists for Edge and standalone variants.

Sources: Makefile173-182 Makefile195-204 Makefile244-253 Makefile268-277

Docker Buildx Integration

All image builds use docker buildx build with the following standard arguments:

Example build command for the base image:

Sources: Makefile17-18 Makefile144-146

Version and Tag Management

The build system implements a sophisticated tagging strategy that supports multiple version formats and automated tag generation.

Version Variable Hierarchy

Core version variables from the Makefile:

Version component extraction:

Sources: Makefile1-11 Makefile19-21

Browser Version Management

The build system maintains browser version matrices in YAML files that define specific browser and driver versions for backward compatibility testing:

These matrices are used by the backward compatibility build scripts:

Sources: tests/build-backward-compatible/browser-matrix.yml9-13 .github/workflows/release-chrome-versions.yml121-126

Browser-Specific Tag Generation

The tag_and_push_browser_images.sh script generates comprehensive tags for browser images incorporating browser versions, driver versions, and build metadata:

The script is invoked via Makefile targets:

Sources: Makefile383-395 tag_and_push_browser_images.sh

Image Registry Management

The build system provides comprehensive registry operations including tagging strategies, push operations, and release management.

Tag Categories and Operations

Sources: Makefile399-426 Makefile459-486 Makefile514-554 Makefile381-393

Platform-Aware Registry Operations

The registry operations include platform-specific logic to handle browser availability:

Sources: Makefile417-426

Build Dependencies and Image Hierarchy

The build system enforces a strict dependency hierarchy that ensures base images are built before dependent images.

Image Dependency Graph

Sources: Makefile144-171 Makefile184-306

Build Arguments and FROM Image Resolution

The build system uses consistent build arguments to pass namespace, version, and author information through the dependency chain:

Each Dockerfile declares and uses these arguments to reference its parent image:

NodeChrome/Dockerfile:

NodeFirefox/Dockerfile:

NodeBase/Dockerfile:

This pattern ensures:

Consistent versioning across the image hierarchy
Ability to override base images for testing
Proper attribution in image metadata
SBOM (Software Bill of Materials) generation with --sbom=true
Build provenance attestation with --attest type=provenance,mode=max

Sources: Makefile17-18 NodeChrome/Dockerfile1-6 NodeFirefox/Dockerfile1-6 NodeBase/Dockerfile1-6

Release Automation

The build system includes automated release processes that handle version updates, release notes generation, and documentation synchronization.

Release Process Components

Release Notes Generation

The release automation extracts version information from built images to generate comprehensive release notes:

Sources: generate_release_notes.sh17-30

Automated Version Updates

The system performs comprehensive version updates across documentation and configuration files:

Sources: update_tag_in_docs_and_files.sh24 Makefile103-109