Self-Hosting Guide

Overview

ClassQuiz is fully open-source under the Mozilla Public License 2.0, enabling you to host your own instance with complete control over your data and customization.

License Compliance: The MPL 2.0 license requires you to publish any modifications you make to the source code. This is a strict requirement, not optional.

While official releases are available, the maintainer recommends running the latest commit from the master branch where CI checks pass, as it contains the most recent bug fixes and improvements.

Prerequisites

Required Software

Docker & Docker Compose

Container orchestration for all services

Git

Version control to clone the repository

OpenSSL

For generating secure secret keys

SSL Certificate

HTTPS is required for proper WebSocket functionality

System Requirements

CPU: 2+ cores recommended
RAM: 4GB minimum, 8GB+ recommended for production
Storage: 10GB+ depending on media uploads
Network: Public IP address or domain name with SSL

Optional Third-Party Services

Email Service (SMTP)

Required for user registration and email verification.

Configure any SMTP server (Gmail, SendGrid, Mailgun, etc.)
Default: Email verification can be disabled

OAuth Providers

Enable single sign-on for users:

Google OAuth: console.cloud.google.com
GitHub OAuth: github.com/settings/developers
Custom OpenID: Any OpenID Connect provider

Captcha Service

Prevent spam registrations:

hCaptcha: hcaptcha.com
reCAPTCHA: google.com/recaptcha

Image Search

Enable image search in quiz editor:

Pixabay API: pixabay.com/api/docs

Error Tracking

Monitor application errors:

Sentry: sentry.io

Installation

Clone the Repository

git clone https://github.com/mawoka-myblock/ClassQuiz.git
cd ClassQuiz

For production deployments, consider using a specific commit or tag for stability:

git checkout <commit-hash>

Configure Frontend Build

Edit frontend/Dockerfile to set build-time environment variables:

# Captcha Configuration
ENV VITE_HCAPTCHA=your_hcaptcha_sitekey_here
ENV VITE_CAPTCHA_ENABLED=true

# OAuth Configuration
ENV VITE_GOOGLE_AUTH_ENABLED=true
ENV VITE_GITHUB_AUTH_ENABLED=true
ENV VITE_CUSTOM_OAUTH_NAME="School SSO"

# Optional: Error Tracking
ENV VITE_SENTRY=your_sentry_dsn_here

These are build-time variables. Changes require rebuilding the frontend container:

docker compose build frontend

Frontend Environment Variables

Variable	Required	Description
`VITE_HCAPTCHA`	No	hCaptcha site key for captcha challenges
`VITE_CAPTCHA_ENABLED`	No	Set to `true` to enable captcha on registration
`VITE_GOOGLE_AUTH_ENABLED`	No	Set to `true` to show Google login button
`VITE_GITHUB_AUTH_ENABLED`	No	Set to `true` to show GitHub login button
`VITE_CUSTOM_OAUTH_NAME`	No	Display name for custom OpenID provider
`VITE_SENTRY`	No	Sentry DSN for frontend error tracking

Configure Backend Services

Edit the docker-compose.yml file to configure the API and worker services.

Essential Configuration

environment:
  # ===== REQUIRED: Change These Values =====
  
  # Your public domain (no trailing slash)
  ROOT_ADDRESS: "https://classquiz.yourdomain.com"
  
  # Generate with: openssl rand -hex 32
  SECRET_KEY: "TOP_SECRET"  # CHANGE THIS!
  
  # ===== Email Configuration =====
  MAIL_SERVER: "smtp.gmail.com"
  MAIL_PORT: "587"
  MAIL_USERNAME: "[email protected]"
  MAIL_PASSWORD: "your-app-password"
  MAIL_ADDRESS: "[email protected]"
  SKIP_EMAIL_VERIFICATION: "False"  # Set to "True" to disable email verification
  
  # ===== Storage Backend =====
  STORAGE_BACKEND: "local"  # Options: "local" or "s3"
  STORAGE_PATH: "/app/data"  # Required if STORAGE_BACKEND=local

Generate Secure Secret Key

Run this command to automatically generate and set a secure secret:

sed -i "s/TOP_SECRET/$(openssl rand -hex 32)/g" docker-compose.yml

