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