Local Development

Requirements

The following description of the development setup is mainly applicable for Mac / Linux platforms. Should you use Windows for development, we highly recommend using WSL / WSL2 (Windows Subsystem for Linux) to be able to run the same commands.

• Clone the https://github.com/uzh-bf/klicker-uzh repository and checkout the development branch (currently v3).
• Install Doppler (https://docs.doppler.com/docs/install-cli) and create a new project/dev environment.
  • Once the Doppler environment has been set up, use doppler login to connect your local environment.
  • Run doppler setup and to link the repository folder to your matching Doppler project
• Preferably: Install Volta (https://volta.sh/) for automated Node.js and NPM/PNPM package management
  • Linux/Mac/WSL: When using Volta, add VOLTA_FEATURE_PNPM=1 to your .bashrc or .zshrc
  • Alternatively: Manually install Node.js 20 (https://nodejs.org/en/download) and PNPM 8 (https://pnpm.io/installation)
• Install either Docker Desktop (https://docs.docker.com/get-docker/) or Rancher Desktop (https://github.com/rancher-sandbox/rancher-desktop)
  • Docker is preferable if licensing allows (e.g., for student projects)
  • Rancher Desktop works well as an alternative to Docker (on MacOS: brew install --cask rancher, brew install docker docker-compose docker-credential-helper). If prompted, disable Kubernetes (not used in local development) and enable docker.
  • When using Rancher Desktop on a Windows machine, install it directly on Windows and expose it through the corresponding setting to your WSL.
• For Live Quiz Execution only: Install Azure Function Tools (https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local)
• For Live Quiz Execution only: Install Azurite in, e.g., VS Code (https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite?tabs=visual-studio)
• For Live Quiz Execution only: Create an Azure Service Bus Queue (https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions)

Initial Setup

Windows - Subsystem for Linux

• Install the Windows Subsystem for Linux:
  • Open PowerShell with administrative permissions
  • Run wsl --install to install WSL2
  • Reboot the system and, if applicable, follow the steps to finalize WSL installation (username/password, etc.)
• Open WSL using Terminal and by typing wsl
• Add some missing dependencies to work with Docker inside WSL using sudo apt install libsecret-1-0 gnome-keyring
• In a new terminal outside of WSL, get the local IP address of your WSL environment using wsl -d Ubuntu hostname -I. This will return a list of IP addresses, of which you should need the first.

Development Domains

The KlickerUZH runs on domains in local development (using localhost or IPs will cause many random issues with, e.g., Edu-ID log-in or cookie authentication). These domains need to be added to /etc/hosts such that they refer to the local machine and are not resolved through the internet.

• Linux/Mac: Add local domain entries to /etc/hosts

127.0.0.1	api.klicker.com
127.0.0.1	pwa.klicker.com
127.0.0.1	manage.klicker.com
127.0.0.1	control.klicker.com
127.0.0.1	auth.klicker.com
127.0.0.1	func-responses.klicker.com
127.0.0.1	func-response-processor.klicker.com

• Windows with WSL: Add the entries to C:\Windows\System32\drivers\etc\hosts using an editor with administrative access (e.g., open Notepad with right-click, "Run as administrator", then open the hosts file, edit, and save.

Environment Variables and Secrets

• In apps/backend-docker: Copy .env.template to .env
• For Live Quiz Execution only: In apps/func-incoming-responses and apps/func-response-processor: Copy local.settings.template to local.settings.json and fill in any missing values
• Add required secrets as listed below to the Doppler environment (Add Secret > Import Secrets)

API_DOMAIN="api.klicker.com"
APP_SECRET="abcd"
AZUREWEBJOBSFEATUREFLAGS="EnableWorkerIndexing"
AZUREWEBJOBSSTORAGE="UseDevelopmentStorage=true"
COOKIE_DOMAIN=".klicker.com"
CRON_TOKEN="abcd"
DATABASE_URL="postgres://klicker:klicker@localhost:5432/klicker"
FUNCTIONS_EXTENSION_VERSION="~4"
FUNCTIONS_WORKER_PROCESS_COUNT="10"
FUNCTIONS_WORKER_RUNTIME="node"
NODE_ENV="development"
REDIS_CACHE_HOST="localhost"
REDIS_CACHE_PORT="6379"
REDIS_HOST="localhost"
REDIS_PORT="6379"
SERVICE_BUS_CONNECTION_STRING="<FILL_IN>"
SERVICE_BUS_QUEUE_NAME="<FILL_IN>"
SHADOW_DATABASE_URL="postgres://klicker:klicker@localhost:5432/shadow"

Running KlickerUZH in Development Mode

• Ensure that Docker Desktop or Rancher Desktop are running and configured correctly (docker ps should not return an error).
• Run the database and other required services with Docker using the ./_run_app_dependencies.sh script for Mac/Linux, and the ./_run_app_dependencies_wsl.sh script for Windows using WSL.
• Install dependencies with PNPM using pnpm install in the root of the repository.
• Prepare the database schema and seed with initial data using pnpm run prisma:setup. Ideally, open a separate terminal in the packages/prisma folder to run this command and continue using this terminal for database-related actions.
• If you are setting up KlickerUZH for the first time, run pnpm run build on the top level to make sure that all packages are available and can be built.
• For development of Azure functions only (e.g., for Live Quiz Execution): Start the Azurite emulator (e.g., in VSCode using the Azurite: Start command, or using the azurite CLI).
• Start the application in development mode using pnpm run dev (will start everything and requires internet access and an Azure Service Bus configuration) or pnpm run dev:offline (will skip Azure functions and thus not require internet access or Azure Service Bus, but the live quiz will not be able to process responses).
• To visualize the database content during development, use pnpm run prisma:studio in the packages/prisma folder (available at localhost:5555) or access the database using a tool like DataGrip and using the connection string postgres://klicker:klicker@localhost:5432/klicker.

The applications should then be accessible on the configured local domains (e.g., manage.klicker.com - see list above). If any issues occur, ensure the relevant preparations as described have been made. You can also check the Traefik proxy web interface for any errors on localhost:8080, or check whether an IP-based access returns any results (e.g., to http://127.0.0.1:3002/).

The seeded development users are:

• manage.klicker.com -> use delegated login with username: lecturer, password: abcd
• pwa.klicker.com -> username: testuser1, password: abcd

Troubleshooting

• WSL: If the applications are not reachable due to a gateway error, make sure that the IP address used in util/traefik/rules_wsl.yaml corresponds to the internal IP address of your WSL environment. If you are not sure, check using a terminal with the command wsl -d Ubuntu hostname -I. The email used in Traefik rules should correspond to the first IP listed in the output of the command.