fchaussin/quizdock repository overview

⁠QuizDock

Open-source, self-hosted live quiz platform.
Real-time multiplayer · projector-ready · your data stays on your servers.

Website⁠ · Live demo⁠ · Self-hosting guide⁠ · Releases⁠

QuizDock is a Kahoot-style live quiz you run yourself. A host presents a quiz, players join from any device with a PIN or QR code (no account), and answers — weighted by speed and correctness — feed a live leaderboard projected on the big screen. Everything runs on your infrastructure as a single Docker image; the questions, the answers and the results never leave your servers.

⁠🎮 Try it online

https://quizdock-standalone.onrender.com⁠ — a public instance in demo mode: enter a name, take the host seat and present one of the sample quizzes; open the join link on your phone to play.

• It sleeps when idle: the first load can take about a minute.
• Shared with strangers: everything is wiped every hour, the host seat lasts 5 minutes at a time (renewable), media uploads are off. Don't put anything you care about in it.

⁠✨ Main features

• ⚡ Live quiz, in real time — players join by 6-digit PIN or QR code from any device, no account; a Socket.IO engine with authoritative server timing keeps everyone in step; each player gets a generated Multiavatar⁠ avatar.
• 🖥️ Made for the big screen — bright, high-contrast projection screens, with separate projection and control windows; manual or automatic pacing.
• 🧩 A real quiz builder — seven question types (single/multi choice, true-false, text, numeric, reorder, poll), image & audio media, Markdown everywhere, content slides between questions, backgrounds, answer explanations at the reveal.
• 🏆 Scoring that rewards speed — time-weighted points, streak bonuses, leaderboard between questions, final podium; per-question rules (closest answer wins, partial credit, typo-tolerant text, double or fixed points).
• 🏠 Self-hosted and private — one Docker image (amd64 / arm64), no SaaS, no tracking, no ads; interface in English, French, Spanish, Simplified and Traditional Chinese; rebrand name, logo and CSS without a rebuild.

⁠🔑 Two ways to run it

Same image, one switch: AUTH_MODE decides who can host.

Players never sign in, in either mode. Details: authentication⁠.

⁠🚀 Quick start (self-host)

QuizDock ships as one image — fchaussin/quizdock⁠ on Docker Hub. NestJS serves the API, the WebSocket and the SPA; PostgreSQL and Redis run alongside, and a one-shot migrate service applies migrations.

⁠One container — first try, Docker Desktop

App and database in a single image, nothing else to install:

docker run -p 18080:3000 -v quizdock:/data fchaussin/quizdock:standalone
# open http://localhost:18080

Data persists in the quizdock volume. A deployment shortcut, not a different product: same AUTH_MODE switch as below. For production, prefer a dedicated database.

⁠The quizdock script — recommended

Guided setup, then start, backup, upgrade and admin commands; Docker only:

curl -fsSLO https://raw.githubusercontent.com/quizdock/quiz-dock/main/quizdock && chmod +x quizdock
./quizdock init      # name, language, port, auth mode → .env + docker-compose.prod.yml
./quizdock up        # open http://localhost:18080
./quizdock doctor    # config & connectivity check; later: backup, upgrade <tag>, seat:release…

Every command: docs/self-hosting/cli.md⁠.

⁠Docker Compose by hand

curl -O https://raw.githubusercontent.com/quizdock/quiz-dock/main/docker-compose.prod.yml
docker compose -f docker-compose.prod.yml up -d
# open http://localhost:18080

Pin a version with QUIZDOCK_TAG=0.6.0 docker compose -f docker-compose.prod.yml up -d. From source: git clone https://github.com/quizdock/quiz-dock.git, then the same command with --build.

⁠Upgrading

Migrations run automatically on every start: pull the new tag and up again. Back up PostgreSQL first, and don't roll back an image once its migrations ran — restore the backup instead. With the script: ./quizdock upgrade 0.6.0 (backup → pull → restart → doctor). Full procedure: self-hosting → Upgrading⁠.

⁠⚙️ Configuration

Copy .env.example to .env and adjust. The settings you are most likely to touch:

Rebrand without rebuilding: set APP_NAME / APP_LANG and drop a logo.<svg|avif|webp|png|jpg|jpeg|gif>

• override.css into the mounted branding/ folder (or point APP_LOGO_URL at a logo hosted elsewhere).

📖 Self-hosting guide — every variable, white-labeling and OIDC setup: docs/self-hosting/⁠.

⁠📸 Screenshots

Quiz builder — 7 question types, slides, backgrounds, scoring rules	Host console — lobby: PIN, QR code, invitation address, players
Join — PIN or QR code, nickname & avatar, no account	Projection — live question on the big screen
Player — colour tiles to tap, then own result	Reveal — distribution, explanation, live leaderboard

More — my quizzes, content slides, the console during a question and at the reveal, the podium, the player's ordering and feedback screens: full gallery⁠.

⁠📋 More features

⁠🧱 Tech stack

Backend NestJS + Socket.IO · Prisma 7 / PostgreSQL · Redis (live state) · Frontend React + Vite + shadcn/ui + TanStack · i18next · Packaging single distroless image · Docker Compose. Front/back are kept in sync via an auto-generated OpenAPI client (Orval) and a shared TypeScript WebSocket contract.

⁠🛠️ Development

Dev runs backend (NestJS, hot-reload) and frontend (Vite) as separate services:

pnpm install
docker compose up -d
# Front: http://localhost:15173   ·   API: http://localhost:13000   ·   API docs: http://localhost:13000/api/docs

Design references live in specifications/⁠; ongoing notes and decisions in docs/⁠ (see the ADRs⁠).

⁠🔒 Security

Dependencies and images are scanned on every push, every PR and weekly (Security workflow⁠): pnpm audit gates app CVEs, Trivy scans the filesystem and the published image (results in the Security tab). Point-in-time audits live in docs/security/⁠; report a vulnerability via SECURITY.md⁠.

⁠📄 License

MIT⁠ — free to use, modify and redistribute, including for internal self-hosting, provided the copyright notice is kept.