compose-anything/src/selenium

Selenium Standalone with Chrome

Selenium Grid in Standalone mode with Chrome browser for browser automation at scale.

Quick Start

# Start the service
docker compose up -d

# Verify the service is running
docker compose ps

# View logs
docker compose logs -f

# Stop the service
docker compose down

Service Information

Ports

Port	Service	Description
4444	Selenium Grid	HTTP endpoint for WebDriver
7900	noVNC	Browser viewing interface (password: secret)

Default Credentials

• VNC Password: secret (configurable via SE_VNC_PASSWORD)

Volumes

• selenium_downloads: Browser downloads directory (/home/seluser/Downloads)

Configuration

Environment Variables

All configuration can be customized via the .env file:

# Copy the example configuration
cp .env.example .env

# Edit the configuration
nano .env

Key configurations:

Variable	Default	Description
SELENIUM_VERSION	144.0-20260120	Docker image tag (Chrome version + date)
SELENIUM_SHM_SIZE	2g	Shared memory size (required for browser stability)
SELENIUM_GRID_PORT_OVERRIDE	4444	Grid HTTP endpoint port
SELENIUM_VNC_PORT_OVERRIDE	7900	noVNC viewer port
SE_SCREEN_WIDTH	1920	Browser screen width
SE_SCREEN_HEIGHT	1080	Browser screen height
SE_NODE_MAX_SESSIONS	1	Max concurrent sessions per container
SE_NODE_SESSION_TIMEOUT	300	Session timeout in seconds

For a complete list of environment variables, see the Selenium Docker documentation.

Usage

Basic WebDriver Test (Python)

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

# Configure Chrome options
options = Options()

# Connect to Selenium Grid
driver = webdriver.Remote(
    command_executor='http://localhost:4444',
    options=options
)

# Run your test
driver.get('https://www.selenium.dev/')
print(driver.title)

# Clean up
driver.quit()

Basic WebDriver Test (Node.js)

const { Builder } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');

(async function example() {
    let driver = await new Builder()
        .forBrowser('chrome')
        .usingServer('http://localhost:4444')
        .build();
    
    try {
        await driver.get('https://www.selenium.dev/');
        console.log(await driver.getTitle());
    } finally {
        await driver.quit();
    }
})();

Viewing Browser Sessions

You can watch tests execute in real-time using noVNC:

1. Open your browser to http://localhost:7900/?autoconnect=1&resize=scale&password=secret
2. The default VNC password is secret
3. You'll see the browser session in real-time

Alternatively, use a VNC client to connect to localhost:5900 (if exposed).

Advanced Configuration

Changing Browser Version

To use a specific Chrome version, update the SELENIUM_VERSION in your .env file:

# Use Chrome 143.0
SELENIUM_VERSION=143.0-20260120

# Or use a specific Selenium Grid version
SELENIUM_VERSION=144.0-chromedriver-144.0-grid-4.40.0-20260120

Visit Docker Hub for available versions.

Increasing Concurrent Sessions

To run multiple concurrent sessions in one container (not recommended for production):

SE_NODE_MAX_SESSIONS=5

Note: For better stability, scale containers instead:

docker compose up -d --scale selenium-chrome=3

Retrieving Downloaded Files

To access files downloaded during tests, mount the downloads directory:

volumes:
  - ./downloads:/home/seluser/Downloads

Linux users: Set proper permissions before mounting:

mkdir -p ./downloads
sudo chown 1200:1201 ./downloads

Running in Headless Mode

For newer Chrome versions (127+), headless mode requires Xvfb:

SE_START_XVFB=true

Then configure headless in your test:

options = Options()
options.add_argument('--headless=new')

Custom Screen Resolution

Adjust screen resolution for your test needs:

SE_SCREEN_WIDTH=1366
SE_SCREEN_HEIGHT=768
SE_SCREEN_DEPTH=24
SE_SCREEN_DPI=74

Health Check

The container includes a built-in health check that polls the Grid status endpoint every 30 seconds:

# Check container health
docker compose ps

# Or inspect the health status
docker inspect --format='{{json .State.Health.Status}}' <container-id>

Troubleshooting

Browser Crashes

If you see errors like "Chrome failed to start" or "invalid argument: can't kill an exited process":

1. Ensure sufficient shared memory: The default 2g should work for most cases

   SELENIUM_SHM_SIZE=2g
   

2. Check headless mode configuration: Make sure SE_START_XVFB=true if using headless mode with Chrome 127+

Permission Issues (Linux)

When mounting volumes on Linux, ensure correct permissions:

# For downloads directory
mkdir -p ./downloads
sudo chown 1200:1201 ./downloads

# Check user/group IDs in container
docker compose exec selenium-chrome id

Resource Constraints

If tests are slow or containers are being OOM killed:

# Increase resource limits
SELENIUM_CPU_LIMIT=4.0
SELENIUM_MEMORY_LIMIT=4G

VNC Connection Issues

If you can't connect to VNC:

1. Check that port 7900 is not in use
2. Verify the VNC password is correct (default: secret)
3. Try disabling VNC authentication: SE_VNC_NO_PASSWORD=true

Multi-Browser Support

For running multiple browser types (Chrome, Firefox, Edge), consider using:

• Hub & Nodes architecture: See docker-compose-grid.yaml example
• Dynamic Grid: Automatically spawns containers on demand
• Selenium Grid 4: Full distributed mode with Router, Distributor, etc.

Additional Resources

• Selenium Documentation
• Docker Selenium GitHub
• Selenium Grid Configuration
• Environment Variables Reference

Security Notes

• VNC Password: Change the default secret password in production
• Network Exposure: Do not expose Selenium Grid directly to the internet
• Resource Limits: Always set CPU and memory limits to prevent resource exhaustion
• User Permissions: Selenium runs as non-root user seluser (UID 1200, GID 1201)

License

This configuration is provided under the Apache License 2.0, following the Selenium project's licensing. The Selenium Docker images are maintained by the SeleniumHQ team and community contributors.