Skip to main content

Configuration

TriviaFlow follows the 12-Factor App methodology, meaning all configuration is stored in Environment Variables. You don't need to touch a single line of Python code to change the database, switch languages, or secure your server.

All configuration happens in the .env file located in the root directory.

1. Initial Setup​

First, create your production configuration file by copying the example template:

cp .env.example .env
nano .env

Now, let's go through the sections one by one.

2. Security Settings (Critical)​

These settings determine if your server is safe from attacks. Do not skip this section.

SECRET_KEY​

A long, random string used by Django to sign session cookies and cryptographic tokens.

  • Requirement: Must be kept secret.
  • Generation: Run openssl rand -hex 32 in your terminal and paste the output here.
  • Example: e8f39...a72b

DEBUG​

Toggles the development mode.

  • Production Value: False
  • Why? If set to True, error pages will expose your source code, environment variables, and database structure to the public.
  • Default: False

ALLOWED_HOSTS​

A comma-separated list of domain names that this server is allowed to serve. This prevents HTTP Host header attacks.

  • Format: domain.com,sub.domain.com,1.2.3.4
  • Example: quiz.your-domain.com

CSRF_TRUSTED_ORIGINS​

Required for Django to accept form submissions (like logins) over HTTPS.

  • Format: Must include the scheme (https://).
  • Example: https://quiz.your-domain.com
Common Pitfall

If you see a "CSRF verification failed" error when trying to log in, you likely forgot to add your domain to CSRF_TRUSTED_ORIGINS.

3. Game Customization​

Adjust the gameplay experience without restarting the server.

VariableDefaultDescription
UI_LANGUAGEenThe interface language. Options: en (English), de (German).
MAX_ACTIVE_LOBBIES5Limits concurrent game sessions to save resources.
LOBBY_TIMEOUT_MINUTES5Automatically deletes empty/inactive lobbies after X minutes to keep the DB clean.
POINTS_PER_QUESTION100Score awarded for a correct answer.
DEFAULT_QUESTION_DURATION20Default timer (in seconds) for new questions. Can be overridden per question in the admin panel.

4. Database (MariaDB)​

TriviaFlow uses MariaDB as its primary data store. The default values in .env.example work out-of-the-box with the provided docker-compose.yml.

  • DB_HOST: Leave as db (This is the internal Docker service name).
  • DB_PORT: Leave as 3306.
  • DB_NAME: triviaflow
  • DB_USER: triviaflow
  • DB_PASSWORD: Change this! Choose a strong password.
  • DB_ROOT_PASSWORD: Change this! The root password for database administration.
Database Hostname

Inside the Docker network, services address each other by their container names. That is why DB_HOST is set to db and REDIS_HOST is set to redis. Do not use "localhost" here, as "localhost" refers to the container itself, not the host machine.

5. Infrastructure​

These settings ensure the WebSocket layer works correctly within Docker.

  • REDIS_HOST: Leave as redis.
  • UseDocker: Leave as True.
    • Technical Detail: This flag tells Django to use the Redis Channel Layer (production) instead of the In-Memory Channel Layer (local development).

Configuration Checklist​

Before starting the server, verify your .env file:

  • DEBUG=False
  • SECRET_KEY is a long random string.
  • ALLOWED_HOSTS contains your domain (e.g., quiz.example.com).
  • CSRF_TRUSTED_ORIGINS contains your full URL (e.g., https://quiz.example.com).
  • Database passwords are changed and secure.