External Services Configuration

ClassQuiz relies on several external services to function properly. This guide covers the configuration for PostgreSQL, Redis, Meilisearch, hCaptcha/reCAPTCHA, and optional services like Pixabay.

PostgreSQL Database

ClassQuiz uses PostgreSQL as its primary database for storing users, quizzes, sessions, and all application data.

DB_URL

string

required

PostgreSQL connection URL in the format:postgresql://username:password@host:port/databaseDocker default: postgresql://postgres:classquiz@db:5432/classquizStandalone example: postgresql://postgres:mysecretpassword@localhost:5432/classquiz

PostgreSQL Setup

Docker Compose
Standalone

PostgreSQL is included in the Docker Compose setup:

docker-compose.yml

db:
  image: postgres:14-alpine
  restart: always
  environment:
    POSTGRES_PASSWORD: "classquiz"
    POSTGRES_DB: "classquiz"
  volumes:
    - data:/var/lib/postgresql/data

The connection URL is pre-configured:

DB_URL=postgresql://postgres:classquiz@db:5432/classquiz

Do not change the DB_URL in Docker deployments unless you modify the database service configuration

Install PostgreSQL

Install PostgreSQL 12 or later:

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# macOS
brew install postgresql

Create database

sudo -u postgres psql
CREATE DATABASE classquiz;
CREATE USER classquiz_user WITH PASSWORD 'secure-password';
GRANT ALL PRIVILEGES ON DATABASE classquiz TO classquiz_user;

Configure connection

DB_URL=postgresql://classquiz_user:secure-password@localhost:5432/classquiz

Redis Cache

Redis is used for caching, session management, OAuth state storage, and background job queues.

REDIS

string

required

Redis connection URL in the format:redis://host:port/db?decode_responses=TrueDocker default: redis://redis:6379/0?decode_responses=TrueStandalone example: redis://localhost:6379/0?decode_responses=True

The decode_responses=True parameter is required for proper string handling

CACHE_EXPIRY

integer

default:"86400"

Default cache expiration time in seconds.Default: 86400 seconds (24 hours)

Redis Setup

Docker Compose
Standalone

Redis is included in the Docker Compose setup:

docker-compose.yml

redis:
  image: redis:alpine
  restart: always
  healthcheck:
    test: ["CMD", "redis-cli", "ping"]

Connection is pre-configured:

REDIS=redis://redis:6379/0?decode_responses=True

Install Redis

# Ubuntu/Debian
sudo apt-get install redis-server

# macOS
brew install redis

Start Redis

# Ubuntu/Debian
sudo systemctl start redis

# macOS
brew services start redis

Configure connection

REDIS=redis://localhost:6379/0?decode_responses=True

Meilisearch

Meilisearch provides fast, typo-tolerant search functionality for quizzes.

MEILISEARCH_URL

string

required

URL of your Meilisearch instance.Docker default: http://meilisearch:7700Standalone default: http://127.0.0.1:7700

MEILISEARCH_INDEX

string

default:"classquiz"

Name of the Meilisearch index used for storing quiz search data.

Meilisearch Setup

Docker Compose
Standalone

Meilisearch is included in the Docker Compose setup:

docker-compose.yml

meilisearch:
  image: getmeili/meilisearch:v0.28.0
  restart: always
  environment:
    MEILI_NO_ANALYTICS: "true"
  volumes:
    - meilisearch-data:/data.ms

Configuration:

MEILISEARCH_URL=http://meilisearch:7700
MEILISEARCH_INDEX=classquiz

Install Meilisearch

# Download and install
curl -L https://install.meilisearch.com | sh

# Or use Docker
docker run -d -p 7700:7700 \
  -v $(pwd)/meili_data:/meili_data \
  getmeili/meilisearch:v0.28.0

Start Meilisearch

./meilisearch

Configure connection

MEILISEARCH_URL=http://127.0.0.1:7700
MEILISEARCH_INDEX=classquiz

Meilisearch indexes are automatically created and configured by ClassQuiz on first use.

Captcha Services

Protect registration and login forms from bots using hCaptcha or Google reCAPTCHA.

HCAPTCHA_KEY

string

hCaptcha secret key for server-side verification.Get your key from: hCaptcha Dashboard

RECAPTCHA_KEY

string

Google reCAPTCHA secret key for server-side verification.Get your key from: reCAPTCHA Admin Console

Both captcha services are optional. If neither is configured, captcha verification will be skipped.

hCaptcha Setup

Create hCaptcha account

Add your site

Go to Sites
Add a new site with your domain
Copy the Secret Key

Configure ClassQuiz

HCAPTCHA_KEY=your-secret-key-here

reCAPTCHA Setup

Go to reCAPTCHA Admin

Configure reCAPTCHA

Choose reCAPTCHA v2 (“I’m not a robot” checkbox)
Add your domain
Accept terms and submit
Copy the Secret Key

Configure ClassQuiz

RECAPTCHA_KEY=your-secret-key-here

Optional Services

Pixabay API

Integrate Pixabay image search into the quiz editor.

PIXABAY_API_KEY

string

API key for Pixabay integration.Get your key from: Pixabay API Documentation

Create Pixabay account

Get API key

Navigate to API Documentation and find your API key

Configure ClassQuiz

PIXABAY_API_KEY=your-api-key-here

