What Selenium Grid does
Selenium Grid is the server of the Selenium project, published under the Apache-2.0 license. It speaks the WebDriver protocol standardized by the W3C: a test written in Java, Python, JavaScript, C# or Ruby asks it for a session, the grid starts a browser, runs the commands (open a page, click, fill in a field, read a text) and returns the results.
The docker-selenium project publishes ready-to-use images. The standalone image bundles in a single container the router (the HTTP entry point), the session queue and a node that carries the browser. On a VPS it is the simplest form: one container, one port, and no driver to install on the host. Large distributed grids, with a hub and dozens of nodes, use the same images split differently.
Unlike an online testing service billed by the minute, the grid belongs to you: tested pages, test accounts and screenshots stay on your server.
What the grid gives you
- A stable browser — all your suites test the same Chromium version, whatever the runner.
- Shorter builds — no more browser or driver installation on every run.
- A standard endpoint — any WebDriver client connects to it without changing the test code.
- Parallel sessions — several tests at once, within the VPS memory.
- A live view — the grid interface shows the browser while it works.
- A shared grid — several projects and several CIs can target the same address.
Chrome installed on the runner or a Selenium grid on your VPS
Scroll the table
| Chrome on every runner | Selenium Grid on your VPS | |
|---|---|---|
| Browser installation | On every build | Once, on the server |
| Tested version | Varies from runner to runner | Identical for all suites |
| Runner memory | Shared with the build | Free for the build |
| Watching a test | Screenshots afterwards | Live view in the interface |
| Sharing across projects | Impossible | One address for all |
Prepare the server
Plan an Ubuntu 24.04 VPS with 2 GB of RAM and 2 vCPUs: the grid alone uses less than 300 MB at rest, but each Chromium session needs several hundred MB during a test. Move to 4 GB to sustain two continuous sessions. 10 GB of disk is enough, the image weighs a little over a GB.
Install Docker with the Compose plugin, nginx and certbot. You also need a domain name (or a subdomain) pointing to the VPS: your pipelines will connect to the grid from outside, over HTTPS. In the examples, the address is grid.example.com.
Install Selenium Grid with Docker Compose
Prepare the folder and the password
The
.envfile holds the grid's username and password. This password also protects the live view.mkdir -p /opt/selenium-grid && cd /opt/selenium-grid cat > .env <<EOF ADMIN_USER=admin ADMIN_PASSWORD=$(openssl rand -hex 16) EOF chmod 600 .envWrite the docker-compose.yml file
A single service, the official image with Chromium.
shm_sizegives the browser the shared memory it needs; without it, tabs crash on heavy pages. The port is only published on the loopback: only nginx will be exposed to the Internet.services: selenium: image: selenium/standalone-chromium:4.53.0-20261120 restart: unless-stopped shm_size: 2gb environment: SE_ROUTER_USERNAME: ${ADMIN_USER:-admin} SE_ROUTER_PASSWORD: ${ADMIN_PASSWORD:?ADMIN_PASSWORD manquant} SE_VNC_PASSWORD: ${ADMIN_PASSWORD:?ADMIN_PASSWORD manquant} SE_NODE_MAX_SESSIONS: "2" SE_NODE_OVERRIDE_MAX_SESSIONS: "true" SE_NODE_SESSION_TIMEOUT: "300" ports: - "127.0.0.1:4444:4444"Start and check the grid
The image ships its own health check:
--waitreturns once the grid is ready. The/statuspage must answertrue.docker compose up -d --wait . ./.env curl -s -u "admin:$ADMIN_PASSWORD" http://127.0.0.1:4444/status | jq .value.readyPublish the grid behind nginx
The
UpgradeandConnectionheaders let the live view's websockets through, and the read timeout covers long commands.server { server_name grid.example.com; location / { proxy_pass http://127.0.0.1:4444; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 300s; } }Enable HTTPS
The grid password travels with every request: only expose it over HTTPS. Without credentials,
/statusmust answer 401.certbot --nginx -d grid.example.com curl -s -o /dev/null -w '%{http_code}\n' https://grid.example.com/status
Never open the grid without a password
A Selenium grid reachable without authentication is a browser anyone can drive from your server: visit sites, fill in forms, get around IP-based filtering. The bots that sweep the Internet look precisely for port 4444. Keep SE_ROUTER_PASSWORD, leave the port on 127.0.0.1 and only open nginx's 443 to the public.
Connect your tests to the grid
On the test side, only the browser start changes: instead of a local driver, you create a RemoteWebDriver pointing to the grid address, credentials included. The rest of the test stays the same. In Python:
from selenium import webdriver
options = webdriver.ChromeOptions()
driver = webdriver.Remote(
command_executor="https://admin:[email protected]",
options=options,
)
driver.get("https://example.com")
print(driver.title)
driver.quit()In JavaScript with selenium-webdriver, same principle. The Chromium node answers to the browser name chrome. Older clients that append /wd/hub to the address also work, the grid accepts both forms.
const { Builder } = require("selenium-webdriver");
const driver = await new Builder()
.usingServer("https://admin:[email protected]")
.forBrowser("chrome")
.build();Run the tests from GitHub Actions or GitLab CI
Keep the password in the CI secrets and build the address when the job runs. Your tests read SELENIUM_URL instead of starting a local browser:
- name: Tests de bout en bout
env:
SELENIUM_URL: https://admin:${{ secrets.SELENIUM_PASSWORD }}@grid.example.com
run: pytest tests/e2eThe same pattern works for GitLab CI (masked variable), Jenkins (credentials manager) or Gitea Actions. The tested site must be reachable from the VPS: a public or password-protected staging environment works, a development server started inside the runner does not, unless you expose it through a tunnel.
Watch a session and unblock the grid
The https://grid.example.com/ui/ interface lists running sessions. Click a session and then the camera icon to watch the browser; the password asked is the grid's. A test that crashes without calling quit() keeps its slot busy until the SE_NODE_SESSION_TIMEOUT delay (five minutes here). To free a stuck session right away:
curl -s -u "admin:$ADMIN_PASSWORD" http://127.0.0.1:4444/status \
| jq '.value.nodes[].slots[] | select(.session != null) | .session.sessionId'
curl -s -u "admin:$ADMIN_PASSWORD" -X DELETE http://127.0.0.1:4444/session/<id>The container logs (docker compose logs -f selenium) give the cause of a refused session: unknown requested capability, full queue or a browser that does not start.
Capacity, memory and other browsers
The configuration above opens two sessions in parallel. Beyond that, requests wait in the queue, then fail after SE_SESSION_REQUEST_TIMEOUT (300 seconds by default). To scale up, increase the VPS RAM before SE_NODE_MAX_SESSIONS: a Chromium short on memory does not slow down, it crashes.
The standalone-firefox and standalone-edge images are used exactly the same way; Edge and Google Chrome are only published for x86-64 processors, Chromium and Firefox also exist for ARM. To test several browsers, run one service per image on different ports.
Install Selenium Grid in one click from the ServOrbit Marketplace
The ServOrbit Marketplace installs this same configuration on your VPS: official image with Chromium, grid protected by the admin user and a generated password, port published on the loopback and nginx reverse proxy over HTTPS. Selenium Grid requires a domain, since your pipelines connect to it from outside: choose a subdomain of one of your domains, or the VPS's free subdomain, HTTPS included. The password is shown in your client area.
servorbit.com/ma-en/blog/self-host-selenium-grid-vps-ci