Skip to content

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.

Terminal window
pnpm eden up --with hub

This 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.

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.

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.

A fork that wants its own community features runs its own hub. Hubs don’t talk to each other.

  1. Create a D1 database with pnpm exec wrangler d1 create <name> in hub/.
  2. In hub/wrangler.jsonc, set the database_id, replace the domain in the routes, and set HUB_ORIGIN to your origin.
  3. Create a GitHub OAuth app, a Discord application, or both, with the callback <origin>/v1/auth/callback/github or /discord.
  4. Set the secrets with pnpm exec wrangler secret put <name> --env "": AUTH_SECRET (a long random string), plus GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET, or DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET. Sign-in shows only the providers you set.
  5. Run pnpm exec wrangler d1 migrations apply DB --remote --env "", then pnpm exec wrangler deploy --env "".