Skip to content

Configuration

Jump to bottom
motionbug edited this page May 16, 2026 · 2 revisions

Configuration

This page covers all configuration options for Setup Manager HUD. Follow these steps in order for a new deployment, or jump to a specific section for reference.

KV Namespace (Required)

Setup Manager HUD stores webhook events in Cloudflare Workers KV. Without this, the Worker returns 500 errors on webhook requests.

Option A: Cloudflare Dashboard

No CLI needed - everything in the browser.

1. Create the namespace:

  1. Log in to the Cloudflare dashboard
  2. Go to Workers & Pages -> KV in the left sidebar
  3. Click Create a namespace
  4. Name it WEBHOOKS
  5. Click Add

2. Bind it to your Worker:

  1. Go to Workers & Pages -> click your Worker
  2. Go to Settings -> Bindings
  3. Click Add binding -> KV Namespace
  4. Variable name: WEBHOOKS (must be exactly this)
  5. Select your namespace from the dropdown
  6. Click Save and Deploy

Note

Dashboard bindings can be removed if you later redeploy from GitHub with a wrangler.toml KV section that points somewhere else. For persistent GitHub/CLI deploys, use the CLI method and commit your namespace ID to your fork.

Option B: CLI with Wrangler

Bindings persist across redeploys when configured in wrangler.toml.

# Create the namespace
npx wrangler kv namespace create WEBHOOKS
# Copy the ID from the output

Edit wrangler.toml and uncomment the KV section:

[[kv_namespaces]]
binding = "WEBHOOKS"
id = "paste-your-namespace-id-here"

Redeploy:

npm run deploy

Environment Variables

Secrets (via Wrangler CLI)

Secrets are encrypted and never exposed in logs or code.

Secret Purpose Required
WEBHOOK_TOKEN Shared token for webhook authentication Yes
WEBHOOK_SECRET Legacy fallback name for existing installs No

Set a secret:

npx wrangler secret put WEBHOOK_TOKEN
# Paste your token when prompted

List secrets:

npx wrangler secret list

Delete a secret:

npx wrangler secret delete WEBHOOK_TOKEN

See Security for complete webhook token setup instructions.

Variables (via wrangler.toml)

Non-sensitive configuration stored in wrangler.toml.

Variable Purpose Default
CF_ACCESS_AUD Cloudflare Access audience tag (not set)
CF_ACCESS_TEAM_DOMAIN Cloudflare Access team domain (not set) 
[vars]
CF_ACCESS_AUD = "your-audience-tag"
CF_ACCESS_TEAM_DOMAIN = "your-team.cloudflareaccess.com"

Important

If CF_ACCESS_AUD and CF_ACCESS_TEAM_DOMAIN are not set, the Worker skips JWT validation. The dashboard works but doesn't verify that requests came through Cloudflare Access.

Set these only after creating a Cloudflare Access application for the dashboard. See Security#optional-verify-cloudflare-access-jwts-in-the-worker for why this is recommended, where to find the values, and how to redeploy from a local clone or GitHub Actions.

Local Development (.dev.vars)

For local development with npm run dev:worker, create a .dev.vars file:

WEBHOOK_TOKEN=local-test-token

See .dev.vars.example for a template. This file is gitignored.

wrangler.toml Reference

The wrangler.toml file configures your Worker deployment. Key sections:

Basic Settings

name = "setupmanagerhud"
main = "src/index.ts"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]
  • name: Your Worker name (becomes the subdomain)
  • main: Entry point file
  • compatibility_date: Cloudflare runtime version
  • compatibility_flags: Enable Node.js compatibility

KV Namespace Binding

# Uncomment and fill this in for CLI/GitHub deploys.
# [[kv_namespaces]]
# binding = "WEBHOOKS"
# id = "your-namespace-id"

Durable Object Binding

[[durable_objects.bindings]]
name = "DASHBOARD_ROOM"
class_name = "DashboardRoom"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["DashboardRoom"]

The Durable Object handles WebSocket connections. This is pre-configured and shouldn't need changes.

Static Assets

[assets]
directory = "dist"

The React dashboard is built to dist/ and served as static assets.

Environment Variables

[vars]
CF_ACCESS_AUD = "your-audience-tag"
CF_ACCESS_TEAM_DOMAIN = "your-team.cloudflareaccess.com"

Health Check

Verify your configuration via the health endpoint:

curl https://your-worker.workers.dev/api/health

Response:

{
  "status": "healthy",
  "kv": "connected",
  "durableObject": "available"
}
Field Healthy Value Problem Value
status healthy degraded
kv connected not configured or error
durableObject available unavailable

If any field shows a problem value, see Troubleshooting.

Home

Clone this wiki locally