Zum Inhalt

Lokales Backend-Setup

Stand: 14.10.2026 11:06 Branch: main Status: Anleitung

Änderungshistorie anzeigen

Diese Anleitung beschreibt den lokalen Start des DiveLogix360-Backends. Gearbeitet wird ausschliesslich auf dem Branch main; auf jedem Entwicklungsrechner liegt ein eigener Klon unter C:\03 Dev\divelogix360, abgeglichen über GitHub.

Ziel ist nicht die Produktivinstallation, sondern die technische Prüfung des vorhandenen UC00-Backend-Kerns gegen die bestehende Supabase-Dev-Datenbank.

Voraussetzungen

Auf dem Entwicklungs-PC sollten vorhanden sein:

  • Node.js LTS
  • npm
  • Git
  • Visual Studio Code oder eine vergleichbare IDE
  • Zugriff auf das GitHub-Repository dmittig/divelogix360
  • Supabase-Verbindungsdaten für die Dev-Datenbank

Repository vorbereiten

Neu klonen, zum Beispiel in GitHub Desktop über File → Clone repository… mit dem lokalen Pfad C:\03 Dev\divelogix360, oder in PowerShell:

cd "C:\03 Dev"
git clone https://github.com/dmittig/divelogix360.git

Vor jedem Arbeitsbeginn den aktuellen Stand holen, in GitHub Desktop mit Fetch origin und Pull origin oder in PowerShell:

cd "C:\03 Dev\divelogix360"
git pull

Das Repository wird nicht in einem synchronisierten Cloud-Ordner wie OneDrive abgelegt. Die nicht versionierte Datei backend/.env wird zwischen den Rechnern unverändert und auf sicherem Weg übertragen, damit gemeinsame Schlüssel wie DEV_TOTP_ENCRYPTION_KEY und die JWT-Schlüssel übereinstimmen.

Backend vorbereiten

cd "C:\03 Dev\divelogix360\backend"
npm ci
npx prisma generate

Umgebungsvariablen einrichten

Die Datei backend/.env.example als Vorlage verwenden:

copy .env.example .env

Danach die Datei .env mit den echten Entwicklungswerten befüllen.

Wichtig:

  • .env darf nicht in Git committet werden.
  • Supabase-Passwörter und JWT-Schlüssel bleiben lokal.
  • Produktivwerte dürfen nicht in die Entwicklungsdatei eingetragen werden.
  • Keine Kopien der .env im Repository-Ordner ablegen (auch nicht umbenannt); .gitignore erfasst nur .env, .env.* und .env *.

Geheimnisse ersetzen (Rotation)

Gelangt ein Geheimnis an einen unsicheren Ort, wird es ersetzt. Neue Werte erzeugt das Skript backend/scripts/generate-secrets.mjs lokal und ohne Netzwerkzugriff:

node scripts/generate-secrets.mjs cookie
node scripts/generate-secrets.mjs jwt
node scripts/generate-secrets.mjs totp
node scripts/generate-secrets.mjs password
node scripts/generate-secrets.mjs db dlx_login_platform
node scripts/generate-secrets.mjs db dlx_login_tenant
node scripts/generate-secrets.mjs db postgres

Für die Login-Rollen gibt das Skript einen SQL-Befehl ALTER ROLE mit SCRAM-SHA-256-Prüfwert aus, damit das Passwort nicht im Klartext im SQL-Editor oder in Datenbankprotokollen erscheint. Das Passwort von postgres wird im Supabase-Dashboard gesetzt. password erzeugt DEV_SUPERADMIN_PASSWORD für prisma/seed-dev-superadmin.ts. Nach jedem Wechsel dieselben Werte in die .env beider Entwicklungsrechner übernehmen. Ein neuer DEV_TOTP_ENCRYPTION_KEY macht gespeicherte 2FA-Einrichtungen unlesbar; die 2FA der Testkonten ist danach neu einzurichten.

Supabase-Verbindung prüfen

Die 18 Tabellen sind bereits in Supabase installiert. Deshalb wird das Schema nicht neu installiert, sondern zuerst abgeglichen.

Empfohlene Prüfreihenfolge:

npm run prisma:generate
npx prisma db pull
npm run prisma:generate

Bedeutung:

  • npm run prisma:generate erzeugt den Prisma Client aus dem vorhandenen Repository-Schema.
  • npx prisma db pull liest den realen Supabase-Stand ein und zeigt Abweichungen zum lokalen Schema.
  • Das zweite npm run prisma:generate prüft, ob der Prisma Client nach dem Abgleich weiterhin erzeugt werden kann.

Wichtig:

Wenn npx prisma db pull die Datei backend/prisma/schema.prisma verändert, diese Änderung nicht ungeprüft übernehmen. Zuerst prüfen, ob die Änderung fachlich korrekt ist.

Build und Tests prüfen

npm run build
npm test

Ziel:

  • TypeScript kompiliert fehlerfrei.
  • Vorhandene Tests laufen.
  • Fehlende oder fehlerhafte Tests werden sichtbar.

Entwicklungsserver starten

npm run start:dev

Erwarteter Standard:

http://localhost:3000/v1

Der genaue Port und API-Prefix hängen von den Werten in .env ab.

Erste technische Abnahme

Folgende Punkte sollten dokumentiert werden:

Prüfung Erwartung Ergebnis
npm install läuft ohne kritische Fehler offen
npm run prisma:generate Prisma Client wird erzeugt offen
npx prisma db pull Supabase-Schema wird gelesen offen
npm run build Backend kompiliert offen
npm test Tests laufen oder Fehler sind dokumentiert offen
npm run start:dev API startet lokal offen

Nächster Schritt nach erfolgreichem Start

Nach erfolgreichem lokalem Start folgt UC00-Testlogik:

  • SuperAdmin per Seed anlegen
  • SuperAdmin-Login testen
  • Test-Tenant anlegen
  • Tenant-Admin-Einladung erzeugen
  • Einladung einlösen
  • Tenant-Admin-Login testen
  • Refresh Token testen
  • Logout testen

Änderungshistorie

Datum, Uhrzeit Version Änderung Autor
14.10.2026 11:06 1.5 Rotation um DEV_SUPERADMIN_PASSWORD ergänzt Claude
14.10.2026 10:25 1.4 Abschnitt «Geheimnisse ersetzen (Rotation)» mit generate-secrets.mjs ergänzt; Hinweis auf .env-Kopien im Repository-Ordner Claude
13.10.2026 14:08 1.3 Veralteten Branch stabilize-uc00-backend entfernt; Arbeit ausschliesslich auf main mit je einem lokalen Klon pro Rechner, Abgleich über GitHub und sichere Übertragung der .env beschrieben; Installation auf npm ci und prisma generate umgestellt Claude
12.10.2026 09:58 1.2 Änderungshistorie ans Dokumentende verschoben und Sprunglink «Änderungshistorie anzeigen» unter dem Kopf ergänzt (einheitlicher Dokumentaufbau gemäss AGENTS.md) Claude
12.10.2026 09:08 1.1 Branch-Angabe im Kopfbereich auf main korrigiert Claude
01.08.2026 14:55 1.0 Kopfbereich vereinheitlicht David Mittig