Quick Start

This guide will get you up and running with Respondeo in just a few minutes.

git clone <repository-url>
cd quiz-app
bun install

docker compose up -d

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Auth (generate secret with: openssl rand -base64 32)
BETTER_AUTH_SECRET=your-32-character-secret-here
BETTER_AUTH_URL=http://localhost:3000

# OIDC Provider (example: Keycloak)
OIDC_ISSUER=https://auth.example.com/realms/your-realm
OIDC_CLIENT_ID=quiz-app
OIDC_CLIENT_SECRET=your-client-secret

# Database
DATABASE_URL=postgresql://quiz_app:strongpassword@localhost:5432/quiz_app

# Optional: Caching
REDIS_URL=redis://:strongvalkeypassword@localhost:6379

bun run db:migrate

bun run dev

What's Next?

Now that you have the app running:

1. Sign in with your OIDC provider
2. Configure RBAC to set up roles and permissions — see RBAC Guide
3. Create your first quiz at /quiz/new
4. Explore features:
   • Enable AI quiz generation
   • Set up image search
   • Configure caching
5. Use the API — see API Reference

Troubleshooting

"Database connection failed"

Make sure PostgreSQL is running:

docker compose ps

Or check your local PostgreSQL installation:

pg_isready

"OIDC authentication error"

1. Verify your OIDC_ISSUER URL is accessible
2. Check that the callback URL is configured: http://localhost:3000/api/auth/callback/hogwarts
3. Ensure OIDC_CLIENT_ID and OIDC_CLIENT_SECRET are correct

"Session not persisting"

Make sure BETTER_AUTH_SECRET is set and is at least 32 characters long.

Production Deployment

Ready to deploy? Check out the Deployment Guide.