Never use the default TOP_SECRET value in production! This would allow attackers to forge authentication tokens.

Configure Storage Backend

ClassQuiz requires a storage backend for uploaded media files.

Local Filesystem
S3-Compatible Storage

Recommended for: Small deployments, single-server setups

docker-compose.yml

environment:
  STORAGE_BACKEND: "local"
  STORAGE_PATH: "/app/data"

volumes:
  - ./uploads:/app/data  # Persist uploads on host

Local storage stores files directly on the server filesystem. Ensure the ./uploads directory has appropriate permissions.

Recommended for: Large deployments, horizontal scaling, CDN integration

docker-compose.yml

environment:
  STORAGE_BACKEND: "s3"
  S3_ACCESS_KEY: "your-access-key"
  S3_SECRET_KEY: "your-secret-key"
  S3_BASE_URL: "https://s3.amazonaws.com"  # Or your Minio URL
  S3_BUCKET_NAME: "classquiz"  # Default bucket name

Compatible with:

Amazon S3
MinIO (self-hosted)
DigitalOcean Spaces
Backblaze B2
Any S3-compatible service

For self-hosted MinIO, add it to your docker-compose.yml:

minio:
  image: minio/minio
  command: server /data --console-address ":9001"
  environment:
    MINIO_ROOT_USER: minioadmin
    MINIO_ROOT_PASSWORD: minioadmin
  ports:
    - "9000:9000"
    - "9001:9001"
  volumes:
    - minio-data:/data

Configure OAuth (Optional)

Enable third-party authentication for easier user registration.

Google OAuth
GitHub OAuth
Custom OpenID

Visit Google Cloud Console
Create a new project or select existing
Navigate to APIs & Services > OAuth consent screen
Configure consent screen with your application details
Go to Credentials > Create Credentials > OAuth Client ID
Set application type to Web application
Add Authorized JavaScript origins:
```
https://classquiz.yourdomain.com
```

Add Authorized redirect URIs:

https://classquiz.yourdomain.com/api/v1/users/oauth/google/auth

Copy the Client ID and Client Secret

Add to docker-compose.yml:

environment:
  GOOGLE_CLIENT_ID: "your-client-id.apps.googleusercontent.com"
  GOOGLE_CLIENT_SECRET: "your-client-secret"

Update frontend/Dockerfile:

ENV VITE_GOOGLE_AUTH_ENABLED=true

Visit GitHub Developer Settings
Click New OAuth App
Fill in application details:
- Homepage URL: https://classquiz.yourdomain.com
- Authorization callback URL: https://classquiz.yourdomain.com/api/v1/users/oauth/github/auth
Click Register application
Generate a new Client Secret
Copy the Client ID and Client Secret

Add to docker-compose.yml:

environment:
  GITHUB_CLIENT_ID: "your-github-client-id"
  GITHUB_CLIENT_SECRET: "your-github-client-secret"

Update frontend/Dockerfile:

ENV VITE_GITHUB_AUTH_ENABLED=true

Configure any OpenID Connect-compliant provider.Add to docker-compose.yml:

environment:
  CUSTOM_OPENID_PROVIDER__CLIENT_ID: "your-client-id"
  CUSTOM_OPENID_PROVIDER__CLIENT_SECRET: "your-client-secret"
  CUSTOM_OPENID_PROVIDER__SERVER_METADATA_URL: "https://provider.com/.well-known/openid-configuration"

Set redirect URI in your provider to:

https://classquiz.yourdomain.com/api/v1/users/oauth/custom/auth

Update frontend/Dockerfile:

ENV VITE_CUSTOM_OAUTH_NAME="Your Provider Name"

The default scopes requested are: openid email profile

Configure Advanced Options

Captcha Protection

environment:
  # Choose ONE captcha provider
  HCAPTCHA_KEY: "your-hcaptcha-secret"     # hCaptcha (recommended)
  # OR
  RECAPTCHA_KEY: "your-recaptcha-secret"   # Google reCAPTCHA

Remember to also set the site key in frontend/Dockerfile.

Image Search

Enable Pixabay integration for quiz images:

environment:
  PIXABAY_API_KEY: "your-pixabay-api-key"

Get your key at pixabay.com/api/docs

Error Tracking

environment:
  SENTRY_DSN: "https://[email protected]/project-id"

