Development.md

Lokale Entwicklung

Dieses Projekt basiert auf Python 3.13+ und Django 5.1+.

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. Unter Windows getestet mit WSL 2.
2. Klonen dieses Repositories an beliebigen Ort.
3. Image erzeugen: docker compose build
   • Für schnellere Builds kann buildkit verwendet werden:

     export DOCKER_BUILDKIT=1

   • 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
   • 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.
5. Optional: Import von Demo-Daten: docker compose exec -it hub python manage.py loaddata ./core/fixtures/anhalter.json

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

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.13 (oder höher) und habe eine PostgreSQL-Datenbank zur Hand (z.B. aus dem docker mit exposed port). 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
   • Python Paketmanager: pdm: Kann mit OS Installationsmitteln, mit pip install pdm oder pipx install pdm installiert werden.
2. Klone dieses Repository an beliebigen Ort.
3. Erstelle die virtuelle Umgebung mit pdm info
4. Installiere die python dependencies mit pdm install
5. (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
6. Konfiguriere deine Instanz mittels:
   • Umgebungsvariablen (z.B. direnv, oder env Datei)
   • oder mittels einer 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
STORAGE_TYPE = 'local'
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_2021.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: pdm manage migrate
9. Richte einen Admin-Nutzer (für die Anwendung) ein: pdm manage createsuperuser
10. optional: Import von Demo-Daten: pdm manage.py loaddata .src/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. Aktiviere das virtual env pdm venv activate
2. Wende ggf. vorhandene DB-Migrations an (wenn du gerade aus dem Git geupdatet hast): pdm manage migrate
3. Stelle sicher dass alle Translations aktuell sind: pdm manage compilemessages
4. Lasse alle staticfiles einsammeln: pdm manage collectstatic --noinput
5. Starte den Dev-Server: pdm manage runserver
6. Besuche die lokale Instanz: Admin-Seite, API und plainui-Frontend

PlainUI Development Tipps

Ein Theme erstellen

Sämtliche Hub-Komponenten müssen eigene Variablen definieren. Alle Variablen sind in _variables-hub.scss enthalten. Gegebenenfalls müssen neue Variablen hinzugefügt werden. Ein neues Theme kann dann Variablen aus Bootstrap oder dem Hub überschreiben.

Als Beispiel kann das hub-high-contrast.scss genommen werden.

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

Kompiliertes CSS mit lokalem docker-compose Setup ausliefern

Um das kompilierte CSS über eine lokale Instanz auszuliefern die z.B. mit docker compose up ausgeliefert wurde muss dem nginx Container in der docker-compose.yml ein zusätzlicher Ordner gemounted werden:

volumes:
  - ./src/plainui/static:/www/static
  ...

CSS Watch im Container

1. Um die Styles zu kompilieren und eine watch zu starten benutze docker compose --profile build up -d local-static

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.

Python Development Tipps

Abhängigkeitsverwaltung

Zur Verwaltung der verwendeten python Abhängigkeiten wir der Paketmanager PDM verwendet. Mittels diesem werden die requirements.txt und die requirements.dev.txt erzeugt.

Installation der aktuellen Abhängigkeiten

Um die aktuellen python Abhängigkeiten zu installieren kann das Kommando pdm install verwendet werden. Mit dem Kommando pdm sync --clean kann sichergestellt werden, dass genau die Versionen aus dem pdm lock file installiert werden. Achtung: Nicht in der Lock Datei enthaltene python Pakete werden deinstalliert!

Hinzufügen von neuen Abhängigkeiten

Um neue Abhängigkeiten hinzuzufügen kann das Kommando pdm add verwendet werden. Mit dem Parameter --dev kann eine Abhängigkeit als Entwicklungs-Abhängigkeit deklariert werden. Diese wird dann in den Produktivinstanzen nicht installiert.

Anschließend müssen die requirements.txt und requirements.dev.txt angepasst werden. Wenn pre-commit verwendet wird, passiert dies automatisch beim commit. Alternativ können die folgenden Kommandos verwendet werden

pdm export --no-hashes -o requirements.txt --prod
pdm export --no-hashes -o requirements.dev.txt --dev

Debugging DJANGO

Context im HTML-File ausgeben:

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

oder:

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

Übersetzungen extrahieren & compilieren

• pdm manage 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!
• pdm manage 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) }}