Local Development

The control plane needs a SurrealDB instance and an AMQP broker. Everything else runs from the workspace.

The repository .env is not a dev profile

The root .env can hold production credentials (SURREALDB_HOST, SURREALDB_USER, SURREALDB_PASSWORD, SURREALDB_NAMESPACE, SURREALDB_NAME, AMQP_URI), and every process you start inherits it. Pass the database flags explicitly — or override the variables — so a local run cannot talk to a remote database by accident.

1. Dependencies

docker run -d --name guru-surreal -p 8000:8000 \
  surrealdb/surrealdb:latest start --user root --pass root

docker run -d --name guru-rabbit -p 5672:5672 -p 15672:15672 rabbitmq:4-alpine

Use a SurrealDB 3.2 or newer server. Older 3.0 binaries disagree with the client the workspace links against and mis-handle assertions that read a row written earlier in the same transaction.

The broker URI form matters: use amqp://guest:guest@127.0.0.1:5672/ for the default vhost.

2. Schema

Schema lives in database/schema/*.surql (one file per module) and is managed with surrealkit:

surrealkit sync --host ws://127.0.0.1:8000 --ns guru --db guru

3. Bootstrap an administrator

cargo run -p manage-tool -- \
  --address ws://127.0.0.1:8000 --username root --password root \
  --namespace guru --database guru \
  create-admin --email admin@example.com --password 'change-me'

4. Control plane

Each mode is a separate process. The operator API the dashboard talks to is dashboard_grpc:

cargo run -p guru-master -- \
  --mode dashboard_grpc \
  --address ws://127.0.0.1:8000 --username root --password root \
  --namespace guru --database guru \
  --amqp-uri 'amqp://guest:guest@127.0.0.1:5672/'

Swap --mode for workers_grpc, consumer or cron to run the other workers; consumer is what re-derives configs after a canvas edit.

5. Dashboard

bun install
GURU_GRPC_URL=127.0.0.1:50051 bun run dev

bun run dev at the workspace root proxies to the guru-frontend package.

6. Documentation site

These docs are their own workspace package:

bun run --filter guru-docs dev     # or: bun run docs:dev
bun run --filter guru-docs build   # static output in typescript/docs/dist

Regenerating the API client

proto/ is the single source of truth. After changing it, regenerate the TypeScript client (the Rust side is generated by rpguru_sdk’s build.rs):

bun run generate:proto

Tests

Module integration tests run against an in-memory SurrealDB (mem://) and apply the module’s own schema file, so they need no running server:

cargo test