Prerequisites
Before diving into the deployment process, let's make sure you have everything needed to run TriviaFlow successfully. This guide covers the infrastructure, tools, and configurations required for a smooth installation. Don't worry—TriviaFlow is designed to be flexible and runs on a variety of hardware configurations!
🖥️ Server / Hosting
TriviaFlow is fully containerized using Docker, which means it can run on virtually any Linux-based system. You have several options depending on your use case, budget, and technical comfort level.
Server Options
Which option is right for you?
| Type | Best For | Pros | Cons |
|---|---|---|---|
| ☁️ VPS (Cloud) | Production, public events | Professional, scalable, automatic SSL | Monthly cost (~$5-10) |
| 🖥️ Dedicated Server | Large-scale deployments | Full control, maximum performance | Higher cost, requires management |
| 🍓 Raspberry Pi | Home/local events, testing | Low cost, educational | Limited resources, local network only |
| 💻 Home Server | Private events, development | Full control, no recurring costs | Requires port forwarding, dynamic IP challenges |
A VPS (Virtual Private Server) from providers like DigitalOcean, Hetzner, or Linode offers the best balance of simplicity, reliability, and cost. Plans starting at $5/month are sufficient for most use cases.
You can absolutely run TriviaFlow on a Raspberry Pi 4 (4GB+ RAM recommended) or a home server for local events! Just be aware that you'll need to configure port forwarding on your router and handle SSL certificates differently if you want external access. For local-only use (like a classroom or office), this works great!
Recommended Operating Systems
TriviaFlow has been tested and optimized for the following Linux distributions. While Docker ensures broad compatibility, these OSes provide the most stable experience:
| OS | Version | Status |
|---|---|---|
| Debian | 12 (Bookworm) / 13 (Trixie) | ✅ Recommended |
| Ubuntu | 22.04 LTS / 24.04 LTS | ✅ Recommended |
| Raspberry Pi OS | Latest (64-bit) | ✅ Supported |
| Fedora | Latest | ⚠️ Works |
| Other Linux | Docker-compatible | ⚠️ Experimental |
While Docker runs on Windows and macOS, TriviaFlow is designed for Linux production environments. Use WSL2 (Windows) or Docker Desktop (macOS) for local development only, not production deployment.
Hardware Requirements
Understanding the requirements:
TriviaFlow consists of several services (Django app, MariaDB database, Redis cache, Caddy web server) running in Docker containers. The resource requirements scale with your expected player count and quiz complexity.
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCore / ARM64 | 2 vCores |
| RAM | 1 GB | 2-4 GB |
| Storage | 10 GB SSD | 20 GB+ SSD/NVMe |
| Network | 10 Mbps | 50+ Mbps |
Player capacity estimates:
- 1 vCore, 1GB RAM: ~20-30 concurrent players
- 2 vCores, 2GB RAM: ~50-100 concurrent players
- 4 vCores, 4GB RAM: 100+ concurrent players
A Raspberry Pi 4 with 4GB RAM can comfortably handle 20-30 players for local events. The 8GB model can push to 40-50 players with proper optimization.
Required Ports
Your server must have the following ports open and accessible:
| Port | Protocol | Purpose |
|---|---|---|
| 80 | HTTP | Web traffic (auto-redirects to HTTPS) |
| 443 | HTTPS | Secure web traffic (game interface) |
| 22 | SSH | Server management access |
Security Note: Caddy automatically handles SSL/TLS certificates and redirects HTTP to HTTPS, so you don't need to worry about certificate management!
🌐 Domain Name
Why you need a domain:
TriviaFlow requires a public domain name to enable automatic HTTPS encryption via Let's Encrypt. This ensures secure connections for your players and provides a professional, easy-to-remember URL.
What You Need
- A registered domain from any registrar (Namecheap, Cloudflare, GoDaddy, etc.)
- DNS A Record pointing to your server's public IP address
DNS Configuration
Point your domain to your server by creating an A record in your DNS settings:
Type: A
Name: quiz (or @, or your subdomain)
Content: YOUR_SERVER_IP_ADDRESS
TTL: Auto (or 3600)
Example configurations:
| Use Case | Domain | DNS Record | Points To |
|---|---|---|---|
| Main game | quiz.your-domain.com | quiz → 203.0.113.42 | Your server IP |
| Database admin | db.your-domain.com | db → 203.0.113.42 | Same server IP |
After creating the DNS record, it may take 5-60 minutes to propagate globally. You can check the status using Google Dig.
If you're running TriviaFlow on a local network (e.g., Raspberry Pi at home), you can skip the domain requirement and access it via IP address (e.g., http://192.168.1.100). However, you won't have automatic SSL and will need to use HTTP instead of HTTPS.
🛠️ Required Software
Before deploying TriviaFlow, install the following tools on your server. These are the foundation for fetching the code and running the containerized application.
1. Git
Why you need it: Git allows you to clone the TriviaFlow repository from GitHub and receive updates easily.
Installation:
- Debian / Ubuntu
- RedHat / Fedora
- Arch Linux
- Raspberry Pi OS
sudo apt update && sudo apt install git -y
sudo dnf install git -y
sudo pacman -S git
sudo apt update && sudo apt install git -y
Verify installation:
git --version
# Should output: git version 2.x.x
2. Docker & Docker Compose
Why you need it: TriviaFlow runs entirely in Docker containers, which package all dependencies (Python, database, web server) into isolated, reproducible environments. This eliminates "it works on my machine" problems!
Quick Installation (Recommended):
The official Docker convenience script automatically detects your OS and installs Docker + Docker Compose:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
Post-Installation Setup:
Allow your user to run Docker without sudo (optional but recommended):
sudo usermod -aG docker $USER
Log out and back in for the group change to take effect.
📦 Manual Installation (Advanced)
If you prefer to install via your package manager or need a specific version:
Debian/Ubuntu:
# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
# Add the repository to Apt sources:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
$(. /etc/os-release; echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Raspberry Pi OS:
# Same as Debian/Ubuntu above, or use the convenience script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
Verify installation:
docker --version
# Should output: Docker version 24.x.x
docker compose version
# Should output: Docker Compose version v2.x.x
✅ Checklist
Before proceeding to deployment, verify you have:
- Access to a Linux server (VPS, dedicated server, Raspberry Pi, or home server)
- Operating system is Debian, Ubuntu, or another Docker-compatible Linux distro
- Server specs meet minimum requirements (1 vCore, 1GB RAM, 10GB storage)
- Ports 80 & 443 are open and accessible from the internet (if deploying publicly)
- Domain name registered and DNS A record configured (if deploying publicly)
- Git installed and working (
git --version) - Docker & Docker Compose installed and working (
docker --version) - SSH access to your server with root or sudo privileges
Once you've checked all the boxes above, you're ready to proceed to the Deployment Guide and get TriviaFlow up and running!
If you're unsure about any of these prerequisites or need help choosing a hosting option, check out our Troubleshooting Guide, reach out to support@triviaflow.de, or join our Discord community.