selenosis-deploy Helm chart

Architecture

diagram

Summary

This chart deploys the full Selenosis stack:

selenosis — Selenium hub/proxy for creating sessions and routing traffic.
browser-controller — Kubernetes controller that reconciles Browser and BrowserConfig CRDs into Pods.
browser-service — REST + event stream API for managing Browser resources.
browser-ui — UI + VNC WebSocket proxy backed by browser-service.

CRDs for Browser and BrowserConfig are managed as Helm template resources (templates/crds/) and applied on every helm install and helm upgrade. Installation can be disabled with --set crds.enabled=false if you manage CRDs outside of Helm.
Each service is configurable via Helm values that map to the environment variables described in the individual project READMEs.

Installation

From Helm Repository

Add the Selenosis Helm repository:

helm repo add selenosis https://alcounit.github.io/selenosis-deploy/
helm repo update

Install the chart:

helm install selenosis selenosis/selenosis-deploy -n selenosis --create-namespace

From Git Repository

Clone and install directly:

git clone https://github.com/alcounit/selenosis-deploy.git
cd selenosis-deploy
helm upgrade --install selenosis . -n selenosis --create-namespace --wait
helm status selenosis -n selenosis

CRD Management

CRDs are part of the chart templates and are controlled by the crds values block:

crds:
  enabled: true  # set to false to skip CRD installation
  keep: true     # adds helm.sh/resource-policy: keep — CRDs are not deleted on helm uninstall

Install without CRDs (when CRDs are already applied or managed externally):

helm install selenosis selenosis/selenosis-deploy -n selenosis --create-namespace --set crds.enabled=false

Upgrade without touching CRDs:

helm upgrade selenosis selenosis/selenosis-deploy -n selenosis --set crds.enabled=false

Unlike the legacy crds/ directory approach, CRDs in templates are updated by helm upgrade when the schema changes. If you are upgrading from a previous chart version that used crds/, follow the migration guide.

BrowserConfig examples

Ready-to-use BrowserConfig manifests are in examples/. Apply any of them after deploying the chart:

kubectl apply -n selenosis -f ./examples/<filename>.yaml

Selenoid (twilio/selenoid)

Images from the Twilio-maintained Selenoid image family. VNC is built into the image and enabled via the ENABLE_VNC=true env var. Minimal two-container setup: browser + seleniferous sidecar.

helm upgrade selenosis . -n selenosis --set browserUI.vncPassword="selenoid"

Selenium Standalone (selenium/standalone)

Official Selenium project standalone images with a built-in VNC server. Password is configured via SE_VNC_PASSWORD. Minimal two-container setup: browser + seleniferous sidecar.

helm upgrade selenosis . -n selenosis --set browserUI.vncPassword="${se_vnc_password}"

Moon (quay.io/browser)

Images from Moon project, distributed via quay.io/browser. VNC requires a full X11 sidecar stack: xvfb (X server), openbox (window manager), and x11vnc (VNC server) — all from quay.io/aerokube. Also requires a usergroup ConfigMap (included in the manifests) to map the user:4096 identity used by the browser containers.

helm upgrade selenosis . -n selenosis --set browserUI.vncPassword="selenoid"

Playwright-specific Moon images for CDP/BiDi protocol sessions.

Playwright Standalone (mcr.microsoft.com/playwright)

Official Microsoft Playwright base image. Contains Chromium, Firefox, and WebKit browsers. The playwright-core npm module is installed via an init container since the base image only ships browser binaries. The run-server command starts a multi-browser WebSocket server — the client chooses which browser to launch at connect time. Minimal two-container setup: browser + seleniferous sidecar.

browserconfig-playwright-example.yaml

Playwright MCP (mcr.microsoft.com/playwright/mcp)

Microsoft Playwright MCP server image. Exposes browser automation via MCP Streamable HTTP protocol. Lightweight image with a built-in MCP server — no init container needed. Minimal two-container setup: browser + seleniferous sidecar.

browserconfig-playwright-mcp-example.yaml

Service types

Each service supports ClusterIP, NodePort, or LoadBalancer.

Example values:

browserUI:
  service:
    type: NodePort
    port: 8080
    nodePort: 30080

browserService:
  service:
    type: LoadBalancer
    port: 8080

selenosis:
  service:
    type: ClusterIP
    port: 4444

Apply:

helm upgrade --install selenosis . -n selenosis -f values.local.yaml

Ingress Configuration

Expose services via Ingress for external access with TLS and WebSocket support.

Each component (selenosis and browserUI) has its own ingress configuration under its respective section.

Basic Setup (NGINX Ingress Controller)

selenosis:
  ingress:
    enabled: true
    className: nginx
    host: selenosis.example.com

browserUI:
  ingress:
    enabled: true
    className: nginx
    host: ui.example.com
    # CRITICAL: WebSocket support for VNC proxy
    annotations:
      nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
      nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
      nginx.ingress.kubernetes.io/websocket-services: "browser-ui"

With TLS/SSL Certificate

selenosis:
  ingress:
    enabled: true
    className: nginx
    host: selenosis.example.com
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
    tls:
      secretName: selenosis-tls

browserUI:
  ingress:
    enabled: true
    className: nginx
    host: ui.example.com
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
      nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
      nginx.ingress.kubernetes.io/websocket-services: "browser-ui"
    tls:
      secretName: browser-ui-tls

Important: Browser UI requires WebSocket support for the VNC proxy. The above annotations are required for NGINX Ingress Controller. Other ingress controllers may require different annotations.