Self-hosting

Run your own live quiz server

Buzrr is open source, so you can run the whole thing — live rooms, 1v1 battles, AI generation — on your own infrastructure with one command, even on a network with no internet access.

Can Buzrr be self-hosted?

Yes. Buzrr is AGPL-3.0 open source and the repository includes everything needed to run it: a Next.js web app, a NestJS game server, a PostgreSQL schema with migrations, and an optional Python AI service. One docker compose up runs the stack with local accounts and local image storage, and no outside services. Self-hosted instances run with billing off, and every account gets Pro limits.

What is Buzrr?

Buzrr is an open-source quiz platform that runs in the browser. A host builds a quiz — by hand or with AI — from multiple-choice, true/false, poll, word-cloud, rating and open-text questions, and opens a live room; players join from their own phones or laptops with a 6-character code, a link or a QR code, without creating an account. Signed-in users can also play ranked 1v1 quiz battles. Buzrr is licensed under AGPL-3.0, so anyone can read the code or run their own instance.

Why teams self-host

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

What you need

Required

  • Docker with Compose v2.24 or newer.
  • About 4 GB of free RAM while the images build, and much less to run them.
  • Free ports 3000 (web) and 3001 (API). Postgres and Redis are published on localhost only, for backups and debugging.

Optional

  • A model for AI quiz generation: a Gemini API key, any OpenAI-compatible server, or the bundled Ollama, which runs on your own hardware.
  • The AI service (the compose ai profile), for Knowledge Spaces. Without it, that part of the app stays hidden.
  • Google OAuth credentials, if you want Google sign-in alongside local accounts.
  • An S3-compatible bucket or Cloudinary, if you'd rather not keep question images on a Docker volume.

Run it

From the repository's self-hosting guide. The whole install is one command.

  1. 1

    Install Docker, then clone the repository.

  2. 2

    Run docker compose up -d. The first run builds the images and takes a few minutes. It starts Postgres and Redis, applies migrations, seeds starter duel questions and generates the auth secret.

  3. 3

    Open http://localhost:3000 and create an account. Nothing here calls an outside service.

git clone https://github.com/buzrr/buzrr && cd buzrr
docker compose up -d     # first run builds the images (a few minutes)
# then open http://localhost:3000 and create an account

Going to production

  • Set PUBLIC_WEB_URL and PUBLIC_API_URL to addresses players' devices can reach, in a .env file next to docker-compose.yml, then run docker compose up -d --build. The API address is compiled into the web app, so it needs the rebuild.
  • For the public internet, put a reverse proxy with HTTPS in front of both ports, such as Caddy, nginx or Traefik.
  • Never expose Postgres (5432) or Redis (6379) publicly: Postgres uses a default password and Redis has none, and Docker's published ports can bypass host firewalls such as ufw. The compose file binds both to 127.0.0.1, so keep that binding.
  • Once your hosts have accounts, close registration with AUTH_EMAIL_SIGNUP=OFF.
  • Back up the Postgres database and the uploads volume. To upgrade, run git pull and docker compose up -d --build; migrations apply before the API starts.

What's different on your own instance

  • No billing: every account gets Pro limits — 250 players per room, unlimited quizzes, 10 AI generations a week, question images and PDF session reports. An operator can raise an individual host's room cap in the database (the hostSizeLimit column).
  • AI stays off until you configure a model. With a local model, nothing leaves your network; with a hosted one, its cost and data handling are between you and that provider.
  • 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.

Know before you start

  • There are no prebuilt images to pull: the first docker compose up builds them from source.
  • Local accounts have no password reset, because an offline server can't send email.
  • 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.

Related pages

Clone it and run docker compose up

The whole install is one command. Questions and bug reports go to GitHub issues.