# Zoom Bot Server (production setup)

The machine that runs the **zoom-bot's browsers** — the headless Chrome windows that sit in a
webinar and type the timed chat drops ("at 1:01:32, *Adeline* says …"). It is a **separate VM**,
not the web box. What the bot *does* is documented with the Zoom module
([Zoom handbook](/docs/modules_handbook/manage/zoom/readMe.md) → *Live webinar Q&A and the
zoom-bot*); this file is how to stand the box up, switch production over to it, and tell when it is
down.

## Why a separate machine

Zoom will not let a panelist rename itself, so every **sender name** is its own Zoom participant —
one headless Chrome each ("a seat"). Measured on the 2-vCPU prod web box on 2026-10-16: a seat
costs **~30% of a CPU and ~500 MB**; four names at once took the box to load ~30, the drops failed
to post, and the web box serves the site. One name on the same box sent 6 of 6.

The bot only keeps a name in the room while it is about to speak (it enters
`ZOOM_BOT_SEAT_LEAD_SECONDS` = 4 min before its drop and leaves once its next drop is more than
`ZOOM_BOT_SEAT_IDLE_SECONDS` = 8 min away), so what has to fit is the number of names **in the room
at the same time**, not the number of names in the night. A new name every minute ≈ 5 at once.

| Bot server | Names in the room at once (rule: CPUs − 1, ~600 MB each) |
| --- | --- |
| 4 vCPU / 4–8 GB | 3 |
| **8 vCPU / 8 GB — `e2-highcpu-8` (recommended)** | **7** |
| 16 vCPU / 16 GB | 15 |

The pre-flight checks the night's plan against the bot server's real CPUs and free memory and says
so on your phone an hour before (see *How you know it is working*). Before that, the session's
**Webinar tab → Engagement timeline** checks each drop as it is typed: it shows how many names fit,
refuses a drop that needs one more, and suggests a name already in the room or a time that fits.
It uses the CPU count the bot server last reported, so it works while the VM is switched off.

## How it works

```
petav3 (app server) — the brain                         bot server — the hands
  zoom:run-bot, every minute: "82506338799 needs a bot"
    → leaves an ORDER  ─────────────────────────────────→  runner.js checks in every 20 s,
                                                            collects it, starts src/live-loop.js
  bot/zoom/webinars/{id}/join: signs each seat's join  ←── each seat asks for its signed join
  feed / heartbeat / results / alerts                  ←──→ the bot reports in as it always did
```

- **Production stays the brain.** The supervisor still decides which webinar needs a bot, holds the
  STARTING lock and the three-launch ceiling, and the watchdog still sends the Telegram alerts.
  With `ZOOM_BOT_RUNNER=remote` it simply does not start a process — it leaves the launch for the
  bot server (`Src\Zoom\Services\ZoomBotRunner`, a short-lived cache entry). While the bot server
  is offline nothing is ordered and **no launch attempt is used up** — the bot goes in the minute the
  server checks in.
- **The bot server holds no Zoom credentials.** Its `.env` has two values: `PETAV3_URL` and
  `BOT_TOKEN`. Each seat's Meeting SDK signature is built and its panelist token minted on the app
  server (`ZoomBotController::join`), and that endpoint only signs the bot's own panelist address or
  a plus-address of it. Changing the Zoom app on **Manage → Integrations → Zoom** needs nothing here.
- **It only makes outbound HTTPS calls** (to petav3 and to Zoom). Nothing needs to reach it: no open
  port, no inbound firewall rule.
- **Every check-in reports** the box's CPUs, free memory and load, its own self-checks (node,
  Chromium, log folder) and the join error in each recent bot log. The pre-flight and the
  "bot is not in the webinar" alert read these instead of the app server's.
- Stopping or restarting the runner does **not** stop a bot already in a webinar (each bot runs in
  its own process group; the unit below sets `KillMode=process`). Updating mid-webinar is safe.

## Create the VM (Google Cloud console)

| Setting | Value |
| --- | --- |
| Machine type | `e2-highcpu-8` (8 vCPU, 8 GB) — see the sizing table above |
| Region | `asia-southeast1`, same as production |
| Boot disk | Ubuntu 24.04 LTS, 20 GB |
| Firewall | nothing to open — leave "Allow HTTP/HTTPS traffic" **unticked** |
| External IP | needed for outbound traffic (ephemeral is fine) |

**Save money with an instance schedule** (Compute Engine → Instance schedules): the bot server is
only needed while a webinar with chat drops is on. Start it **at least 70 minutes before** the
earliest webinar (the pre-flight runs 60 minutes before and must find it online) and stop it after
the latest webinar's end + 30 minutes. If it is off when it should be on, you get an alert telling
you so.

## Install (once, on the bot server)

