trymeapp/SETUP.md

# TryMe Gaming App — Setup Guide (`SETUP.md`)

This guide walks through configuring **Auth0 federated Single Sign-On**, the **Moderator account**, **PostgreSQL vs. SQLite** storage, and **User API Keys**.

---

## 1. Auth0 Federated IdP Configuration

TryMe authenticates students and moderators via Auth0 OIDC Authorization Code flow and RS256 JWKS verification.

### Step 1: Create an Auth0 Application
1. Sign in to the [Auth0 Dashboard](https://manage.auth0.com/) and navigate to **Applications -> Create Application**.
2. Name the application **`TryMe Quiz App`**, select **Regular Web Applications**, and click **Create**.
3. Open the **Settings** tab and note your:
   - **Domain** (e.g., `your-tenant.us.auth0.com`)
   - **Client ID**
   - **Client Secret**

### Step 2: Configure Allowed URLs in Auth0
Set the following URLs in your Auth0 Application settings (replace `http://localhost:8000` with your production domain, e.g., `https://tryme.example.edu`):

- **Allowed Callback URLs**:
  ```text
  http://localhost:8000/api/v1/auth/callback
  ```
- **Allowed Logout URLs**:
  ```text
  http://localhost:8000/
  ```
- **Allowed Web Origins**:
  ```text
  http://localhost:8000
  ```

### Step 3: Enable Federated Connections
Under **Authentication -> Social** or **Enterprise** in Auth0, enable the federated identity providers your students use (Google Workspace for Education, Microsoft Azure AD / Entra ID, GitHub, Apple, etc.) and toggle them on for the **TryMe Quiz App** application.

### Step 4: Pass Auth0 Variables to TryMe
Set these environment variables in `.env`, `docker-compose.yaml`, or `helm-chart/values.yaml`:

```bash
AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your_auth0_client_id
AUTH0_CLIENT_SECRET=your_auth0_client_secret
AUTH0_AUDIENCE=https://tryme-api.example.edu   # Optional API audience
AUTH0_CALLBACK_URL=http://localhost:8000/api/v1/auth/callback
FRONTEND_BASE_URL=http://localhost:8000
DEV_AUTH_ENABLED=false                         # Disable local dev login in production
SESSION_SECRET=generate-a-long-random-secret
```

> **Local Development Without Auth0**: When `DEV_AUTH_ENABLED=true` (the default in `docker-compose.yaml`), TryMe enables a local player sign-in form so you can run, demo, and test all features immediately before connecting an Auth0 tenant.

---

## 2. Moderator Account Setup

The Moderator account can ban disruptive users and remove public quizzes. You can configure it in either of two ways:

1. **Container Environment Variable (`ADMIN_USER`)**:
   Pass `ADMIN_USER` to the container matching the moderator's Auth0 `sub`, email address, or TryMe `nickname`:
   ```bash
   ADMIN_USER=moderator@school.edu
   ```
   When that user signs in, TryMe automatically grants moderator privileges and locks initial moderator claiming.

2. **Initial Launch Claim (When `ADMIN_USER` is Unset)**:
   If `ADMIN_USER` is left empty and zero moderators exist in the database, the **Moderation** tab appears for the first signed-in operator so they can click **Claim moderator account** once at initial launch. Once claimed, subsequent users receive `409 Conflict` if they attempt to claim it.

---

## 3. Database Configuration (PostgreSQL vs. SQLite)

TryMe supports both **PostgreSQL** and **SQLite** via the `DATABASE_URL` environment variable:

- **PostgreSQL (Recommended for Docker Compose & Multi-Replica Kubernetes)**:
  ```bash
  DATABASE_URL=postgresql+psycopg://tryme:tryme_secret@db:5432/trymedb
  ```
  *(Plain `postgresql://...` and `postgres://...` URLs are also normalized automatically.)*

- **SQLite (Local Development or Single-Pod Helm with PVC)**:
  ```bash
  DATABASE_URL=sqlite:///./tryme.db
  ```
  When deploying via Helm with `--set database.mode=sqlite`, the chart automatically provisions and mounts a `PersistentVolumeClaim` (`trymeapp-sqlite-pvc`) at `/data` and configures `DATABASE_URL=sqlite:////data/tryme.db`.

---

## 4. User API Keys & Expiring Old Keys

Every onboarded user can generate personal API keys (`tm_live_...`) from **Profile and API keys** in the UI (or via `POST /api/v1/users/me/api-keys`).

```bash
# Authenticate any API call using X-API-Key
curl -H "X-API-Key: tm_live_your_generated_token" \
     http://localhost:8000/api/v1/quizzes

# Expire an old key immediately via REST API
curl -X POST \
     -H "X-API-Key: tm_live_your_generated_token" \
     http://localhost:8000/api/v1/users/me/api-keys/1/expire
```