W.I.S.V. 'Christiaan Huygens' Dienstensysteem v2
This repository has Development Containers configuration files, making it easy to use GitHub Codespaces to develop remotely or Visual Studio Code Dev Containers to develop locally. Simply open this repository using one of these editors and use the 'Run' menu to start the Dienst2 application server.
For Visual Studio Code:
- Run 'Dev Containers: Open Folder in Container' from the Command Palette (Ctrl+Shift+P) to open the repository in a container.
- Wait for the container to install.
- Start the server by running 'Run: Start Debugging' from the menu (F5).
Build and run the development Docker image using Docker Compose: docker-compose up
and go to http://localhost:8000
- Install PostgreSQL (e.g. Postgres.app for macOS, make sure to add it to
$PATH
) - Install PyCharm Professional (free for students)
- Open project
- Create virtual environment
- Install dependencies in virtual environment
- Install dependencies using Yarn (
yarn install
; first install Node.js and Yarn if you haven't already) - Run pre-commit install (
pre-commit install
) - Create PostgreSQL database (
createdb dienst2
;createuser dienst2
) - Edit the
dienst2/local.py
file to set up your database - Initialise database using manage.py (
./manage.py migrate
) - Start server (
./manage.py runserver
) and go to http://localhost:8000
Note: please do not use (a copy of) the production database for local development.
We use django-admin make-messages
for localisation.
The translations are generated in .po
files, such as this django.po file.
Please beware that these files should not be edited by hand, except for the translations themselves.
For an example of translations in a file, please check this file.
If you run your development environment using docker, the generation of the translation files is done using the following command:
docker-compose run django python manage.py makemessages -l nl -i venv --no-location
at the root of the project.
In this case we are generating the Dutch (nl) translation files.
To compile the messages run docker-compose run django python manage.py compilemessages -l nl
The master
branch should be automatically deployed to the CH Kubernetes cluster through GitHub Actions and Flux.
Dienst2 requires a Google Service account to access Group and Member data via the directory API. A Google Serivce Account can be created in the Google Cloud Console. The service account should be a "Domain-wide Delegation" account with the following scopes:
- https://www.googleapis.com/auth/admin.directory.group.readonly
- https://www.googleapis.com/auth/admin.directory.group.member.readonly
The scopes can be defined in Google Admin Console -> Security -> API controls -> Domain-wide delegation.
After creating the service account, a JSON key file should be downloaded and stored in /google-service-account.json
on the server.
It is also required to set the subject of the service account as an environment variable GOOGLE_SERVICE_ACCOUNT_DELEGATED_USER
. Service accounts are used to represent non-human entities, but some APIs require a human user to be impersonated.
I do not know to what value this should be set in production, but for development, every email address of someone from "beheer" should work.
The API is available at /ldb/api/v3/
. Authentication is done using a valid session (for in-browser testing) or a token (send an Authorization: Token <token>
header).
To create an API token:
- Create a new user through the Django admin interface, please prefix username with
api_
- Set password field to
!
in database (e.g. through phpPgAdmin) - Assign new API token to new user in Django admin interface
Testing the IAP in a local environment is not straightforward. 3 headers are required for the IAP. Headers for development can be retrieved from the following page: https://wisvch.ew.r.appspot.com/resource.
x-goog-authenticated-user-email=securetoken.google.com/wisvch:[USERNAME]@ch.tudelft.nl
x-goog-authenticated-user-id=securetoken.google.com/wisvch:[SUB]
x-goog-iap-jwt-assertion=[JWT]
You can set the headers using Postman
or using this Chrome Plugin
The page https://wisvch.ew.r.appspot.com/resource uses GOOGLE_IAP_AUDIENCE=/projects/966138216790/apps/wisvch
audience.