CloudBeat Playwright-Cucumber Agent - Docker Deployment Guide

---

1. Overview

The deployment consists of two containers:

• cb.controller.cucumberjs— The CloudBeat test controller and Playwright-Cucumber runner. Connects to the CloudBeat Gateway, executes tests, and reports results.

• playwright-browsers — A standalone Playwright browser server (official Microsoft image). Hosts browser engines and exposes them via WebSocket on port 3000 (the controller does not embed browsers. It connects to the browser container over WebSocket, allowing independent version upgrades and scaling).

---

2. Prerequisites

AWS Instance Requirements

Resource	Minimum
OS	Ubuntu 22.04 LTS and later (officially supported by CB) or Amazon Linux 2023 (no official support by CB team)
CPU	4 vCPUs (x86 architecture)
Memory	8 GB RAM (16 GB recommended)
Storage	50 GB SSD (gp3)

Actual hardware requirements depend on the number of required parallel tests.

Network Access

• Outbound: All outbound ports should be open.

• Inbound: No inbound ports need to be opened. The controller initiates all connections outbound.

---

3. Setup

3.1 Install Docker

Please refer to the official Docker documentation.

3.2 Create Working Directory

sudo mkdir -p /opt/cloudbeat && cd /opt/cloudbeat

3.3 Create .env File

Create a .env file with your CloudBeat configuration. Replace placeholder values with the credentials provided by CloudBeat:

PW_VERSION=1.57.0

CB_LOGGER_DEPLOYMENT_NAME=AWS_Docker_Playwright
CB_CONTROLLER_API_KEY=<your-api-key>
CB_CONTROLLER_AGENT_ID=<your-agent-id>
CB_CONTROLLER_LOCATION_KEY=<your-location-key>
CB_CONTROLLER_LOCATION_NAME=<your-location-name>
CB_CONTROLLER_GATEWAY_URL=https://api.cloudbeat.io:8080
CB_CONTROLLER_PARALLEL_TESTS=2

3.4 Environment Variables Reference

Variable	Description
PW_VERSION	Playwright version for the browser container (e.g. 1.57.0)
CB_CONTROLLER_API_KEY	API key for authenticating with the Gateway
CB_CONTROLLER_AGENT_ID	Unique agent identifier assigned by CloudBeat
CB_CONTROLLER_LOCATION_KEY	Location key for this runner instance
CB_CONTROLLER_LOCATION_NAME	Human-readable name for this location
CB_CONTROLLER_GATEWAY_URL	CloudBeat Gateway URL
CB_CONTROLLER_PARALLEL_TESTS	Maximum number of parallel tests (default: 2)

3.5 Create docker-compose.yml

Place the provided docker-compose.yml file in /opt/cloudbeat/. The complete file is included in the Reference section below.

---

4. Deployment

Start Services

cd /opt/cloudbeat
docker compose pull
docker compose up -d

Verify

docker compose ps

Both services should show status "Up" with playwright-browsers showing "healthy".

docker compose logs cb.controller.cucumberjs --tail 50

Look for log entries confirming successful connection to the CloudBeat Gateway.

Run a Test

Trigger a test run from the CloudBeat web interface. Monitor in real time:

docker compose logs -f cb.controller.cucumberjs

---

5. Upgrading Playwright Version

1. Update PW_VERSION in your .env file

2. Recreate the browser container:

docker compose up -d playwright-browsers

Important: The Playwright version in the browser container must match the version used in your test projects.

6. Upgrading the Controller

docker compose pull cb.controller.cucumberjs
docker compose up -d cb.controller.cucumberjs

Important: It is recommended to update the controller periodically to benefit from the latest fixes and improvements. If a specific version is required due to a CloudBeat Gateway update, the CloudBeat team will notify you in advance

---

7. Docker Compose File

services:
  playwright-browsers:
    image: mcr.microsoft.com/playwright:v${PW_VERSION:-1.57.0}-noble
    container_name: playwright-browsers
    command: npx playwright@${PW_VERSION:-1.57.0} run-server --port 3000 --host 0.0.0.0
    shm_size: '2gb'
    networks:
      - cb-network
    healthcheck:
      test: ["CMD", "node", "-e",
        "const http=require('http');http.get('http://localhost:3000',r=>{process.exit(r.statusCode===200?0:1)}).on('error',()=>process.exit(1))"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 15s
    security_opt:
      - no-new-privileges:true

  cb.controller.cucumberjs:
    image: cloudbeat/cucumberjs-runner
    container_name: cb-controller-cucumberjs
    volumes:
      - /etc/ssl/certs:/etc/ssl/certs:ro
      - /etc/ca-certificates:/etc/ca-certificates:ro
    environment:
      - DOTNET_NOLOGO=true
      - CB_LOGGING_LEVEL=info
      - CB_LOGGER_DEPLOYMENT_NAME=${CB_LOGGER_DEPLOYMENT_NAME}
      - CB_CONTROLLER_API_KEY=${CB_CONTROLLER_API_KEY}
      - CB_CONTROLLER_AGENT_ID=${CB_CONTROLLER_AGENT_ID}
      - CB_CONTROLLER_LOCATION_KEY=${CB_CONTROLLER_LOCATION_KEY}
      - CB_CONTROLLER_LOCATION_NAME=${CB_CONTROLLER_LOCATION_NAME}
      - CB_CONTROLLER_GATEWAY_URL=${CB_CONTROLLER_GATEWAY_URL}
      - CB_CONTROLLER_PARALLEL_TESTS=${CB_CONTROLLER_PARALLEL_TESTS}
      - PW_TEST_CONNECT_WS_ENDPOINT=ws://playwright-browsers:3000
    networks:
      - cb-network
    security_opt:
      - no-new-privileges:true
    depends_on:
      playwright-browsers:
        condition: service_healthy

networks:
  cb-network:
    external: false