Storage Limits

environment:
  FREE_STORAGE_LIMIT: "1074000000"  # 1GB in bytes

Admin and Moderation

environment:
  MODS: '["[email protected]", "[email protected]"]'  # JSON array of moderator emails
  REGISTRATION_DISABLED: "false"  # Set to "true" to disable new registrations

Token Expiration

environment:
  ACCESS_TOKEN_EXPIRE_MINUTES: 30  # Default: 30 minutes
  CACHE_EXPIRY: 86400              # Default: 24 hours (in seconds)

Build and Deploy

Build Containers

docker compose build

This builds:

frontend: SvelteKit frontend (Node.js)
api: FastAPI backend (Python)
worker: ARQ background worker (Python)

Start Services

docker compose up -d

This starts all services:

frontend (port 3000)
api (port 80)
worker
db (PostgreSQL)
redis (cache and queue)
meilisearch (search engine)
proxy (Caddy reverse proxy on port 8000)

Verify Deployment

# Check all containers are running
docker compose ps

# View logs
docker compose logs -f

# Check specific service
docker compose logs -f api

The Caddy proxy listens on port 8000 by default. Change this in docker-compose.yml under the proxy service:

ports:
  - "8080:8080"  # Change 8000 to your preferred port

Configure Reverse Proxy & SSL

ClassQuiz requires HTTPS for proper WebSocket and OAuth functionality.

Using External Nginx
Using Caddy (Standalone)
Using Internal Caddy

/etc/nginx/sites-available/classquiz

