Complete stage 7
This commit is contained in:
parent
3e7b89bcad
commit
1f88e291a9
9 changed files with 784 additions and 26 deletions
124
README.md
124
README.md
|
|
@ -2,19 +2,123 @@
|
|||
<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
|
||||
</div>
|
||||
|
||||
# Run and deploy your AI Studio app
|
||||
# Kaboot
|
||||
|
||||
This contains everything you need to run your app locally.
|
||||
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.
|
||||
|
||||
View your app in AI Studio: https://ai.studio/apps/drive/1N0ITrr45ZWdQvXMQNxOULCmJBQyaiWH8
|
||||
## Features
|
||||
|
||||
## Run Locally
|
||||
- **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.
|
||||
|
||||
**Prerequisites:** Node.js
|
||||
## Architecture
|
||||
|
||||
Kaboot is built with a modern decoupled architecture:
|
||||
|
||||
1. Install dependencies:
|
||||
`npm install`
|
||||
2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
|
||||
3. Run the app:
|
||||
`npm run dev`
|
||||
- **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`.
|
||||
|
||||
## Configuration
|
||||
|
||||
Kaboot uses environment variables for configuration. Refer to `.env.example` for a complete list.
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `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) |
|
||||
| `CORS_ORIGIN` | Allowed origin for API requests | `http://localhost:5173` |
|
||||
| `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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue