README.md

July 5, 2026 · View on GitHub


Visitor Badge Docker Pulls

🧩 What is this project?

Razzia is a straightforward and open-source quiz platform, allowing users to host it on their own server for smaller events.

Disclaimer: Razzia is an independent, open-source software project. It is not affiliated with, endorsed by, or sponsored by any third-party quiz platform or service. Any resemblance to other quiz platforms is purely incidental.

Login Manager Room Question Screen

⚙️ Prerequisites

Choose one of the following deployment methods:

Without Docker

  • Node.js : version 24 or higher
  • PNPM : version 10.16 or higher (learn more here)

With Docker

  • Docker and Docker Compose

📖 Getting Started

Choose your deployment method:

Using Docker Compose (recommended): You can find the docker compose configuration in the repository: docker-compose.yml

docker compose up -d

Or using Docker directly:

docker run -d \
  -p 3000:3000 \
  -v ./config:/app/config \
  ralex91/razzia:latest

The image is also published on the GitHub Container Registry, if you prefer using it instead of Docker Hub:

docker run -d \
  -p 3000:3000 \
  -v ./config:/app/config \
  ghcr.io/ralex91/razzia:latest

Configuration Volume: The -v ./config:/app/config option mounts a local config folder to persist your game settings and quizzes. This allows you to:

  • Edit your configuration files directly on your host machine
  • Keep your settings when updating the container
  • Easily backup your quizzes and game configuration

The folder will be created automatically on first run with an example quiz to get you started.

The application will be available at http://localhost:3000

🛠️ Without Docker

  1. Clone the repository:
git clone https://github.com/Ralex91/Razzia.git
cd ./Razzia
  1. Install dependencies:
pnpm install
  1. Build and start the application:
# Development mode
pnpm dev

# Production mode
pnpm build
pnpm start

⚙️ Configuration

⚠️ Required: set a manager password in config/game.json before going live.

{
  "managerPassword": "PASSWORD"
}

managerPassword must be changed from the default "PASSWORD" value, otherwise manager access is blocked.

📚 Documentation

  • Configuration: manager password, via the config folder.
  • Quiz: creating and structuring quizzes.
  • Branding: optional custom theming.
  • Reverse Proxy: running behind Traefik, Nginx, Caddy, or another reverse proxy.
  • WebSocket Protocol: build a custom client (e.g. an ESP32 physical buzzer).

Full index in docs/.

🎮 How to Play

  1. Access the manager interface at http://localhost:3000/manager
  2. Enter the manager password (defined in config/game.json)
  3. Share the game URL (http://localhost:3000) and room code with participants
  4. Wait for players to join
  5. Click the start button to begin the game

📝 Contributing

Contributions are welcome! Please read the CONTRIBUTING.md guide before submitting a pull request.

For bug reports or feature requests, please create an issue.

⭐ Star History

Star History Chart