Hub/Gateway (und Plain UI Frontend)

Plain UI

Es handelt sich um eine Darstellung der Konferenz-Inhalte als simples Frontend ohne viel Schnick-Schnack.

• Prodinstanz: https://events.ccc.de/congress/2023/hub/
• Testinstanz: https://staging.hub.c3events.de/

Datenmodell

als PDF: Grobes Datenmodell und automatisch exportiertes ER-Diagramm (kann Spuren von Unübersichtlichkeit enthalten)

REST API

Am Beispiel der Konferenz-Slug "camp23", grundsätzlich sind alle hier aufgeführten Endpoints per GET abrufbar (Restriktionen bei nicht-öffentlichen Events, etc. sind möglich). Manche Endpunkte sind zusätzlich "schreibbar" und können zur Anlage bzw. Bearbeitung der jeweiligen Daten genutzt werden.

Testinstanz: https://hub.test.c3voc.de/api/ / https://staging.hub.c3events.de/api/
Prodinstanz: https://api.events.ccc.de/congress/2023/

Per POST werden neue Einträge angelegt, per PUT bestehende verändert. Details zu den einzelnen Endpunkten folgen in Kürze™.

Navbar

Bietet eine von allen Seiten gemeinsam einbindbare Navigationsleiste im jeweiligen Congress-Design. (not implemented yet)

Lokale Entwicklung

Dieses Projekt basiert auf Python 3.11+ und Django 4.2+.

Initiale Einrichtung

Lokales Docker development image

Das Docker development image vereinfacht die initiale Einrichtung und sperrt alle Abhängigkeiten und Prozesse in einen Entwicklungscontainer. Alternativ ist auch eine manuelle Einrichtung möglich.

1. Docker und Docker Compose installieren. Optional kann auch die devcontainer cli verwendet werden. Unter Windows getestet mit WSL 2.
2. Klonen dieses Repositories an beliebigen Ort.
3. Image erzeugen: docker compose build oder devcontainer build.
   • Für schnellere Builds kann buildkit verwendet werden:

     docker buildx bake

   • Die Standardpasswöter für PostgreSQL und Hub Benutzer sind in der docker-compose.yml Datei festgelegt und können per Umgebungsvariable angepasst werden.
4. Container erzeugen: docker compose up -d hub oder devcontainer up.
   • Beim Start mittels docker compose wird kein HUB Admin Benutzer angelegt um ein ungewolltes anlegen von diesen Benutzern in der Produktivumgebung vorzubeugen. Falls der admin Benutzer angelegt werden soll muss die Umgebungsvariable DJANGO_CREATE_ADMIN_PASSWORD für den Container gesetzt werden.
   • Bei Verwendung von devcontainers wird der admin Benutzer automatisch mit dem Password hubhubhub angelegt.
5. Optional: Import von Demo-Daten: docker compose exec -it hub python manage.py loaddata ./core/fixtures/rc3_2021.json

Docker Einstellungen in der Entwicklungsumgebung

Um die Einstellungen der Instanz anzupassen kann eine dev.env Datei im Root-Verzeichnis angelegt werden.

Diese kann duch das anlegen einer localen compose Datei mit dem folgenden Inhalt geladen werden:

version: "3.8"

services:
  hub:
    env_file:
      - dev.env

Diese kann durch das setzen der Umgebungsvariable COMPOSE_FILE=docker-compose.yml:docker-compose.local.yml automatisch beim allen docker compose Kommandos berücksichtigt werden. Um eine andere Demo Datei zu laden kann die Umgebungsvariable DJANGO_LOAD_FIXTURE gesetzt werden (Aufgrund von Compose Prioritäten ist es nicht möglich das über die dev.env Datei zu setzen).

Lokale Einrichtung

1. Installiere, falls noch nicht geschehen, Python in Version 3.11 (oder höher) und habe eine PostgreSQL-Datenbank zur Hand (geht potenziell auch mit sqlite aber das ist nicht getestet). Außerdem wird unter Umständen GNU gettext benötigt, wenn man Übersetzungen kompilieren will. Alternativ kann auch das docker dev image verwendet werden.
   • Linux: Pakete python3, postgresql und gettext
   • Mac: brew install python3 postgresql gettext bzw. https://postgresapp.com/
   • Windows: latest stable Python 3 release und PostgreSQL Installer und gettext binaries