Mapbox (Not Currently Used)

Mapbox configuration is present in the codebase but not actively used in the current version.

Complete External Services Configuration

# Database
DB_URL=postgresql://postgres:classquiz@db:5432/classquiz

# Redis
REDIS=redis://redis:6379/0?decode_responses=True
CACHE_EXPIRY=86400

# Meilisearch
MEILISEARCH_URL=http://meilisearch:7700
MEILISEARCH_INDEX=classquiz

# Captcha (optional)
HCAPTCHA_KEY=your-hcaptcha-secret
# RECAPTCHA_KEY=your-recaptcha-secret

# Optional services
PIXABAY_API_KEY=your-pixabay-key

Health Checks

Verify that external services are running correctly:

PostgreSQL
Redis
Meilisearch
Docker Services

# Test connection
psql postgresql://postgres:classquiz@localhost:5432/classquiz -c "SELECT 1;"

# Check if database exists
psql -U postgres -lqt | cut -d \| -f 1 | grep -qw classquiz

# Test connection
redis-cli ping

# Check info
redis-cli INFO server

# Check health
curl http://localhost:7700/health

# List indexes
curl http://localhost:7700/indexes

# Check all service health
docker-compose ps

# View logs
docker-compose logs db
docker-compose logs redis
docker-compose logs meilisearch

Troubleshooting

Database connection refused

Check that:

PostgreSQL is running: systemctl status postgresql
Port 5432 is not blocked by firewall
Connection URL is correct (host, port, username, password)
Database exists: psql -U postgres -l

Test connection:

psql postgresql://username:password@host:port/database

Redis connection failed

Verify:

Redis is running: redis-cli ping
Redis is listening on correct port: netstat -tlnp | grep 6379
No authentication is required (or correct password is provided)
decode_responses=True parameter is present in the URL

Meilisearch not indexing

Common issues:

Meilisearch service not running
Incorrect MEILISEARCH_URL
Network connectivity issues
Disk space full (check Meilisearch data directory)

Check Meilisearch logs:

docker-compose logs meilisearch

Captcha verification failing

Verify:

You’re using the Secret Key (not Site Key) in HCAPTCHA_KEY/RECAPTCHA_KEY
Your domain is registered in the captcha service dashboard
Client-side captcha is correctly implemented with the Site Key
No network issues preventing server-side verification

Performance Tuning

PostgreSQL

-- Increase shared buffers (recommended: 25% of RAM)
ALTER SYSTEM SET shared_buffers = '256MB';

-- Enable query planning cache
ALTER SYSTEM SET plan_cache_mode = 'auto';

-- Increase worker processes
ALTER SYSTEM SET max_worker_processes = 4;

Redis

# redis.conf
maxmemory 256mb
maxmemory-policy allkeys-lru
save ""  # Disable persistence for pure cache

Meilisearch

For large datasets, consider:

Increasing memory allocation
Using dedicated Meilisearch server
Configuring custom ranking rules
Setting up replica for high availability

Security Best Practices

Never expose database or Redis ports directly to the internet. Use firewall rules and VPCs to restrict access.

Use strong passwords for PostgreSQL and Redis
Enable SSL/TLS for database connections in production
Regularly backup PostgreSQL data
Implement Redis authentication with requirepass
Use Meilisearch master keys in production
Rotate API keys periodically
Monitor service logs for suspicious activity

Monitoring

Consider implementing monitoring for:

Database query performance (pg_stat_statements)
Redis memory usage and hit rates
Meilisearch index size and search latency
Connection pool utilization
Error rates and response times

Tools: Prometheus, Grafana, pgAdmin, RedisInsight

Next Steps

Environment Variables

Complete environment variable reference

Storage Configuration

Configure file storage backends

Get Started

Core Features

Configuration

Guides

Developer

External Services Configuration

PostgreSQL Database

PostgreSQL Setup

Redis Cache

Redis Setup

Meilisearch

Meilisearch Setup

Captcha Services

hCaptcha Setup

reCAPTCHA Setup

Optional Services

Pixabay API

Mapbox (Not Currently Used)

Complete External Services Configuration

Health Checks

Troubleshooting

Performance Tuning

PostgreSQL

Redis

Meilisearch

Security Best Practices

Monitoring

Next Steps

Environment Variables

Storage Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Guides

Developer

​PostgreSQL Database

​PostgreSQL Setup

​Redis Cache

​Redis Setup

​Meilisearch

​Meilisearch Setup

​Captcha Services

​hCaptcha Setup

​reCAPTCHA Setup

​Optional Services

​Pixabay API

​Mapbox (Not Currently Used)

​Complete External Services Configuration

​Health Checks

​Troubleshooting

​Performance Tuning

​PostgreSQL

​Redis

​Meilisearch

​Security Best Practices

​Monitoring

​Next Steps

Environment Variables

Storage Configuration

Build docs developers (and LLMs) love

PostgreSQL Database

PostgreSQL Setup

Redis Cache

Redis Setup

Meilisearch

Meilisearch Setup

Captcha Services

hCaptcha Setup

reCAPTCHA Setup

Optional Services

Pixabay API

Mapbox (Not Currently Used)

Complete External Services Configuration

Health Checks

Troubleshooting

Performance Tuning

PostgreSQL

Redis

Meilisearch

Security Best Practices

Monitoring

Next Steps