• Clone the repo:
    git clone
  • Install the dependencies
    • Python:
      pipenv install -d
    • JS:
      cd frontend && pnpm i
  • Start the other services

    There's a small helper-script: It's called and does more than you think. - Docs

    You can run this script with bash. It helps you managing docker-containers you need to run ClassQuiz. The standard workflow is the following:

    1. Prepare all the containers:
      ./ +
    2. Start the Python-server:
      pipenv run uvicorn classquiz:app --reload --proxy-headers
    3. Start the background worker:
      pipenv run arq classquiz.worker.WorkerSettings
    4. Start the frontend-dev-server:
      cd frontend && API_URL=http://localhost:8080 pnpm dev
    5. Start Caddy:
      caddy run
    6. Start the background-worker:
      arq classquiz.worker.WorkerSettings

    If you're done developing: ./ -

    If you want to run all the tests: ./ a

  • Add the following line to your /etc/hosts-file, so you can visit ClassQuiz via (Required for the Captcha and Mapbox)
    Now you can visit ClassQuiz at
  • Set your config up in your .env-file. What you have to set up can you see in the classquiz/ The things you have to set are the following:
    • hcaptcha_key
    • mail_address
    • mail_password
    • mail_username
    • mail_server
    • mail_port
    • secret_key

    You'll have to set up the storage. For developing, I'd recommend using the local file system. to do that, set the following 2 environment-varialbes:

    • STORAGE_PATH=/tmp/storage
  • Start the server
    • Backend:
      pipenv run uvicorn classquiz:app --reload --proxy-headers
    • Frontend:
      cd frontend && API_URL=http://localhost:8080 pnpm dev


We're using Pre-Commit for our pre-commit hooks. Install it by running the following command:

pipenv run pre-commit install

BEFORE you submit a Pull-Request

Please use Gitmoji for your commits.


Please format and lint your code with

pnpm run format && pnpm run lint


Run the tests: ./ a

Made with ❤️ by Mawoka and with the help of others.
If you find this useful, please consider donating. More details here.

Consider following Mastodon @[email protected] for updates!