README.md

WebGrid

Install | Usage | Docs

_{You have an idea for a logo? Submit it here!}

---

• Cluster ready. Designed with concurrency and on-demand scalability¹ in mind
• Debuggable. Provides browser screen recordings, extensive logs, and tracing
• Fast. Built for speed and performance on a single grid instance
• W3C Specification compilant. Fully compatible with existing Selenium 4 clients

_{¹All the way down to zero, obviously}

---

Install

Below are quick-start tutorials to get you started. For a more detailed introduction visit the dedicated Getting Started guide!

🐳 Docker

To run a basic grid in Docker you can use Docker Compose. Below is a bare-bones example of getting all required components up and running!

# Create prerequisites
docker network create webgrid

# Download compose file
curl -fsSLO webgrid.dev/docker-compose.yml

# Launch the grid
docker-compose up

You can now point your Selenium client to localhost:8080 and browse the API at /api.

☸️ Kube

For deployment to Kubernetes a Helm repository is available. The default values provide a good starting point for basic cluster setups like K3s or microk8s.

# Add the repository
helm repo add webgrid https://webgrid.dev/

# List all available versions
helm search repo --versions --devel webgrid/demo

# Install the chart
helm install example webgrid/demo --version "<pick-a-version-from-the-list>"

# Make it accessible locally for evaluation
kubectl port-forward service/example-webgrid 8080:80

Your grid is now available at localhost:8080.

If you are deploying to a RBAC enabled cluster you might have to tweak some settings. Take a look at the documentation on how to use your own ServiceAccount and PersistentVolumeClaims.

Usage

Once you have your grid up and running there is a couple of things you can do!

🚀 Launch browser instances

Point your selenium client to http://localhost:8080 to create a new browser container/pod and interact with it! You can use all features supported by Selenium.

🔍 Browse the API

The grid provides a GraphQL API at /api with a Playground for you to explore. It exposes all available metadata about sessions, grid health and advanced features like video recordings.

📺 Watch your browsers

You can take a live look at what your browsers are doing by taking the Session ID of a instance and visiting localhost:8080. You can also embed the videos in your existing tools! Head over to the embedding documentation to learn how.

_{Note:
Video recordings are disabled by default in K8s as every cluster has specific requirements for file storage. The storage documentation explains how to enable it.}

Developing

If you want to build the project locally you can use the Makefile. To create Docker images for every component and run them locally run these commands:

# Build docker images
make

# Start components in docker
make install

To start individual components outside of Docker or setup the development environment, see the development environment documentation.

License

This project is licensed under the MIT License. While this does grant you a lot of freedom in how to use the software and keeps the legal headache to a minimum, it also no longer requires you to publish modifications made to the project. The original intention behind the AGPL license was to encourage contributions by users who added features for their own use.

Since this project is so small at this stage, it heavily relies on feedback and contributions from the community (thats you!). So please strongly consider contributing any changes you make for the benefit of all users 🙂