The hub
The hub is the API behind aurral.org’s community features. It is a Hono app on Cloudflare Workers in hub/, and it stores its data in D1. Aurral works without it. See ADR 0014 for what it stores and why.
Run it locally
Section titled “Run it locally”pnpm eden up --with hubThis applies the migrations to a local D1 database in .eden/hub and serves the hub on wrangler’s local runtime. Its account pages sign in through Eden’s OIDC stand-in, as ada or grace, and Eden points Aurral’s AURRAL_SHARE_ORIGIN at it, so linking in Settings > Profile goes to the local hub. pnpm eden status prints the address. The hub’s tests use the same runtime through hub/testing.ts.
Change the database
Section titled “Change the database”Add a numbered file to hub/migrations. Never edit a migration that has shipped. Migrations only add: a released Aurral and every fork call the hub deployed from main, so the hub keeps answering the routes and fields they read. Routes live under /v1.
Deploy
Section titled “Deploy”On every push to main that changes hub/, the Hub workflow applies migrations and deploys the preview environment, then production if the preview succeeded. The preview runs on workers.dev with its own database. To redeploy one environment, run the workflow by hand and pick it. Deploys need the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID repository secrets, with permission to edit Workers, D1, and the zone’s Workers routes.
Run your own
Section titled “Run your own”A fork that wants its own community features runs its own hub. Hubs don’t talk to each other.
- Create a D1 database with
pnpm exec wrangler d1 create <name>inhub/. - In
hub/wrangler.jsonc, set thedatabase_id, replace the domain in the routes, and setHUB_ORIGINto your origin. - Create a GitHub OAuth app, a Discord application, or both, with the callback
<origin>/v1/auth/callback/githubor/discord. - Set the secrets with
pnpm exec wrangler secret put <name> --env "":AUTH_SECRET(a long random string), plusGITHUB_CLIENT_IDandGITHUB_CLIENT_SECRET, orDISCORD_CLIENT_IDandDISCORD_CLIENT_SECRET. Sign-in shows only the providers you set. - Run
pnpm exec wrangler d1 migrations apply DB --remote --env "", thenpnpm exec wrangler deploy --env "".