```bash
# 1. Node 22 LTS (20.6+ also works — it must support --env-file) and git
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs git

# 2. A user for the bot
sudo useradd --system --create-home --home-dir /opt/zoom-bot-home --shell /usr/sbin/nologin zoombot

# 3. Only the tools/zoom-bot folder of the repo. The repo is private: add a READ-ONLY
#    deploy key for this machine on GitHub (repo → Settings → Deploy keys) first.
sudo -u zoombot git clone --depth 1 --filter=blob:none --sparse \
    git@github.com:property-lab/petav3.git /opt/zoom-bot-home/petav3
cd /opt/zoom-bot-home/petav3
sudo -u zoombot git sparse-checkout set tools/zoom-bot
cd tools/zoom-bot

# 4. Dependencies + Chromium (+ the system libraries Chromium needs)
sudo -u zoombot npm ci
sudo -u zoombot PLAYWRIGHT_BROWSERS_PATH=$PWD/pw-browsers npx playwright install chromium
sudo PLAYWRIGHT_BROWSERS_PATH=$PWD/pw-browsers npx playwright install-deps chromium
```

`/opt/zoom-bot-home/petav3/tools/zoom-bot/.env` (owner `zoombot`, `chmod 600`):

```ini
# The app server, exactly as the bot reaches it.
PETAV3_URL=https://petav3.example.com
# Must equal ZOOM_BOT_TOKEN in the app server's .env.
BOT_TOKEN=
# Where step 4 installed Chromium.
PLAYWRIGHT_BROWSERS_PATH=/opt/zoom-bot-home/petav3/tools/zoom-bot/pw-browsers
```

Nothing else. No Zoom key goes here.

`/etc/systemd/system/zoom-bot-runner.service`:

```ini
[Unit]
Description=zoom-bot runner (collects webinar bot launches from petav3)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=zoombot
WorkingDirectory=/opt/zoom-bot-home/petav3/tools/zoom-bot
ExecStart=/usr/bin/node --env-file=.env src/runner.js
Restart=always
RestartSec=10
# Restarting the runner (an update) must never pull a bot out of a live webinar:
# only the runner itself is stopped, the bots it started keep going.
KillMode=process

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now zoom-bot-runner
sudo journalctl -u zoom-bot-runner -f     # "checking in with https://… every 20s"
```

## Switch production over

On the app server, in `.env`:

```ini
ZOOM_BOT_RUNNER=remote
```

then `php artisan config:cache` (the deploy script does this too). Check it took:

```bash
sudo -u ubuntu php artisan zoom:bot-doctor
```

It now prints `runner: remote` and checks the **bot server**, not this box: the credentials this
server signs joins with, *"bot server: checked in within the last 120s"*, that it runs the same bot
version (protocol), and every problem the bot server's own self-check found. All pass = ready.

To go back to running the browsers on the app server: `ZOOM_BOT_RUNNER=local` + `config:cache`.

## How you know it is working

You do not have to look. The Telegram alerts (**Setting → Notifications**, tick both *Zoom bot*
events for your chat) cover it:

- **An hour before** every webinar with chat drops: *"✅ Zoom bot ready"* — or the numbered
  problems, e.g. *"bot server: checked in … — last seen 3 hours ago — is the bot server VM switched
  on?"*, or *"6 names in the room at the same time = 6 browser windows, but the 4-CPU server running
  the bot handles about 3 reliably"*. When the bot server comes online later, the check runs again
  and tells you it is now ready.
- **During** it: *"🚨 Zoom bot is NOT in the webinar"* (with *"The bot server is OFFLINE"* when that
  is why, and the join error from the bot's log), or *"⚠️ A Zoom chat drop did not go out"*.

## Updating the bot code

When a deploy changes `tools/zoom-bot` (or the pre-flight says the bot server runs an older
protocol):

```bash
cd /opt/zoom-bot-home/petav3
sudo -u zoombot git pull
cd tools/zoom-bot && sudo -u zoombot npm ci
sudo systemctl restart zoom-bot-runner
```

Safe during a webinar: the running bots are not touched; the next launch uses the new code.

## Logs

- The runner: `sudo journalctl -u zoom-bot-runner`.
- Each webinar's bot: `tools/zoom-bot/logs/zoom-bot-<zoom webinar id>.log` on the bot server
  (`ZOOM_BOT_LOG_DIR` moves it). Seats joining and leaving, every drop's outcome and every failed
  join with what Zoom showed ("Waiting for host to start the webinar") are there.

## Related files

- [tools/zoom-bot/src/runner.js](/tools/zoom-bot/src/runner.js) — the daemon (check-in, launch, self-check, log report).
- [tools/zoom-bot/src/live-loop.js](/tools/zoom-bot/src/live-loop.js) — the bot itself; seats come and go via `planSeats()` in [seats.js](/tools/zoom-bot/src/seats.js).
- [src/Zoom/Services/ZoomBotRunner.php](/src/Zoom/Services/ZoomBotRunner.php) — orders + check-ins (`PROTOCOL` must equal the sidecar's `RUNNER_PROTOCOL`).
- [app/Http/Controllers/Bot/ZoomBotRunnerController.php](/app/Http/Controllers/Bot/ZoomBotRunnerController.php) — `POST bot/zoom/runner/check-in`.
- [app/Http/Controllers/Bot/ZoomBotController.php](/app/Http/Controllers/Bot/ZoomBotController.php) — `join` (signed seat join) and `release` (drops a bot left without firing).
- [src/Zoom/Services/ZoomBotReadiness.php](/src/Zoom/Services/ZoomBotReadiness.php) — the checks `zoom:bot-doctor` and the pre-flight share; `peakSeats()`.