server {
    listen 80;
    server_name classquiz.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name classquiz.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # WebSocket support
    location /socket.io/ {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # API endpoints
    location /api/ {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Frontend
    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

If you prefer to manage SSL with an external Caddy instance:

/etc/caddy/Caddyfile

classquiz.yourdomain.com {
    reverse_proxy localhost:8000
}

Caddy automatically obtains and renews SSL certificates from Let’s Encrypt.

The included Caddy proxy can handle SSL if you modify Caddyfile-docker:

Caddyfile-docker

classquiz.yourdomain.com {
    reverse_proxy * http://frontend:3000
    reverse_proxy /api/* http://api:80
    reverse_proxy /openapi.json http://api:80
    reverse_proxy /socket.io/* api:80
}

Update docker-compose.yml:

proxy:
  image: caddy:alpine
  restart: always
  volumes:
    - ./Caddyfile-docker:/etc/caddy/Caddyfile
    - caddy-data:/data
    - caddy-config:/config
  ports:
    - "80:80"
    - "443:443"

volumes:
  data:
  meilisearch-data:
  caddy-data:
  caddy-config:

Architecture Overview

Services

Tech Stack

Frontend

SvelteKit: Modern web framework
TailwindCSS: Utility-first CSS
Socket.IO: Real-time communication

Backend

FastAPI: High-performance Python API
Ormar: Async ORM
ARQ: Background task queue

Database

PostgreSQL: Primary database
Redis: Caching and queues
Meilisearch: Full-text search

Infrastructure

Docker: Containerization
Caddy: Reverse proxy
S3: Optional object storage

Environment Variables Reference

Database & Cache (Do Not Change)

Variable	Default	Description
`DB_URL`	`postgresql://postgres:classquiz@db:5432/classquiz`	PostgreSQL connection string
`REDIS`	`redis://redis:6379/0?decode_responses=True`	Redis connection string
`MEILISEARCH_URL`	`http://meilisearch:7700`	Meilisearch endpoint
`MAX_WORKERS`	`1`	Worker pool size (keep at 1)

Required Configuration

Variable	Required	Description
`ROOT_ADDRESS`	Yes	Public URL (no trailing slash)
`SECRET_KEY`	Yes	32+ character secret for JWT signing
`STORAGE_BACKEND`	Yes	`local` or `s3`

Email Configuration

Variable	Required	Description
`MAIL_SERVER`	Yes	SMTP server hostname
`MAIL_PORT`	Yes	SMTP server port (587 for TLS)
`MAIL_USERNAME`	Yes	SMTP authentication username
`MAIL_PASSWORD`	Yes	SMTP authentication password
`MAIL_ADDRESS`	Yes	Sender email address
`SKIP_EMAIL_VERIFICATION`	No	Set to `True` to disable email verification

Storage Configuration

Variable	Required	Description
`STORAGE_PATH`	If `STORAGE_BACKEND=local`	Absolute path for file storage
`S3_ACCESS_KEY`	If `STORAGE_BACKEND=s3`	S3 access key
`S3_SECRET_KEY`	If `STORAGE_BACKEND=s3`	S3 secret key
`S3_BASE_URL`	If `STORAGE_BACKEND=s3`	S3 endpoint URL
`S3_BUCKET_NAME`	No	S3 bucket name (default: `classquiz`)

OAuth Configuration

Variable	Required	Description
`GOOGLE_CLIENT_ID`	No	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	No	Google OAuth client secret
`GITHUB_CLIENT_ID`	No	GitHub OAuth client ID
`GITHUB_CLIENT_SECRET`	No	GitHub OAuth client secret
`CUSTOM_OPENID_PROVIDER__CLIENT_ID`	No	Custom OIDC client ID
`CUSTOM_OPENID_PROVIDER__CLIENT_SECRET`	No	Custom OIDC client secret
`CUSTOM_OPENID_PROVIDER__SERVER_METADATA_URL`	No	OIDC discovery URL

Optional Features

Variable	Required	Description
`HCAPTCHA_KEY`	No	hCaptcha secret key
`RECAPTCHA_KEY`	No	reCAPTCHA secret key
`PIXABAY_API_KEY`	No	Pixabay API key for image search
`SENTRY_DSN`	No	Sentry error tracking DSN
`TELEMETRY_ENABLED`	No	Enable usage telemetry (default: `true`)
`FREE_STORAGE_LIMIT`	No	Storage quota in bytes (default: 1GB)
`MODS`	No	JSON array of moderator emails
`REGISTRATION_DISABLED`	No	Disable new registrations

Maintenance

Updating ClassQuiz

# Pull latest changes
git pull origin master

# Rebuild and restart
docker compose down
docker compose build
docker compose up -d

Database Backups

# Backup PostgreSQL
docker compose exec db pg_dump -U postgres classquiz > backup.sql

# Restore from backup
docker compose exec -T db psql -U postgres classquiz < backup.sql

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api

# Last 100 lines
docker compose logs --tail=100 api

Restart Services

# Restart all
docker compose restart

# Restart specific service
docker compose restart api

Clean Up

# Remove containers and networks (preserves data)
docker compose down

# Remove everything including volumes (DATA LOSS!)
docker compose down -v

Troubleshooting

OAuth Login Fails

Symptoms: Redirect loops, OAuth errorsSolutions:

Ensure ROOT_ADDRESS matches your public URL exactly (no trailing slash)
Verify redirect URIs in OAuth provider match exactly
Confirm HTTPS is enabled (OAuth requires secure connections)
Check that VITE_GOOGLE_AUTH_ENABLED or VITE_GITHUB_AUTH_ENABLED is set in frontend/Dockerfile

Rebuild frontend after environment variable changes:

docker compose build frontend
docker compose up -d frontend

WebSocket Connection Errors

Symptoms: “Connection refused” in browser console, games don’t startSolutions:

Ensure reverse proxy forwards /socket.io/* to the API
Verify WebSocket upgrade headers are set:
```
Upgrade: websocket
Connection: upgrade
```
Check that HTTPS is enabled (WebSocket over HTTP fails in production)

Test WebSocket endpoint:

curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
  https://classquiz.yourdomain.com/socket.io/

Email Verification Not Working

Symptoms: Users don’t receive verification emailsSolutions:

Verify SMTP credentials in docker-compose.yml
Check API logs for email errors:
```
docker compose logs api | grep -i mail
```
Ensure firewall allows outbound SMTP (port 587 or 465)

Test SMTP connection:

docker compose exec api python -c "import smtplib; s=smtplib.SMTP('smtp.gmail.com', 587); s.starttls(); s.login('user', 'pass'); print('OK')"

Temporarily disable verification for testing:
```
SKIP_EMAIL_VERIFICATION: "True"
```

File Upload Errors

Symptoms: “Storage error” when uploading mediaSolutions:

Local storage: Check directory permissions

chmod -R 755 ./uploads
docker compose restart api

S3 storage: Verify credentials and bucket access

docker compose exec api python -c "from classquiz.storage import Storage; s = Storage(...); print(s.test_connection())"

Check storage limit:

FREE_STORAGE_LIMIT: "5368709120"  # Increase to 5GB

Verify allowed MIME types (source: classquiz/config.py:109):
- Images: PNG, JPEG, GIF, WebP
- Videos: MP4

Database Migration Errors

Symptoms: “Table doesn’t exist” errorsSolutions:

Run migrations manually:

docker compose exec api alembic upgrade head

Check migration status:

docker compose exec api alembic current

If migrations fail, check database connectivity:

docker compose exec api python -c "from classquiz.db.models import db; print(db.database.url)"

Search Not Working

Symptoms: Quiz search returns no resultsSolutions:

Check Meilisearch status:

docker compose ps meilisearch
docker compose logs meilisearch

Rebuild search index:

docker compose exec api python -c "from classquiz.helpers.search import rebuild_index; rebuild_index()"

Verify Meilisearch connection:
```
curl http://localhost:7700/health
```

Security Best Practices

Secret Management

Generate unique SECRET_KEY for each deployment
Never commit secrets to version control
Rotate secrets periodically
Use environment files with restricted permissions

Network Security

Always use HTTPS in production
Restrict database access to Docker network
Keep services updated
Enable fail2ban for brute-force protection

Access Control

Set up moderators with MODS variable
Disable registration if running private instance
Enable captcha to prevent spam
Review OAuth scopes carefully

Backups

Backup database daily
Store media backups separately
Test restoration procedures
Keep backups encrypted

Performance Optimization

Scaling Considerations

Single Server
Load Balanced
Enterprise

Sufficient for most deployments (under 100 concurrent users):

Use local storage
Single instance of each service
PostgreSQL on same host

Resource Limits

Add to services in docker-compose.yml:

api:
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 2G
      reservations:
        cpus: '1'
        memory: 1G

Getting Help

Community Support

Join the Matrix Space for community support and discussions

Report Issues

Found a bug? Open an issue on GitHub

Documentation

Check the official docs for more information

Contribute

Want to contribute? See CONTRIBUTING.md

Remember: You must publish any modifications to the source code under the MPL 2.0 license. This protects the open-source nature of ClassQuiz.

Get Started

Core Features

Configuration

Guides

Developer

​Overview

​Prerequisites

​Required Software

Docker & Docker Compose

Git

OpenSSL

SSL Certificate

​System Requirements

​Optional Third-Party Services

​Installation

​Frontend Environment Variables

​Essential Configuration

​Generate Secure Secret Key

​Captcha Protection

​Image Search

​Error Tracking

​Storage Limits

​Admin and Moderation

​Token Expiration

​Build Containers

​Start Services

​Verify Deployment

​Architecture Overview

​Services

​Tech Stack

Frontend

Backend

Database

Infrastructure

​Environment Variables Reference

​Database & Cache (Do Not Change)

​Required Configuration

​Email Configuration

​Storage Configuration

​OAuth Configuration

​Optional Features

​Maintenance

​Updating ClassQuiz

​Database Backups

​View Logs

​Restart Services

​Clean Up

​Troubleshooting

​Security Best Practices

Secret Management

Network Security

Access Control

Backups

​Performance Optimization

​Scaling Considerations

​Resource Limits

​Getting Help

Community Support

Report Issues

Documentation

Contribute

Build docs developers (and LLMs) love

Overview

Prerequisites

Required Software

System Requirements

Optional Third-Party Services

Installation

Frontend Environment Variables

Essential Configuration

Generate Secure Secret Key

Captcha Protection

Image Search

Error Tracking

Storage Limits

Admin and Moderation

Token Expiration

Build Containers

Start Services

Verify Deployment

Architecture Overview

Services

Tech Stack

Environment Variables Reference

Database & Cache (Do Not Change)

Required Configuration

Email Configuration

Storage Configuration

OAuth Configuration

Optional Features

Maintenance

Updating ClassQuiz

Database Backups

View Logs

Restart Services

Clean Up

Troubleshooting

Security Best Practices

Performance Optimization

Scaling Considerations

Resource Limits

Getting Help