Skip to main content

Deploy TriviaFlow

This is the basic deployment guide for getting TriviaFlow up and running on your server. This guide will walk you through all essential steps to deploy a functional TriviaFlow instance.

Prerequisites

Before starting, make sure you have completed all steps in the Prerequisites guide, including:

  • A VPS with a supported Linux distribution
  • A domain name pointing to your server
  • Git and Docker installed

1. Clone Repository​

Download the source code to your server:

git clone https://github.com/your-username/triviaflow.git
cd triviaflow

2. Configuration​

Technical Config (.env)​

Copy the example configuration file:

cp .env.example .env
nano .env

Required Changes:

  1. Set DEBUG=False.
  2. Generate a SECRET_KEY.
  3. Set ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS to your domain.
  4. Change DB_PASSWORD and DB_ROOT_PASSWORD.

Caddyfile (Reverse Proxy)​

The Caddyfile at the root of your project controls the web server and automatic HTTPS. You must edit this file and replace the placeholder domain with your actual domain.

Open the file:

nano Caddyfile

Replace the domain:

Find the line with quiz.your-domain.com and replace it with your actual domain (e.g., play.super-quiz.com).

quiz.your-domain.com {
    # Static files and reverse proxy configuration
    ...
}

Optional - Database Admin (phpMyAdmin):

If you want a web interface to manage your database, uncomment the database block:

# db.your-domain.com {
#    reverse_proxy phpmyadmin:80
# }

Remove the # symbols and replace db.your-domain.com with your database subdomain.

Technical Details

For more information about how Caddy works, automatic HTTPS, and troubleshooting, see Caddy Reverse Proxy in the Technical Reference.

Game Config (game_config.ini)​

Copy the game configuration example:

cp game_config.ini.example game_config.ini

This file controls gameplay mechanics like questions timers and scoring. You can leave the defaults for now.

Game Logic

See Game Configuration to customize rules later.

3. Start the Application​

We use Docker Compose to start the Database, Redis, Caddy (Webserver/Proxy), and the Django App.

Standard Start:

docker compose up -d --build

Start with phpMyAdmin: (Only if you configured a DB domain in Caddyfile)

docker compose --profile admin up -d --build

4. Initialize Game Configuration​

After starting the application, you need to initialize the game configuration and presets in the database.

Initialize Game Config​

docker compose exec web python manage.py init_game_config

This command sets up the core game mechanics configuration (scoring, timers, lobby settings, etc.) in the database.

Initialize Presets​

docker compose exec web python manage.py init_presets

This command creates the built-in game mode presets (Competitive, Casual, Educational) that will be available when creating new games.

Learn More

For detailed information about these commands and their options, see Custom Commands.

5. Create Admin User​

To access the Game Master dashboard, you must create a Superuser account.

  1. Execute the command inside the running container: 
    docker compose exec web python manage.py createsuperuser
  2. Follow the interactive prompts:
    • Username: e.g., admin
    • Email: (Optional) e.g., admin@example.com
    • Password: Choose a secure password.

6. Verification​

Verify that all containers are running correctly:

docker compose ps

All services should show status "Up". If any container has exited or shows errors, check the logs:

# Check application logs
docker compose logs web

# Check web server logs
docker compose logs caddy

# Check database logs
docker compose logs db

Open your browser and navigate to:

  • https://quiz.your-domain.com/admin - Log in with your new Superuser account.

Congratulations! Your TriviaFlow server is fully operational.

Need Help?​

If you encounter any issues:

What's Next?​

Now that your TriviaFlow instance is up and running, here are some recommended next steps:

Further Configuration​

Create Your First Quiz​

Run Your First Game​