Run your own live quiz server

• Uploaded documents, quizzes and results stay in a database you control.
• You can put it on a school, university or company network and review the code before you do.
• You can change it — a different scoring curve, a new question type, your own branding — under the AGPL-3.0 terms.

Required

• Node.js 18 or newer (20 LTS recommended). Yarn 4 comes via Corepack.
• PostgreSQL. Locally, yarn setup starts one in Docker.
• Redis. The game server keeps live game state there and won't start without it.
• Google OAuth credentials. Google is the only sign-in method, so without them nobody can log in to host.
• Somewhere to run a long-lived Node process for the Socket.IO game server — a container or VM host, not a serverless function.

Optional

• A Gemini API key, to turn on AI quiz generation.
• Cloudinary credentials, for image questions.
• Upstash Redis credentials with RATELIMIT=ON, for rate limiting.
• The Python AI service (apps/ai) with pgvector, for Knowledge Spaces. Without it, that part of the app stays hidden.

1. 1

   Install Docker and Node.js, then clone the repository.

2. 2

   Run corepack enable, yarn install and yarn setup. Setup starts Postgres and Redis in Docker, writes the .env files with a shared auth secret, and pushes the database schema. It's safe to re-run.

3. 3

   Add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to apps/web/.env (redirect URI: http://localhost:3000/api/auth/callback/google).

4. 4

   Run yarn dev. The web app is on port 3000 and the API on port 3001.

git clone https://github.com/buzrr/buzrr.git
cd buzrr
corepack enable
yarn install
yarn setup     # Postgres + Redis in Docker, .env files, schema
# add GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET to apps/web/.env
yarn dev       # web :3000, api :3001

• Deploy apps/web to a Node host (the repo's own deployment uses Vercel) and apps/server to a container or VM host such as Render, Railway or Fly.
• Set BETTER_AUTH_SECRET to the same value on both apps — the web app signs tokens and the server verifies them.
• Set WEB_ORIGIN on the server to your site's URL. If it's unset, the API accepts any origin.
• Apply the committed migrations with prisma migrate deploy rather than db push.
• Seed the 1v1 question pool (yarn workspace @buzrr/prisma seed:duel), or duels will report that there are no questions.

• No billing: every account gets Pro limits — 250 players per room, unlimited quizzes and 10 AI generations a week. An operator can raise an individual host's room cap in the database (the hostSizeLimit column).
• AI generation runs on your own Gemini key, so its cost and data handling are between you and Google.
• Duel questions come from public quizzes approved in the moderation queue. The API can't grant the superadmin role, so give your own account superadmin in the database to manage moderators.
• Bot opponents in 1v1 matchmaking are on by default; set DUEL_BOTS=OFF to disable them.

• There's no one-click installer or official Docker image for the web and server apps. The bundled docker-compose file only runs the local databases.
• Documentation is the README, ARCHITECTURE.md and the docs folder in the repository.
• Redis is required for all live play and matchmaking. If it goes down, games stop.

Rather not run servers? The hosted version has a free plan.

• Buzrr as an open-source quiz platformWhat's in the AGPL-3.0 codebase, how it's built, and how to contribute.
• Kahoot! alternativeLive rooms with a code, speed scoring and leaderboards — open source, self-hostable, plus ranked 1v1 battles.
• Slido alternativeFor Slido quiz, trivia and game sessions — not its Q&A or polls.
• Knowledge checks for training sessionsTurn a training document into a live quiz at the end of the session: generate questions from the material, check what landed, and keep the whole thing on your own servers if you need to.
• Quiz rounds for college fests and club eventsFest quiz rounds, society inductions, freshers' nights, hackathon breaks — Buzrr gets a hall full of people answering on their own phones with one QR code on the screen.