Lokales Setup¶

Diese Seite beschreibt, wie du eine vollständige lokale Entwicklungsumgebung für Kamerplanter aufsetzt. Skaffold ist das einzige autorisierte Werkzeug für den Entwicklungsprozess — es übernimmt Image-Building und Deployment im Kubernetes-Cluster. Manuelle docker build- oder kubectl apply-Befehle werden nicht verwendet.

Voraussetzungen¶

Installiere folgende Werkzeuge, bevor du beginnst:

asdf plugin add nodejs
asdf install

Kind-Cluster erstellen¶

Das Repository enthält eine vorkonfigurierte Kind-Konfiguration mit drei Knoten (1 Control Plane, 2 Worker) und vordefinierten Port-Mappings:

kind create cluster --config kind-config.yaml --name kamerplanter

Der Cluster veröffentlicht auf dem Host-System nur die Ingress-Ports 80 und 443. Der Zugriff auf Backend (8000), Frontend (3000) und ArangoDB (8529) läuft über Skaffolds --port-forward (siehe Tabelle unten) — diese Host-Ports müssen beim Start also frei sein.

Beide Ingress-Ports lauschen nur auf 127.0.0.1 (listenAddress in kind-config.yaml). Ohne diese Angabe bindet Kind auf 0.0.0.0 — dann wäre die Entwicklungs-App auf jeder Netzwerkschnittstelle deines Rechners erreichbar, im Light-Modus sogar ohne Anmeldung, für jedes Gerät im selben Netz.

sed 's/listenAddress: "127.0.0.1"/listenAddress: "0.0.0.0"/' kind-config.yaml > /tmp/kind-config-lan.yaml
kind create cluster --config /tmp/kind-config-lan.yaml --name kamerplanter

kind delete cluster --name kamerplanter

Nach dem Erstellen prüfst du, ob kubectl auf den neuen Cluster zeigt:

kubectl cluster-info --context kind-kamerplanter

Secret anlegen¶

Backend, Celery-Worker und die KI-Dienste referenzieren das Kubernetes-Secret kamerplanter-secrets per envFrom bzw. secretKeyRef (definiert in helm/kamerplanter/values.yaml). Die Dev-Overrides heben diese Referenz nicht auf, daher muss das Secret im Namespace default existieren, bevor du Skaffold startest — sonst bleiben die betroffenen Pods in CreateContainerConfigError hängen. FERNET_KEY, ERASURE_TOMBSTONE_SALT und LOG_PSEUDONYM_SALT werden zusätzlich beim Backend-Start als Pflichtwerte geprüft (Fail-Fast); LOG_PSEUDONYM_SALT prüft auch der Celery-Worker.

Lege das Secret einmalig pro frisch erstelltem Cluster an:

kubectl create secret generic kamerplanter-secrets -n default \
  --from-literal=ARANGODB_PASSWORD=dein-sicheres-passwort \
  --from-literal=ARANGO_ROOT_PASSWORD=dein-sicheres-passwort \
  --from-literal=JWT_SECRET_KEY=dev-only-not-for-production-secret-key-1234 \
  --from-literal=POSTGRES_PASSWORD=foba123456 \
  --from-literal=VECTORDB_PASSWORD=foba123456 \
  --from-literal=FERNET_KEY=$(python3 -c "import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())") \
  --from-literal=ERASURE_TOMBSTONE_SALT=$(openssl rand -hex 32) \
  --from-literal=LOG_PSEUDONYM_SALT=$(openssl rand -hex 32) \
  --from-literal=INTERNAL_SERVICE_TOKEN=$(openssl rand -hex 32)

Entwicklungsstart mit Skaffold¶

Skaffold baut die Container-Images lokal (ohne Push in eine Registry) und deployt sie per Helm ins Kind-Cluster. Dateiänderungen werden per sync direkt in laufende Container übertragen, ohne ein komplettes Rebuild.

Vollstack starten¶

skaffold dev --trigger=manual --port-forward

Mit --trigger=manual erfolgt ein Rebuild nur, wenn du r drückst. Das verhindert ungewollte Neustarts bei schnellen Dateiänderungen. Skaffold aktiviert die Port-Weiterleitungen automatisch (siehe Tabelle unten).

Nur Backend¶

skaffold dev --trigger=manual --port-forward -p backend-only

