Hub/Gateway (und Plain UI Frontend)

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://staging.hub.c3events.de/api/
Prodinstanz: https://events.ccc.de/camp/2023/hub/api/

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

Plain UI

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

Testinstanz: https://staging.hub.c3events.de/

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 build oder devcontainer build.
   • 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

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
PLAINUI_CONFERENCE = '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 rc3.scss eingebunden werden
  • utils: settings, die selbst keinen output generieren (z.B. Variablen, Mixins), damit sie in unterschiedlichen files verwendet werden können
  • rc3.scss: Hauptdatei, welche anschließend in CSS konvertiert wird.
  • alle Files, die auf der gleichen Ebene wie rc3.scss liegen, werden einmalig in das rc3.scss eingebunden.
• static/plainui
  • img: statische Bilder
  • fonts: importierte Schriften
  • das generierte css - rc3.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).

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.