2. Klone dieses Repository an beliebigen Ort.
3. Gehe via Terminal/Konsole in das Unterverzeichnis src.
4. Falls du kein direnv benutzt:
   1. Richte ein venv ein: python3 -m venv venv
   2. Aktiviere das venv: . venv/bin/activate
5. Installiere die benötigten Pakete: python3 -m pip install -r requirements.txt "psycopg[binary]"
6. (falls nicht bereits vorhanden) lege einen PostgreSQL-User an (createuser -P hub_app) sowie eine Datenbank (createdb -O hub_app hub) - unter Linux ggf. via sudo -u postgres
7. Lege eine Datei local_settings.py in src/hub/ an (Dokumentation zur Datenbankkonfiguration in der Django-Dokumentation):

DEBUG = True
ALLOWED_HOSTS = ['127.0.0.1', 'localhost']
SESSION_COOKIE_SECURE = False
SESSION_COOKIE_DOMAIN = None
IS_API = True
IS_FRONTEND = True
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'  # "send" emails as console output
SELECTED_CONFERENCE_ID = '40ba6cda-1970-409f-81ef-efb87ef09d95' # change this to the id of your conference you want to display in frontend (matches the one from rc3_2020.json)
METRICS_SERVER_IPS = ['127.0.0.1']   # Change this if you want to test the Prometheus / Grafana metrics endpoint (http://127.0.0.1:8000/metrics/)

