Installation

Prerequisites

Tool	Version	Purpose
Docker	≥ 24	Container runtime
Docker Compose	≥ 2.20 (bundled with Docker Desktop)	Service orchestration
Git	any	Repository checkout

No local Node.js or Python installation is required — all services run inside containers.

Setup

1. Clone the repository

git clone https://github.com/Gravefax/SQS-Team-11
cd Quizzard-of-Oz

2. Create the environment file

cp .env.example .env

The default values in .env.example work out of the box for local development. The Keycloak quizzard realm is imported automatically on first startup — no manual configuration is required.

Note: TRIVIA_API_KEY is optional. The Trivia API works without a key, but rate limits may apply for heavy usage. Leave the value empty to use the unauthenticated tier.

3. Start all services

docker compose up -d

Docker Compose starts four services in dependency order:

Service	URL	Description
PostgreSQL	—	Persistent database (internal only)
Keycloak	http://localhost:8080	Identity provider; admin UI at /auth/admin
Backend	http://localhost:8000	FastAPI backend; OpenAPI docs at /docs
Frontend	http://localhost:3000	Next.js application

The backend waits for PostgreSQL and Keycloak to pass their health checks before accepting traffic. The frontend starts after the backend is healthy.

4. Open the application

Navigate to http://localhost:3000 and use the Register link to create an account via the Keycloak login page.

Verifying the Stack

Check that all services are running:

docker compose ps

All four services should show running or healthy. Check the backend health endpoint:

curl http://localhost:8000/health

Stopping and Cleaning Up

Stop all services (data is preserved in Docker volumes):

docker compose down

Stop and remove all data volumes (full reset):

docker compose down -v

Local Development Without Docker

For development with hot reload, each component can be started individually. Prerequisites for this approach:

• Python 3.12+ (backend)

• Node.js 22+ and pnpm (frontend)

• A running PostgreSQL 18 instance and Keycloak 26

Backend

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Frontend

cd frontend/quizzard-of-oz
pnpm install
pnpm dev

Ensure the .env values for KEYCLOAK_URL, POSTGRES_HOST, and NEXT_PUBLIC_KEYCLOAK_URL point to the correct host addresses for your local services.

Keycloak Admin Access

The Keycloak admin console is available at http://localhost:8080/auth/admin with the default credentials admin / admin (configured in .env via KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD).

The quizzard realm is automatically imported from keycloak/realm-export.json on startup. The quizzard-frontend client is pre-configured for PKCE login from http://localhost:3000.