Operator onboarding

Zero to a running SpeakerOps workspace: install, env names, migrate, seed, first admin, and the demo walk.

Goal and timebox

New human operators should go from a clean machine to a running local workspace without tribal knowledge. The target is under ninety minutes through install, migrate, seed, first admin, and a demo walk of CFP → evaluation → portal → schedule → readiness. Cloudflare dogfood deploy is optional and may take longer because of account setup.

Judges and invited staff who only need to click through the product can skip local install and use the private demo host with an allowlisted email instead.

Prerequisites

You need Node.js 20 or newer, pnpm matching the workspace packageManager pin, and a git clone of the SpeakerOps monorepo. Cloudflare account access is optional until you deploy dogfood or demo.

  1. Confirm node -v reports v20 or higher.
  2. Enable corepack if needed, then confirm pnpm -v matches the workspace pin.
  3. Clone the monorepo and change into the repository root.
  4. Run pnpm install. Do not source deployment secrets into install or CI gates.
node -v
pnpm -v
pnpm install

Environment names only

Copy variable names into a local secrets channel or a gitignored .env / .dev.vars file. Document names only in shared docs. Never commit API keys, magic-link tokens, encryption keys, or Cloudflare tokens.

NameNeeded forPurpose
SPEAKEROPS_DB_PATHLocal DBOptional SQLite path (default .data/speakerops.local.sqlite)
BOOTSTRAP_ADMIN_EMAILFirst adminAllowlisted email for controlled bootstrap
AUTH_DEV_OUTBOXLocal e2e onlySet to 1 to expose magic-link outbox for Playwright — never production default
TURNSTILE_SITE_KEYPublic CFP / WorkerPublic Turnstile site key
TURNSTILE_SECRET_KEYWorker secretTurnstile secret via wrangler secret put
SPEAKEROPS_API_KEYCLI / agentsBearer secret spk_… minted in admin
SPEAKEROPS_API_URLCLI optionalAPI base URL (default http://127.0.0.1:8787)
EMAIL_PROVIDERComms drainsandbox (default), resend, or cloudflare on demo

Migrate, seed, and first admin

Apply linear D1 migrations to local SQLite with the same SQL used on Cloudflare. Seed loads a realistic demo graph so every admin surface has data. First admin is controlled by allowlist and magic-link flow — there is no password database.

  1. Run pnpm db:migrate to apply packages/db/migrations to local SQLite.
  2. Run pnpm seed to load the demo event graph.
  3. Start the API and web apps per repository scripts (typical ports 8787 and 5173).
  4. Open /login, request a magic link for your allowlisted admin email, and complete the exchange.
  5. Confirm you land in admin with access to CFP, submissions, schedule, and settings.
pnpm db:migrate
pnpm seed
# then start API + web per package scripts / AGENTS.md

Demo walk (program path)

After login, walk the product in season order so you see how fields flow from forms to readiness. Keep this Learn handbook open beside the app.

  1. Open Admin → CFP forms. Review or edit the draft form, then understand publish pins an immutable version.
  2. Open the public CFP route for the form slug and submit a test proposal if your host allows it.
  3. Score the submission in evaluation, then record accept, reject, or waitlist on the submissions screen.
  4. As an accepted speaker, open the portal and complete a task or note outstanding work.
  5. Place a session on the schedule studio and resolve any conflict messaging.
  6. Open readiness and confirm outstanding tasks and stats match what you just did.

Gates and optional deploy

Local quality gates must stay non-interactive: typecheck, unit and CI tests, and Playwright inventory proofs run without production credentials. Optional dogfood deploy needs CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in a secrets channel, plus D1 and Worker configuration described in Operations.

  • pnpm typecheck
  • pnpm test:ci
  • pnpm test:e2e (and inventory crawl when required)
  • Optional: dogfood deploy scripts from docs/OPERATIONS.md