This page documents the remote access and debugging infrastructure for browser sessions running in Selenium Grid containers. It covers the VNC server setup, noVNC web-based access, Fluxbox window manager configuration, and Supervisor process management that enables live viewing of browser automation sessions.
For information about video recording of sessions, see Video Recording and Upload. For container startup and lifecycle management, see Component Startup and Lifecycle.
Remote access capabilities allow developers and operators to view live browser sessions running inside Docker containers. This is essential for debugging test failures, understanding automation behavior, and troubleshooting issues in both development and production environments.
The remote access stack consists of four integrated components:
All components are orchestrated by Supervisor, which manages process lifecycle, dependencies, and automatic restarts.
Sources: NodeBase/Dockerfile81-161 NodeBase/selenium.conf1-73
Xvfb creates a virtual X11 display server that performs all graphical operations in memory without requiring a physical display. This enables browsers to run in headless environments while still rendering full GUI elements.
Key Configuration:
99 (environment variable DISPLAY_NUM):99.0 (environment variable DISPLAY)1920x1080x24 by defaultSE_SCREEN_WIDTH, SE_SCREEN_HEIGHT, SE_SCREEN_DEPTH, SE_SCREEN_DPIStartup Script: NodeBase/start-xvfb.sh
Supervisor Configuration:
[program:xvfb] priority=0 command=/opt/bin/start-xvfb.sh autostart=%(ENV_SE_START_XVFB)s autorestart=%(ENV_SE_START_XVFB)s The priority=0 setting ensures Xvfb starts before all other components that depend on the display.
Sources: NodeBase/Dockerfile75-79 NodeBase/selenium.conf5-22
x11vnc exposes the Xvfb display over the VNC protocol on port 5900, allowing remote desktop clients to view and optionally interact with the browser session.
Key Features:
secret, stored in ${HOME}/.vnc/passwd)-rfbport and -rfbportv6-forever) to persist across client disconnections-shared) to allow multiple simultaneous viewersStartup Logic:
The startup script NodeBase/start-vnc.sh1-66 implements several configuration options:
File Descriptor Limit Handling:
The script includes protection against excessively high ulimit -n values (>100,000), which can cause VNC server instability. See NodeBase/start-vnc.sh45-57 for implementation details.
Sources: NodeBase/start-vnc.sh1-66 NodeBase/Dockerfile156-160 NodeBase/selenium.conf23-39
noVNC provides browser-based access to VNC sessions without requiring VNC client software installation. It uses WebSockets to proxy VNC protocol to web browsers on port 7900.
Implementation:
noVNC is deployed from the official noVNC project, with websockify handling the protocol translation:
| Component | Version | Source |
|---|---|---|
| noVNC | v1.6.0 | NOVNC_VERSION build arg |
| websockify | v0.13.0 | WEBSOCKIFY_VERSION build arg |
| Installation | /opt/bin/noVNC | Extracted from GitHub releases |
Startup Process:
The NodeBase/start-novnc.sh1-33 script:
SE_START_XVFB=true)SE_START_VNC=true)/opt/bin/noVNC/utils/novnc_proxy --listen ${SE_NO_VNC_PORT} --vnc localhost:${SE_VNC_PORT}Access URL Format:
http://<container-host>:7900/?autoconnect=1&resize=scale&password=secret Query parameters:
autoconnect=1: Automatically connect without manual interventionresize=scale: Scale viewport to fit browser windowpassword=secret: Pre-fill VNC password (default)Sources: NodeBase/Dockerfile124-160 NodeBase/start-novnc.sh1-33 NodeBase/selenium.conf41-57 README.md128-129
Fluxbox provides basic window management functionality, including title bars, minimize/maximize controls, and desktop wallpaper. It is configured to display the Selenium Grid logo as the desktop background.
Installation: NodeBase/Dockerfile108
Wallpaper Configuration:
The script NodeBase/start-vnc.sh8-15 sets the wallpaper using fbsetbg:
The wallpaper image is the Selenium Grid logo: NodeBase/selenium_grid_logo.png
Font Configuration:
Fluxbox is configured to use "WenQuanYi Zen Hei" font for international language support, replacing the default Ubuntu font. See NodeBase/Dockerfile117 for the sed command that modifies the style file.
Sources: NodeBase/Dockerfile108-118 NodeBase/start-vnc.sh8-15 NodeBase/selenium_grid_logo.png
Supervisor orchestrates the startup, monitoring, and lifecycle of all remote access components. It enforces a strict startup order through priority values to ensure dependencies are met.
Configuration Files:
| Deployment Mode | Configuration File |
|---|---|
| Node | NodeBase/selenium.conf1-73 |
| Standalone | Standalone/selenium.conf1-75 |
Key Supervisor Settings:
| Program | Priority | autostart | autorestart | Purpose |
|---|---|---|---|---|
| xvfb | 0 | SE_START_XVFB | SE_START_XVFB | Virtual display |
| vnc | 5 | SE_START_VNC | SE_START_VNC | VNC server |
| novnc | 10 | SE_START_NO_VNC | SE_START_NO_VNC | Web proxy |
| selenium-node | 15 | true | false | Grid component |
Process Lifecycle:
autorestart controlled by environment variables, allowing selective disablingautorestart=false to prevent restart loops on intentional shutdownsLog Configuration:
All programs log to /var/log/supervisor/, with rotation configured:
stdout_logfile_maxbytes=50MBstderr_logfile_maxbytes=50MBstdout_logfile_backups=5stderr_logfile_backups=5The Selenium node/standalone redirects all output to stdout for Docker log integration:
redirect_stderr=true stdout_logfile=/dev/stdout stdout_logfile_maxbytes=0 Sources: NodeBase/selenium.conf1-73 Standalone/selenium.conf1-75
| Variable | Default | Description |
|---|---|---|
DISPLAY | :99.0 | X11 display identifier |
DISPLAY_NUM | 99 | Display number for Xvfb |
SE_SCREEN_WIDTH | 1920 | Virtual screen width in pixels |
SE_SCREEN_HEIGHT | 1080 | Virtual screen height in pixels |
SE_SCREEN_DEPTH | 24 | Color depth in bits |
SE_SCREEN_DPI | 96 | Screen DPI setting |
| Variable | Default | Description |
|---|---|---|
SE_START_XVFB | true | Enable Xvfb virtual display |
SE_START_VNC | true | Enable x11vnc VNC server |
SE_START_NO_VNC | true | Enable noVNC web client |
| Variable | Default | Description |
|---|---|---|
SE_VNC_PORT | 5900 | VNC server listening port |
VNC_PORT | 5900 | Alternative variable name |
SE_VNC_NO_PASSWORD | unset | Disable password authentication (true/1) |
VNC_NO_PASSWORD | unset | Alternative variable name |
SE_VNC_VIEW_ONLY | unset | Enable view-only mode (true/1) |
VNC_VIEW_ONLY | unset | Alternative variable name |
SE_VNC_PASSWORD | unset | Custom VNC password (overrides default) |
VNC_PASSWORD | unset | Alternative variable name |
SE_VNC_ULIMIT | unset | Custom file descriptor limit |
| Variable | Default | Description |
|---|---|---|
SE_NO_VNC_PORT | 7900 | noVNC web server listening port |
NO_VNC_PORT | 7900 | Alternative variable name |
Variable Precedence:
The startup scripts check both VAR_NAME and SE_VAR_NAME forms, with SE_ prefixed versions taking precedence. For example:
Sources: NodeBase/Dockerfile63-79 NodeBase/start-vnc.sh16-34 NodeBase/start-novnc.sh23
Traditional VNC clients provide the most responsive experience with full keyboard and mouse support.
Connection Steps:
Ensure container port 5900 is mapped to the host:
Connect using VNC client:
localhost (or container IP)5900secret (default)Recommended VNC Clients:
Custom Password:
Set a custom VNC password using environment variables:
Password Storage:
The password is hashed and stored at container build time using x11vnc's password storage mechanism. See NodeBase/Dockerfile156:
Sources: README.md98-99 NodeBase/start-vnc.sh30-34
noVNC provides instant access without installing additional software, ideal for quick debugging or environments where VNC clients cannot be installed.
Connection Steps:
Ensure container port 7900 is mapped to the host:
Open web browser to:
http://localhost:7900/?autoconnect=1&resize=scale&password=secret URL Parameters:
| Parameter | Values | Description |
|---|---|---|
autoconnect | 0, 1 | Automatically connect on page load |
resize | off, scale, remote | Viewport scaling mode |
password | string | Pre-fill VNC password field |
path | string | WebSocket path (default: websockify) |
encrypt | 0, 1 | Use encrypted WebSocket (wss://) |
Example from README:
README.md128 demonstrates accessing a running container:
http://localhost:7900/?autoconnect=1&resize=scale&password=secret Sources: README.md99-100 README.md128 NodeBase/start-novnc.sh23
VNC can be disabled to reduce resource consumption in production environments or when remote access is not needed.
Disable All Remote Access:
Disable Only Web Access:
Note: Disabling Xvfb (SE_START_XVFB=false) is not recommended as browsers require a display to render properly, even in headless mode.
Sources: README.md100 NodeBase/start-vnc.sh5-6 NodeBase/start-novnc.sh5-7
Example Docker Compose configurations exposing VNC ports:
For view-only access in production monitoring:
Sources: README.md118-129
In Kubernetes deployments, VNC access can be exposed through Services or Ingress resources. The Helm chart automatically configures VNC services when enabled.
Service Configuration:
By default, the Helm chart creates a Service exposing noVNC port 7900 for each browser node. Access patterns vary by deployment strategy:
http://<node-ip>:<nodeport>/node/<pod-name>)Environment Variables in Helm:
The chart passes VNC configuration through values.yaml:
For detailed Helm chart configuration, see Helm Chart Configuration.
Sources: README.md69
Symptoms: VNC client cannot connect to port 5900
Diagnosis:
Check if VNC is enabled:
Verify port mapping:
Check VNC logs:
Solutions:
SE_START_VNC=true is setdocker exec <container> ps aux | grep XvfbSymptoms: Web browser shows black viewport after connecting
Diagnosis:
Verify Xvfb is running:
Check if browser process is running:
Solutions:
SE_SCREEN_WIDTH and SE_SCREEN_HEIGHT are reasonable valuesdocker exec <container> cat /var/log/supervisor/xvfb-stderr.logSymptoms: VNC or noVNC fails to start with "too many open files" error
Diagnosis: Check current limit:
Solutions: The startup scripts automatically handle excessive limits (>100,000), but you can set a custom limit:
See NodeBase/start-vnc.sh45-57 and NodeBase/start-novnc.sh9-21 for automatic limit adjustment logic.
Symptoms: Desktop shows plain background instead of Selenium Grid logo
Diagnosis: Check Fluxbox process:
Solutions:
selenium_grid_logo.png exists: docker exec <container> ls -la /usr/share/images/fluxbox/ubuntu-light.pngfbsetbg errorsdocker exec <container> /usr/bin/fbsetbg -c /usr/share/images/fluxbox/ubuntu-light.pngSources: NodeBase/start-vnc.sh8-15 NodeBase/Dockerfile171
Default Security: VNC is password-protected by default with the password secret. This provides basic protection but should not be relied upon for production security.
Recommendations:
VNC_PASSWORD environment variableSE_VNC_VIEW_ONLY=true) in production monitoringVNC ports (5900, 7900) should not be exposed to untrusted networks. Use one of:
ssh -L 5900:localhost:5900 remote-hostFor production monitoring without allowing control:
This prevents keyboard and mouse input while still allowing session observation.
Sources: NodeBase/start-vnc.sh24-28
Each remote access component consumes resources:
| Component | CPU Impact | Memory Impact | Notes |
|---|---|---|---|
| Xvfb | Low | 50-100 MB | Minimal when no browser active |
| x11vnc | Low-Medium | 20-50 MB | Increases with viewer connections |
| noVNC | Low | 10-20 MB | WebSocket proxy overhead |
| Fluxbox | Very Low | 5-10 MB | Lightweight window manager |
Recommendations:
SE_START_VNC=falseVNC streams screen updates continuously, consuming bandwidth:
noVNC includes automatic quality adjustment to adapt to network conditions.
Sources: NodeBase/Dockerfile81-161
This remote access infrastructure integrates with other Selenium Grid systems:
Sources: NodeBase/Dockerfile1-182 NodeBase/selenium.conf1-73
Refresh this wiki