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 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:

  http://localhost:8000/api/v1/auth/callback
  

• Allowed Logout URLs:

  http://localhost:8000/
  

• Allowed Web Origins:

  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:

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:

   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):

  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):

  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).

# 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