ConferenceOS manual

Self-hosting guide

ConferenceOS is a Next.js application backed by PostgreSQL through Prisma. This guide summarizes the user-facing operating boundary. The canonical deployment, schema, and production record remains docs/DEPLOYMENT.md and the production runbook remains docs/runbooks/production-setup.md.

Core requirements

The bootstrap contract requires:

  • DATABASE_URL for an isolated PostgreSQL database; and
  • NEXT_PUBLIC_APP_URL for the installation's canonical HTTPS origin.

Protected pages require valid Clerk configuration. In production, SECRETS_ENCRYPTION_KEY is also a hard boot requirement. Stripe, Resend, Anthropic, Slack, ESP, webinar, ads, UploadThing, SMS, and other provider integrations are optional and must degrade safely when unset.

Without valid Clerk keys, protected routes fail closed to /setup-required. Without live Stripe configuration, do not present the installation as accepting real payments.

Install locally

  1. Use the repository-supported Node.js version.
  2. Create a PostgreSQL database that is isolated from Preview and production.
  3. Copy the documented environment template and set only local values.
  4. Run npm ci.
  5. Run npx prisma generate.
  6. Apply committed migrations using the repository's approved local procedure.
  7. Optionally run npm run seed:demo only against the isolated local database.
  8. Run npm run dev and open http://localhost:3111.

Demo Mode can be opened with /?demo=1 when the database contains a demo-mode event. It provides fictional, read-only role previews and is useful for verifying the interface without creating privileged accounts.

Validate before deployment

Run the repository's current gates, including:

npx prisma generate
npm run typecheck:ci
npm test
npm run lint
npm run auth:boundary:check
git diff --check
npm run build

Also test these stories against the intended deployment and database:

  • signed-out public event home, schedule, speakers, sponsors, policies, and registration states;
  • /setup-required behavior when authentication is intentionally absent;
  • signed-in organizer and role-scoped access when Clerk is configured;
  • one approved test registration in the same Stripe mode intended for launch;
  • optional-provider unavailable states and, when configured, provider delivery;
  • Demo Mode read-only behavior and server-side mutation rejection.

Database and schema safety

  • Never guess or copy a production database URL into local, Preview, or demo.
  • Never run seeds, resets, destructive migrations, or load tests against a shared or production database.
  • Local npm run build does not authorize or apply a production schema change.
  • The Vercel build wrapper has a guarded additive-only schema path followed by prisma migrate deploy. Read the deployment record before relying on it.
  • Never bypass the guarded path with an ad hoc production migration, and never reintroduce prisma db push.
  • Schema, data migration, branch promotion, and production apply are separate owner-controlled decisions even when code review and CI are green.

Authentication and roles

Configure Clerk for the exact deployment domain. Use site admin only for sitewide administration; use event membership, reviewer invitations, sponsor associations, the checkin role, promoter access, and scoped MCP keys for narrow jobs. Test denial paths as carefully as successful access.

Optional integrations

Configure each provider independently and test its unavailable state before testing the live path. In particular:

  • Stripe controls hosted payment checkout and webhooks.
  • Resend controls transactional email and invitations.
  • Clerk controls accounts and protected routes.
  • Inngest runs durable scheduled and background work.
  • Webinar, ESP, ads, Slack, SMS, AI, and upload providers add specific features without becoming core boot requirements.

Never copy credentials into documentation, screenshots, issue comments, logs, or agent prompts. Provider and DNS mutations remain owner-controlled.

Backups, monitoring, and recovery

Before launch, document database backups and restore testing, provider alerting, deployment rollback, incident contacts, and a break-glass path. Verify the hosted application, not only the deployment status. A green build does not prove that domains, migrations, icons, authentication, webhooks, or external providers work end to end.

Upgrade discipline

Read the release diff, back up the database, test against an isolated copy, run the full validation suite, and rehearse applicable migrations before updating a production branch. After deployment, verify the live SHA, migrations, public routes, protected access, and required providers before announcing success.