143 lines
4.7 KiB
Markdown
143 lines
4.7 KiB
Markdown
<div align="center">
|
|
<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
|
|
</div>
|
|
|
|
# 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:
|
|
|
|
```bash
|
|
chmod +x scripts/setup.sh
|
|
./scripts/setup.sh
|
|
```
|
|
|
|
### 2. Configure Gemini API
|
|
Open the newly created `.env` file and add your Gemini API key:
|
|
|
|
```env
|
|
GEMINI_API_KEY=your_api_key_here
|
|
```
|
|
|
|
### 3. Start Services
|
|
Launch the entire stack using Docker Compose:
|
|
|
|
```bash
|
|
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](docs/AUTHENTIK_SETUP.md) to configure the OIDC provider.
|
|
|
|
## Development Setup
|
|
|
|
If you want to run the frontend in development mode with hot-reloading:
|
|
|
|
1. **Install Dependencies**:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
2. **Run Development Server**:
|
|
```bash
|
|
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):
|
|
|
|
1. **Run setup script** - it auto-detects your IP:
|
|
```bash
|
|
./scripts/setup.sh
|
|
```
|
|
|
|
2. **Update Authentik redirect URIs** to include your IP (e.g., `http://192.168.1.100:5173/callback`)
|
|
|
|
3. **Start dev server with host binding**:
|
|
```bash
|
|
npm run dev -- --host
|
|
```
|
|
|
|
4. **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:
|
|
|
|
```bash
|
|
cd server
|
|
npm install
|
|
npm test
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Authentik Configuration](docs/AUTHENTIK_SETUP.md)
|
|
- [API Reference](docs/API.md)
|
|
|
|
## 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](https://ai.studio/apps/drive/1N0ITrr45ZWdQvXMQNxOULCmJBQyaiWH8)
|