Standalone, in one command
docker run -p 18080:3000 -v quizdock:/data \ fchaussin/quizdock:standalone
Then open http://localhost:18080.
Deploy QuizDock
Four setups run the same application from the same release. Choose by how hosts sign in and how many services you want to operate.
Which setup for which need?
| Need | Setup | Start with | Hosts | Participants |
|---|---|---|---|---|
| Try it on your machine | Standalone: one container with PostgreSQL and Redis inside | docker run, or ./quizdock init --standalone | One host seat, by name | PIN and nickname |
| An instance you keep, on a trusted network | Compose: application, PostgreSQL, Redis | ./quizdock init, local mode | One host seat, by name | PIN and nickname |
| Your organisation's sign-in | Compose with your identity provider | ./quizdock init, OIDC, your issuer | Accounts with the host role | Accounts, or PIN and nickname when open games are allowed |
| A full evaluation, accounts included | Full: Compose with a bundled Keycloak | ./quizdock init --full | A sample host account, then your own | A sample player account, or PIN and nickname in an open game |
Standalone is for trying QuizDock: everything shares one container, which is not hardened for serious production. Local mode trusts names, so keep it to trusted networks. The full setup adds Keycloak and a second database to maintain.
How do I start?
Compose, with the script
curl -fsSLO https://raw.githubusercontent.com/quizdock/quizdock/main/quizdock chmod +x quizdock ./quizdock init ./quizdock up
Use init --full for Keycloak, init --standalone for one container.
The script is a POSIX shell script that needs Docker with its compose plugin, and curl. init
asks for the name, the language, the port (18080 by default), the authentication mode (not with
--full) and whether administrators may change settings from the browser; it writes
.env with permissions 600 and, for Compose, random passwords, and downloads the Compose files. up starts
the instance and waits until it is healthy.
On first visit, the setup wizard asks for the token written in the logs: ./quizdock logs. Run every
command on the server, in the instance's folder.
Where does the data live?
| Setup | Database | Media and templates | Live games | Configuration |
|---|---|---|---|---|
| Standalone | Volume quizdock, /data/postgres | Same volume, /data/media and /data/store | Redis in memory only | Environment of the container (.env with the script) |
| Compose and full | Volume pgdata (Keycloak's database too, in full) | Volumes mediadata and storedata | Volume redisdata, append-only file | .env in the instance's folder |
Media and the templates folder are not in the database: back them up together, at the same moment. That is what
./quizdock backup does. An optional branding/ folder, mounted for a logo and styles, is not
part of the backup.
Which image tag should I use?
The image is fchaussin/quizdock on Docker Hub, for amd64 and arm64.
| Tag | What it points to |
|---|---|
X.Y.Z | That exact release. |
X.Y | The latest patch release of that minor version. |
latest | The current stable release. |
standalone | The current stable release, as one container with PostgreSQL and Redis. |
standalone-X.Y.Z | That exact release, as one container. |
One release, one version: images are published only from a release tag, and the standalone image of a release is
built on that release's application image. The script runs the tag set in .env (QUIZDOCK_TAG,
latest by default) in every setup: X.Y.Z for Compose, standalone-X.Y.Z for the
standalone image.
How do I upgrade?
./quizdock upgrade X.Y.Z
One line, on the server, in the instance's folder. It backs up, records the tag in .env, pulls the
image, restarts with the database migrations and shows their log, waits for the health check, and runs
doctor. A standalone instance moves to that release's standalone image.
Migrations cannot be rolled back: going back means restoring the database and the media from the same backup. Read
the Upgrading section of the release notes first. A newer release is announced in the administration and by
./quizdock status, with the command to run.
What else before going live?
- Configuration: every variable, its default and its level.
- Networking: the address phones are offered.
- Reverse proxy: one origin, WebSocket, request size, HTTPS.
- OIDC: connect your identity provider.
- Sizing: what the measurements say about the machine.
- Security: the image, the secrets, reporting a vulnerability.
- Status and doctor: checking an instance.
Questions
Which setup should I choose?
To try QuizDock on your machine, standalone. For an instance you keep, Compose through ./quizdock init: in local mode on a trusted network, or with your identity provider. To evaluate accounts and roles without a provider of your own, the full setup with Keycloak.
Does QuizDock run on ARM?
Yes. Every image is published for amd64 and arm64.
Do I need a domain name and HTTPS?
Not on a local network: phones open the machine's local address. For players outside your network, you need a public address, and HTTPS through a reverse proxy, which phones also need to install the app on their home screen. Set APP_PUBLIC_URL to that address.
Which ports does QuizDock use?
The application listens on port 3000 in its container, published on HTTP_PORT, 18080 by default. The full setup also publishes Keycloak, on 18081 by default.
Can I run QuizDock without Docker?
No install without Docker is documented. The standalone image and the Compose setups are the supported paths.
How do I back up an instance?
On the server, in the instance's folder: ./quizdock backup. It dumps the database while the instance runs and copies the media, the templates folder and .env into ./backups/. Schedule it yourself; ./quizdock restore puts a backup back.