Self-Hosting

Since ClassQuiz is open-source, it can also be self-hosted.

Warning

Although some versions are already released, I would recommend to run the latest commit (where checks pass) from the master-branch.

Requirements

Software

Docker (Compose)
Git
A Redis-Server

3rd-Parties

Optional

Installation

First, clone the repo:

git clone https://github.com/mawoka-myblock/classquiz && cd ClassQuiz

Now, you'll configure your frontend. You'll have to change the following in frontend/Dockerfile:

VITE_MAPBOX_ACCESS_TOKEN: A Mapbox-token which is optional.
VITE_HCAPTCHA: The hCaptcha-Siteky for captchas
VITE_CAPTCHA_ENABLED: Set it to true, if the captcha should be available
VITE_SENTRY: A Sentry-DSN for Sentry (optional)
VITE_GOOGLE_AUTH_ENABLED: Set it to true, if Google-Auth is set up. Otherwise, leave it unset.
VITE_GITHUB_AUTH_ENABLED: Set it to true, if GitHub-Auth is set up. Otherwise, leave it unset.

Configuration

Storage Provider

You'll have to set up a storage provider for some pictures (these getting imported from Kahoot!). For now, you can use Minio (S3) or the local filesystem. Please not that I'd recommend Minio for larger instances, since it can be scaled and the media doesn't have to streamed through the (comparatively) slow ClassQuiz server. Now, that you've decided on a storage backend, you can set the STORAGE_BACKEND-environment-variable to either s3 or local. If you ask yourself what happened with deta, I've decided to remove it, since the went all-in with their spaces and I think that hardly anyone used it anyway.

If you chose Minio (S3)...

...you'll also have to set the S3_ACCESS_KEY, S3_SECRET_KEY and the S3_BASE_URL. The S3_BUCKET_NAME can also be set, but defaults to classquiz.

If you chose the local filesystem...

...you'll have to set the STORAGE_PATH environment variable. The path must be absolute (so start with a /).

Before you can start your stack, you have to set some environment-variables in your docker-compose.yml.

GitHub/Google/OpenID-Auth

This step is purely optional, but it will enable users to log in using their Google/GitHub-accounts.

Google

First, go to console.cloud.google.com/apis/dashboard and create a new project and select it. Then, go to the "OAuth consent screen" and set it up. Next, go to the "Credentials"-tab and click on "Create Credentials" and create a new "OAuth Client ID". This ID should be from the application-type "Web application". Afterwards, add a new "Authorised JavaScript origin", which is just the base-domain (with https) of your ClassQuiz-installation. Then, add a new "Authorised redirect URI". This URI will have the following scheme:

https://[BASE_URL]/api/v1/users/oauth/google/auth

You're done! Not the client-secret and the client-id down, you'll need it later.

GitHub

First, go to github.com/settings/developers and create a "new OAuth App". The "Authorization callback URL" has the following schema:

https://[BASE_URL]/api/v1/users/oauth/github/auth

That's it. Click on "Register application" and generate a new client secret and save it for later, together with your client-id.

Custom OpenID auth

A login using a custom OpenID provider is also possible. For that, adjust the settings in the docker-compose.yml and configure the following scopes: "openid email profile". The follwoing redirect-url should be used:

https://[BASE_URL]/api/v1/users/oauth/custom/auth

You'll also need to tell the frontend by editing thefrontend/Dockerfile. Add the following line at the top, where all the other ENV's are as well:

ENV VITE_CUSTOM_OAUTH_NAME=[SOME_DISPLAY_NAME_FOR_THE_PROVIDER]

Docker-Compose File

Please go through thedocker-compose.yml thoroughly and fill out all the details, which should be self-explanatory.

Run the following command to generate and set the secret up automatically

sed -i "s/TOP_SECRET/$(openssl rand -hex 32)/g" docker-compose.yml

Now build and deploy:

docker compose build && docker compose up -d

ClassQuiz needs HTTPS/SSL to work properly!

Enjoy! ❤️