Web-based quiz platform built with Flask. Create, run, and analyze quizzes with a visual editor and CSV/Excel export.
QuizSystem is a simple but capable quiz application. It includes an admin interface, a visual quiz editor, multiple question types, results storage in SQLite, and export to Excel.
Key features:
- Visual quiz editor (drag-and-drop, image support)
- Single/multiple-choice and text questions
- Results export to Excel
- Docker-Compose deployment with persistent volumes
These steps run the app on your machine using Docker and Docker Compose v2.
- Docker Engine and Docker Compose v2 installed
- Ports 8000 available on your host (or adjust mapping below)
git clone https://github.com/PelerYuan/QuizSystem
cd QuizSystemThe admin password lives in configure.json and is mounted read-only into the container.
Default content:
{
"admin password": "123456"
}If you change it here before starting, it will be used immediately by the container.
docker compose builddocker compose up -dWhat this does:
- Builds the image defined in
Dockerfile - Starts the
quizsystemservice fromdocker-compose.yml - Maps container port 8000 to host port 8000
- Mounts volumes so your data and media persist on the host
curl -fsS http://localhost:8000/health && echo "OK"Open the app in your browser:
- User interface: http://localhost:8000
- Admin login: http://localhost:8000/admin_login (password from
configure.json)
- View logs:
docker compose logs -f - Stop:
docker compose down - Restart after edits:
docker compose up -d --build
By default, the compose file uses named Docker volumes for writable data. Inside the container these paths are used:
/app/data(named volumedb) — contains the SQLite database at/app/data/data.sqlite/app/img(named volumeimg) — uploaded images/app/quiz(named volumequiz) — quiz JSON files/app/result(named volumeresult) — exported results/app/tmp(named volumetmp) — temporary files./configure.json -> /app/configure.json:ro— admin password (bind-mounted read-only from the repo)
Notes:
- On first start, the container auto-initializes the database schema (idempotent). No manual step is needed.
- To change the host port, edit
docker-compose.ymland modifyports: - "8000:8000"(format isHOST:CONTAINER).
- Container exposes
GET /healthwhich returns JSON and is used by the Composehealthcheck. - The Dockerfile runs
flask runon port 8000.
Because writable data lives in named volumes, you can back them up with a temporary helper container:
- Backup the DB volume to a local folder:
mkdir -p backup/db docker run --rm \ -v quizsystem_db:/from \ -v $(pwd)/backup/db:/to \ busybox sh -c "cp -a /from/. /to/"
- Similarly backup other volumes (
quizsystem_img,quizsystem_quiz,quizsystem_result,quizsystem_tmp) if desired by replacing the volume name after-v.
To restore, reverse the copy (from your backup folder into the corresponding volume) using the same pattern.
- Clone and prepare folders
git clone https://github.com/PelerYuan/QuizSystem
cd QuizSystem
mkdir -p img quiz result tmp- Create a virtual environment and install deps
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt- Initialize database (first run only)
python -c "from app import db; db.create_all()"- Run the app
python app.pyOpen http://localhost:5000 by default (Flask dev server). For production, prefer Docker Compose above.
- Login page:
/admin_login - Password source:
configure.json("admin password"key)
Exports are saved to the result/ folder as Excel files (OpenPyXL).
- Port already in use: change the host port in
docker-compose.yml(ports:section) and restart. - Health check failing: run
docker compose logs -fto see startup logs. The container automatically initializes the database; if it still fails, share the logs.
PRs are welcome! Fork the repo, create a feature branch, and open a pull request.
Licensed under the GNU General Public License v3.0. See LICENSE.md.
Open an issue: https://github.com/PelerYuan/QuizSystem/issues