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/
Kategorie | Endpunkt | GET | POST | PUT | DEL | Beschreibung |
---|---|---|---|---|---|---|
Allgemein | / |
x | allgemeine API-Übersicht | |||
Allgemein | /conferences |
x | x | Liste aller Konferenzen | ||
Persönlich | /me |
x | x | eigenes Profil / Settings | ||
Persönlich | /friends |
x | x | x | Liste der Buddies | |
Persönlich | /badges |
x | Liste aller Badges/Achievements | |||
Konferenz | /c/camp23/ |
x | Metadaten des Konferenz | |||
Konferenz | /c/camp23/tags |
x | Liste aller Tags auf der Konferenz | |||
Konferenz | /c/camp23/tracks |
x | x | Liste der Tracks | ||
Konferenz | /c/camp23/track/<slug>/ |
x | x | x | Details des Tracks | |
Konferenz | /c/camp23/assemblies |
x | x | Liste der Assemblies | ||
Konferenz | /c/camp23/assembly/<slug>/ |
x | x | x | Details der Assembly | |
Konferenz | /c/camp23/assembly/<slug>/events |
x | x | Liste der Events der Assembly | ||
Konferenz | /c/camp23/assembly/<slug>/rooms |
x | x | Liste der Räume der Assembly | ||
Konferenz | /c/camp23/rooms |
x | Liste aller Räume (über alle Assemblies) | |||
Konferenz | /c/camp23/room/<uuid>/ |
x | Details des Raums | |||
Konferenz | /c/camp23/events |
x | Liste aller Events | |||
Konferenz | /c/camp23/event/<uuid>/ |
x | x | x | Details des Events | |
Konferenz | /c/camp23/event/<uuid>/attachments |
x | x | Anhänge | ||
Konferenz | /c/camp23/event/<uuid>/attachments/<id>/ |
x | x | x | Download der zugehörigen Datei | |
Konferenz | /c/camp23/schedule[.xml|.json] |
x | Liste aller Events als Schedule XML/JSON | |||
Konferenz | /c/camp23/assembly/<slug>/schedule[.xml|.json] |
x | Liste aller Events der Assembly als Schedule XML/JSON | |||
Konferenz | /c/camp23/room/<uuid>/schedule[.xml|.json] |
x | Liste aller Events des Raumes als Schedule XML/JSON |
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.
- Docker und Docker Compose installieren. Optional kann auch die devcontainer cli verwendet werden. Unter Windows getestet mit WSL 2.
- Klonen dieses Repositories an beliebigen Ort.
- Image erzeugen:
docker compose build build
oderdevcontainer 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.
- Die Standardpasswöter für PostgreSQL und Hub Benutzer sind in der
- Container erzeugen:
docker compose up -d hub
oderdevcontainer up
.- Beim Start mittels
docker compose
wird kein HUB Admin Benutzer angelegt um ein ungewolltes anlegen von diesen Benutzern in der Produktivumgebung vorzubeugen. Falls deradmin
Benutzer angelegt werden soll muss die UmgebungsvariableDJANGO_CREATE_ADMIN_PASSWORD
für den Container gesetzt werden. - Bei Verwendung von devcontainers wird der
admin
Benutzer automatisch mit dem Passwordhubhubhub
angelegt.
- Beim Start mittels
- Optional: Import von Demo-Daten:
docker compose exec -it hub python manage.py loaddata ./core/fixtures/rc3_2021.json
Lokale Einrichtung
- 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
undgettext
- Mac:
brew install python3 postgresql gettext
bzw. https://postgresapp.com/ - Windows: latest stable Python 3 release und PostgreSQL Installer und gettext binaries
- Linux: Pakete
- Klone dieses Repository an beliebigen Ort.
- Gehe via Terminal/Konsole in das Unterverzeichnis
src
. - Falls du kein direnv benutzt:
- Richte ein venv ein:
python3 -m venv venv
- Aktiviere das venv:
. venv/bin/activate
- Richte ein venv ein:
- Installiere die benötigten Pakete:
python3 -m pip install -r requirements.txt "psycopg[binary]"
- (falls nicht bereits vorhanden) lege einen PostgreSQL-User an (
createuser -P hub_app
) sowie eine Datenbank (createdb -O hub_app hub
) - unter Linux ggf. viasudo -u postgres
- Lege eine Datei
local_settings.py
insrc/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',
}
}
- Lege die Datenbanktabellen an:
./manage.py migrate
- Richte einen Admin-Nutzer (für die Anwendung) ein:
./manage.py createsuperuser
- optional: Import von Demo-Daten:
./manage.py loaddata ./core/fixtures/rc3_2021.json
- optional: Für deinen Adminuser via Admin-Seite einen
ConferenceMember
anlegen um den User für das Frontend freizuschalten
Nutzung
- Gehe in das
src
Verzeichnis, nicht-direnv-Nutzer müssen das venv manuell aktivieren (siehe oben) - Wende ggf. vorhandene DB-Migrations an (wenn du gerade aus dem Git geupdatet hast):
./manage.py migrate
- Stelle sicher dass alle Translations aktuell sind:
./manage.py compilemessages
- Lasse alle staticfiles einsammeln:
./manage.py collectstatic
- Starte den Dev-Server:
./manage.py runserver
- 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)
- Gehe in das Verzeichnis
src/plainui/
- Führe
yarn
aus, um die node_modules zu generieren - Führe
yarn build
aus um das CSS zu kompilieren - 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 beimsgstr
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.