Das backend-only-Profil entfernt das Frontend-Artifact und dessen Port-Weiterleitung aus dem Build-Prozess.

Nur Frontend¶

skaffold dev --trigger=manual --port-forward -p frontend-only

Mit Debugger (debugpy)¶

skaffold debug --port-forward

Das debug-Profil aktiviert DEBUGPY_ENABLED=true als Build-Argument im Backend-Container. Der debugpy-Port 5678 ist dann erreichbar (siehe Debugging).

Mit KI-Stack (RAG / Knowledge-Service)¶

# Hauptapp + KI-Stack gleichzeitig
skaffold dev --trigger=manual --port-forward -m kamerplanter,ki

# Nur KI-Stack (fuer RAG-Entwicklung)
skaffold dev --trigger=manual --port-forward -m ki

Das KI-Modul (-m ki) ist eine eigenstaendige Skaffold-Konfiguration im selben skaffold.yaml. Es deployt Knowledge-Service (Port 8090), Embedding-Service (Port 8080) und VectorDB/TimescaleDB (Port 5433) unabhaengig von der Hauptapplikation. Weitere Details unter Infrastruktur — KI-Modul.

Port-Weiterleitungen¶

Skaffold leitet folgende Ports automatisch weiter, sobald --port-forward gesetzt ist:

Demo-Zugangsdaten¶

Der Backend-Container führt beim ersten Start automatisch Seed-Skripte aus. Danach steht ein Demo-Benutzer bereit:

Backend lokal ohne Kubernetes¶

Für reine Backend-Entwicklung ohne Cluster-Overhead kannst du den FastAPI-Server direkt starten. Voraussetzung ist eine laufende ArangoDB-Instanz (z. B. per Docker Compose).

# ArangoDB und Redis mit Docker Compose starten
docker-compose up -d arangodb valkey

# Python-Abhängigkeiten aus dem Lock installieren (uv: https://docs.astral.sh/uv/)
cd src/backend
uv sync --locked --extra dev
source .venv/bin/activate

# Umgebungsvariablen setzen
export ARANGODB_HOST=localhost
export ARANGODB_PORT=8529
export ARANGODB_DATABASE=kamerplanter
export ARANGODB_USERNAME=root
export ARANGODB_PASSWORD=rootpassword
export REDIS_URL=redis://localhost:6379/0
export DEBUG=true
export REQUIRE_EMAIL_VERIFICATION=false

# Server starten
uvicorn app.main:app --reload --port 8000

Frontend lokal ohne Kubernetes¶

Der Vite-Dev-Server kann unabhängig vom Cluster laufen. Er proxyt alle /api-Anfragen an das Backend (Standard: http://127.0.0.1:8000).

cd src/frontend
npm install
npm run dev

Der Dev-Server startet auf Port 5173. Die Backend-URL kann über die Umgebungsvariable VITE_BACKEND_URL überschrieben werden:

VITE_BACKEND_URL=http://localhost:8000 npm run dev

Home Assistant Integration¶

Die HA-Integration in custom_components/kamerplanter/ wird nicht automatisch von Skaffold deployed. Nach Änderungen an den HA-Integrationsdateien muss der Inhalt manuell in den laufenden Pod kopiert werden:

# Dateien in den Pod kopieren
kubectl cp custom_components/kamerplanter/ \
  default/homeassistant-0:/config/custom_components/kamerplanter/

# Python-Cache löschen (MUSS immer gemacht werden, sonst lädt HA alten Bytecode)
kubectl exec default/homeassistant-0 -- \
  rm -rf /config/custom_components/kamerplanter/__pycache__

# HA-Prozess neustarten (NICHT kubectl delete pod!)
# kill 1 startet nur den Container neu — InitContainers laufen NICHT erneut,
# d.h. die per kubectl cp kopierten Dateien bleiben erhalten.
kubectl exec homeassistant-0 -n default -- kill 1

Fehlerbehebung¶

kubectl config use-context kind-kamerplanter

kubectl logs -l app=kamerplanter-backend --tail=50

lsof -ti:8000 | xargs kill -9

kubectl exec -it deployment/kamerplanter-backend -- \
  python -m app.migrations.seed_auth

Siehe auch¶

• Code-Standards
• Testen
• Debugging