2026-01-14 19:44:13 -07:00

4.7 KiB

Raw Blame History

Kaboot

Kaboot is an AI-powered quiz party game inspired by Kahoot. It leverages the Google Gemini API to instantly generate engaging quizzes on any topic, allowing users to host and join multiplayer games with ease.

Features

AI Quiz Generation: Create full quizzes in seconds by simply providing a topic or prompt using Google Gemini.
Real-time Multiplayer: Host games and have players join via game pins using Peer-to-Peer technology.
Single-player Arcade Mode: Play against AI bots to sharpen your skills.
Secure Authentication: Integrated with Authentik for robust OIDC-based user management.
Quiz Library: Save, manage, and reuse your AI-generated quizzes.
Dynamic UI: A premium, responsive interface built with React, Framer Motion, and Lucide.

Architecture

Kaboot is built with a modern decoupled architecture:

Frontend: React (Vite) with PeerJS for real-time communication.
Backend: Node.js Express server managing the quiz database and session state.
Database: SQLite (Better-SQLite3) for lightweight, reliable data storage.
Identity Provider: Authentik (running in Docker) providing OIDC authentication.
Infrastructure: Redis and PostgreSQL (supporting Authentik).
AI Engine: Google Gemini API for intelligent content generation.

Prerequisites

Before you begin, ensure you have the following installed:

Docker & Docker Compose: For running the backend services and authentication.
Node.js (v18+): For local frontend development.
Google Gemini API Key: Required for AI quiz generation.

Quick Start

The fastest way to get Kaboot running is using Docker Compose.

1. Initialize Environment

Run the setup script to generate necessary secrets and create your .env file:

chmod +x scripts/setup.sh
./scripts/setup.sh

2. Configure Gemini API

Open the newly created .env file and add your Gemini API key:

GEMINI_API_KEY=your_api_key_here

3. Start Services

Launch the entire stack using Docker Compose:

docker compose up -d

This will start:

Authentik (Port 9000)
PostgreSQL & Redis (Internal)
Kaboot Backend (Port 3001)

4. Setup Authentication

Follow the Authentik Setup Guide to configure the OIDC provider.

Development Setup

If you want to run the frontend in development mode with hot-reloading:

Install Dependencies:
```
npm install
```
Run Development Server:
```
npm run dev
```
The frontend will be available at http://localhost:5173.

Mobile/Network Access

To access the dev server from other devices (phones, tablets):

Run setup script - it auto-detects your IP:
```
./scripts/setup.sh
```
Update Authentik redirect URIs to include your IP (e.g., http://192.168.1.100:5173/callback)
Start dev server with host binding:
```
npm run dev -- --host
```
Access from mobile via http://<your-ip>:5173

Configuration

Kaboot uses environment variables for configuration. Refer to .env.example for a complete list.

Variable	Description	Default
`KABOOT_HOST`	Host IP/domain for network access	`localhost`
`KABOOT_FRONTEND_PORT`	Port for the frontend dev server	`5173`
`KABOOT_BACKEND_PORT`	Port for the Express backend	`3001`
`AUTHENTIK_PORT_HTTP`	Port for Authentik web interface	`9000`
`GEMINI_API_KEY`	Your Google Gemini API key	(Required)
`PG_PASS`	PostgreSQL password for Authentik	(Generated)
`AUTHENTIK_SECRET_KEY`	Secret key for Authentik	(Generated)

Testing

Backend Tests

To run the backend test suite:

cd server
npm install
npm test

Documentation

Troubleshooting

Authentik Initial Setup: If you can't access the setup page, ensure authentik-server container is healthy using docker compose ps.
CORS Errors: Verify that CORS_ORIGIN in your .env matches your frontend URL.
Gemini API Issues: Ensure your API key is valid and has sufficient quota. Check the browser console for specific error messages from the GenAI SDK.
Database Locked: If you encounter SQLite locking issues, ensure only one instance of the backend is writing to the database volume.

View your app in AI Studio: https://ai.studio/apps/drive/1N0ITrr45ZWdQvXMQNxOULCmJBQyaiWH8

4.7 KiB Raw Blame History