Skip to content

GETTING STARTED

Getting started

Five minutes from clone to a running control room with simulated events.

← Docs hub

Prerequisites

  • Go 1.27+
  • curl, python3 (for smoke scripts)

Optional for full integration testing:

  • relay-pubsub running with RELAY_BACKEND=relay-events
  • Zyvor Relay reachable at RELAY_BASE_URL

1. Run the server

git clone https://github.com/zyvorai/relay-edge.git
cd relay-edge
go test ./...
go run ./cmd/relay-edge

Open http://127.0.0.1:18086/ui — product home with a self-test lab (store · send · receive). Fire-water console: /ui/firewater.html.

2. Farm smoke (API-only)

In another terminal:

./scripts/smoke.sh

This walks the full farm lifecycle: site → zone → device → season → open → stage → advisory → critical irrigation event.

3. Industrial simulators

Fire-water plant

./scripts/smoke-firewater.sh
# or interactively: Seed → scenarios in /ui

Remote edge NOC

./scripts/smoke-remote-edge.sh
# or open http://127.0.0.1:18086/ui/remote-edge.html

Master fleet catalog

./scripts/smoke-fleet.sh
# or open http://127.0.0.1:18086/ui/fleet.html — scenarios: blackout, amr_lost, …

All four local smokes (with edge already running):

make smoke-all

4. Publish into Relay (optional)

When relay-pubsub and Relay are running:

# Seed shared industrial season
curl -fsS -X POST http://127.0.0.1:18086/v1/firewater/seed

# Enable publish on firewater
curl -fsS -X POST http://127.0.0.1:18086/v1/firewater/config \
  -H 'content-type: application/json' \
  -d '{"publish":true,"interval_ms":5000}'

# Trigger a scenario — events flow: edge → gateway → Relay
curl -fsS -X POST http://127.0.0.1:18086/v1/firewater/scenario \
  -H 'content-type: application/json' \
  -d '{"scenario":"lowtank"}'

Set environment before starting edge:

# Pubsub may be on another host:
export GATEWAY_BASE_URL=https://<pubsub-host>:8081
export RELAY_AUTH_TOKEN=<your-jwt>
export RELAY_TLS_INSECURE=1
go run ./cmd/relay-edge

Remote edge / Fleet — seed once via firewater, then use the browser:

  1. Run POST /v1/firewater/seed (firewater UI Seed plant inventory, or curl below)
  2. Open /ui/remote-edge.html or /ui/fleet.html
  3. Enable Publish into Relay → Apply config
  4. Pick a scenario or Start stream
curl -fsS -X POST http://127.0.0.1:18086/v1/firewater/seed

Same pattern via curl: POST /v1/remote-edge/config, POST /v1/fleet/config.

Direct to Relay (no relay-pubsub)

Skip the gateway — edge POSTs straight to Relay's /v1/events:

export GATEWAY_BASE_URL=          # must be explicit empty — unset uses gateway default
export RELAY_BASE_URL=https://<relay-host>:8443   # remote OK; or :18080
export RELAY_AUTH_TOKEN=<your-jwt>
export RELAY_TLS_INSECURE=1
go run ./cmd/relay-edge
./scripts/smoke.sh   # publish.path should be "relay"

Full expanded matrix (farm + all simulator scenarios):

cp config/lab-direct.env.example config/lab-direct.env
# BASE, EDGE, RELAY_AUTH_TOKEN

set -a && source config/lab-direct.env && set +a
./scripts/e2e-direct-stack.sh    # probe + e2e-direct-relay.sh

Remote deploy in direct mode: RELAY_EDGE_DIRECT=1 RELAY_AUTH_TOKEN=<jwt> ./scripts/deploy-remote.sh <HOST>

Full details → Working with Relay

5. HTTPS mode (pods / production-style)

export EDGE_TLS=1
export EDGE_TLS_SAN=localhost,127.0.0.1
go run ./cmd/relay-edge
curl -k https://127.0.0.1:18086/healthz
curl -k https://127.0.0.1:18086/readyz
curl -k https://127.0.0.1:18086/version

Certs are generated once under /var/lib/relay-edge/tls/ (or local ./data parent paths in dev). /healthz reports build version; /readyz is 503 until a publish target (gateway or Relay base) is configured.

6. Full stack simulation (Zynera optional)

When Zynera runs at the same site, Relay can gate critical acts behind Zynera Decision Records. relay-edge only publishes events — Zynera is not required for the core stack.

No Zynera (relay-edge + pubsub + Relay):

cp config/lab-stack.env.example config/lab-stack.env
# or: cp config/lab-stack-175.env.example config/lab-stack-175.env
# BASE / GATEWAY / EDGE = remote host URLs (not 127.0.0.1 from your laptop)
# RELAY_AUTH_TOKEN — leave ZYNERA_* empty

set -a && source config/lab-stack.env && set +a
./scripts/e2e-stack.sh

With Zynera — add ZYNERA_BASE, ZYNERA_API_KEY, and RELAY_FORGE_* on Relay, then ./scripts/e2e-zynera-stack.sh.

Farm Act fails (TLS / mock targets)? Wire Relay first:

RELAY_BIN=/path/to/linux-amd64-relay ./scripts/lab-wire-relay-act.sh <HOST>
# then sync pubsub JWT and ./scripts/e2e-stack.sh

→ Integration guide · Test results

Next steps