Set up the local Graph lab
This guide starts the separate Graph experiment dashboard on http://localhost:5090. Use a trusted development machine and designated mailbox. Dashboard authentication is disabled.
Prerequisites
Prepare Node.js, pnpm, OpenSSL, and Graph application credentials and consent. The test workflow also uses Bun. Webhooks need a public HTTPS callback because Microsoft cannot reach a private localhost URL.
The lab has its own configuration and callback paths. Production MailGen settings do not automatically configure it.
Configure the environment
src/env.js defines the required contract. .env.example is not a complete list. Supply these values through the lab's local configuration:
| Variable | Format and purpose | Required/default |
|---|---|---|
DATABASE_URL | SQLite URL, for example file:./db.sqlite | Required |
NODE_ENV | development, test, production | Defaults to development |
TENANT_ID | Entra tenant identity | Required, nonempty |
CLIENT_ID | Application client identity | Required, nonempty |
CLIENT_SECRET | App-only credential | Required, confidential |
GRAPH_WEBHOOK_CLIENT_STATE | Stable random validation secret | Required |
GRAPH_WEBHOOK_URL | Public HTTPS callback, for example https://<your-public-host>/graphWebhook | Required URL |
GRAPH_WEBHOOK_ENCRYPTION_CERTIFICATE_PATH | Public certificate file or supported directory | Required |
GRAPH_WEBHOOK_ENCRYPTION_PRIVATE_KEY_PATH | Matching private-key file or supported directory | Required, confidential |
GRAPH_WEBHOOK_ENCRYPTION_CERTIFICATE_ID | Certificate identifier or supported file/directory reference | Required, 1–128 characters in environment validation |
DELTA_LINK_ENCRYPTION_KEY | Stable Base64 encoding of 32 random bytes | Required for stored continuation links |
The certificate helpers resolve configured files/directories. Preserve the delta key with the database. Replacing it can make saved links unreadable. Generate a new key only for a new prepared configuration:
openssl rand -base64 32
Install and start
From the motherrepo root:
cd Architecture/GraphSyncExperimenter/graph-call-dashboard
pnpm install
pnpm cert:generate
pnpm db:push
pnpm dev
db:push changes the configured SQLite schema. Check that it targets the disposable lab database before running it. Open http://localhost:5090 after startup.
Certificate generation creates a self-signed certificate, private key, and certificate ID. It resolves paths from configuration and preserves an existing complete set unless --force is explicit. Do not replace keys used by active subscriptions without planning the matching subscription update.
Script reference
| Command | Action |
|---|---|
pnpm dev | Next.js development server with --turbo --port 5090 |
pnpm cert:generate | Generate certificate/key/ID |
pnpm db:push | Apply Prisma schema to the configured database |
pnpm db:migrate | Deploy migrations |
pnpm db:studio | Open database inspection UI |
pnpm test | Run the repository's database-prepared test workflow |
pnpm check | ESLint and TypeScript checks |
Check the result
- Open Diagnostics and inspect Graph configuration and certificate status.
- List users/folders for the designated mailbox.
- Open the delta explorer and execute a read, or create a subscription for the configured callback.
- Inspect the stored response or webhook arrival.
Missing configuration fails validation before normal startup. Invalid certificate paths prevent rich-content decryption. A broken public callback can prevent subscription validation or later arrivals. An invalid database URL prevents database access. Use troubleshooting for these cases.