DATABASES = {
    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.postgis',
        'NAME': 'hub',
        'USER': 'hub_app',
        'PASSWORD': '<kennwort-aus-dem-createuser-aufruf>',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

8. Lege die Datenbanktabellen an: ./manage.py migrate
9. Richte einen Admin-Nutzer (für die Anwendung) ein: ./manage.py createsuperuser
10. optional: Import von Demo-Daten: ./manage.py loaddata ./core/fixtures/rc3_2021.json
11. optional: Für deinen Adminuser via Admin-Seite einen ConferenceMember anlegen um den User für das Frontend freizuschalten

Nutzung

1. Gehe in das src Verzeichnis, nicht-direnv-Nutzer müssen das venv manuell aktivieren (siehe oben)
2. Wende ggf. vorhandene DB-Migrations an (wenn du gerade aus dem Git geupdatet hast): ./manage.py migrate
3. Stelle sicher dass alle Translations aktuell sind: ./manage.py compilemessages
4. Lasse alle staticfiles einsammeln: ./manage.py collectstatic
5. Starte den Dev-Server: ./manage.py runserver
6. Besuche die lokale Instanz: Admin-Seite, API und plainui-Frontend

PlainUi Structure

• jinja2/plainui
  • components
  • tbd.
• styles
  • components: components styles, die in hub.scss eingebunden werden
  • utils: settings, die selbst keinen output generieren (z.B. Variablen, Mixins), damit sie in unterschiedlichen files verwendet werden können
  • hub.scss: Hauptdatei, welche anschließend in CSS konvertiert wird
• static/plainui
  • img: statische Bilder
  • fonts: importierte Schriften
  • das generierte CSS

CSS Kompilieren (PlainUi)

1. Gehe in das Verzeichnis src/plainui/
2. Führe yarn aus, um die node_modules zu generieren
3. Führe yarn build aus um das CSS zu kompilieren
4. Um das CSS beim Entwickeln automatisch neu zu kompilieren gibt es yarn watch

Components

Wiederverwendbare Elemente können als Komponenten integriert werden. Dafür gibt es jeweils 2 "components"-Ordner. Die HTML-Komponenten befinden sich in plainui/jinja2/plainui/components. Sollten zusätzliche Styles benötigt werden, können diese in plainui/styles/components hinzugefügt werden, welche anschließend in rc3.scss integriert werden. Wichtig ist, ein eigenes File pro Komponente anzulegen. Für Jinja eignen sich dazu Macros oder Includes. Zusätzlich ist die Komponente in der Übersicht hinzuzufügen - lokal erreichbar unter http://localhost:8000/component_gallery.

Debugging DJANGO

Context im HTML-File ausgeben:

<pre>{% debug %}</pre>

oder:

<pre>
        {{ show_vars(myContextElement) }}
    </pre
>

Übersetzungen extrahieren & compilieren

• ./manage.py makemessages
• Die Übersetzungsdateien in <app>/locale/<sprache>/LC_MESSAGES/django.po wurden um alle neuen Übersetzungsstrings erweitert. Bearbeiten und jeweils bei msgstr die Übersetzungen einfügen!
• ./manage.py compilemessages
• Zum Ausprobieren müsst ihr django neu starten um die neuen Übersetzungsdateien zu laden

Übersetzungen definineren

• in Python: gettext wie üblich in Django, siehe Doku
• in jinja2-Templates via _, bspw. {{ _("Settings") }} oder mit Platzhalter {{ _("Hello, %(username)s", username=user.display_name) }}

Static Files einsammeln lassen

• ./manage.py collectstatic
• ohne dies brechen u.a. Unittests mit Fehlern wie "Missing staticfiles manifest entry" ab

Tests

Es gibt Django (Unit-)Tests für die einzelnen Apps. Diese finden sich jeweils im tests Ordner der App. Außerdem gibt es im repository root unter tests auch noch einfache Integrationstests.

Django Tests ausführen

Um die Tests ausführen zu können muss der Datenbanknutzer das Recht haben neue Datenbaken anzulegen. Dafür mit psql postgres die Datenbankkonsole starten. Dort ALTER USER hub_app CREATEDB; ausführen (ggf. hub_app durch den gewählten Nutzernamen ersetzen). Am Ende mit Strg-D Konsole wieder schließen.

Manche Tests benötigen, die kompilierten Übersetzungen. Deshalb ist es sinvoll vor der Testausführung ./manage.py compilemessages auszuführen.

Um alle Tests auszuführen in das src Verzeichnis wechseln und ./manage.py test ausführen.
Um nur die Tests einer App auszführen stattdessen ./manage.py test <app>.tests ausführen.
Hilfreiche Argumente sind -v 2 um die ausgeführten Tests anzuzeigen und --failfast um nach dem ersten Fehler abzubrechen.
Für weitere Infos zu dem Befehl ist https://docs.djangoproject.com/en/3.1/ref/django-admin/#django-admin-test hilfreich.

Um eine Ausführungsgebung zu verwenden die ähnlicher zu der der CI ist, kann DJANGO_SETTINGS_MODULE=hub.settings.ci ./manage.py test verwendet werden.

Django Tests in Docker ausführen

Um alle Tests auszuführen kann das test profil verwendet werden. Hierzu einfach docker compose --profile test run hubtest ausführen. Die oben beschriebenen Funktionen können einfach hinten angehängt werden (z.B. docker compose --profile test run hubtest -v 2 --failtest).

Pre-commit hooks

Um zu verhindern, dass Code eingecheckt wird können pre-commit hooks mittels "pre-commit install" hinzugefügt werden. Ab dann wird vor jedem commit ein Teil der checks (vor allem Format Tests) durchgeführt.

Debug Zugriff

Um auf einen Docker Container mit dem root bentuzer zuzugreifen kann das folgende Kommando verwendet werden: docker compose exec -u root hub /bin/bash

Häufige Fehler

$ ./manage.py migrate
<snip>
AttributeError: 'DatabaseOperations' object has no attribute 'geo_db_type'

Dieser Fehler tritt auf, wenn man PostGIS-Felder mit dem normalen Django-Postgres-Backend anlegen möchte. Statt dessen als Engine django.contrib.gis.db.backends.postgis verwenden.

Docker Image Abhängigkeiten

Das Bild zeigt die aktuellen Docker Image Abhängigkeiten aus dem Multistage Dockerfile

Recreate image

docker run \
  --rm \
  --user "$(id -u):$(id -g)" \
  --workdir /workspace \
  --volume "$(pwd)":/workspace \
  ghcr.io/patrickhoefler/dockerfilegraph:alpine -o png

Ignore Format Commits

Um den Reformat in lokalen git blame Kommandos zu ignorieren kann man die .git-blame-ignore-revs Datei verwenden. Für dauerhafte Konfiguration bitte das folgende Kommando verwenden:

git config blame.ignoreRevsFile .git-blame-ignore-revs