stackpulse/docs/backend.md

Backend & API

Das Backend implementiert alle Anwendungsfälle über Express-Routen, Socket.IO für Echtzeit-Events und eine SQLite-Datenbank als Persistenzschicht. Dieser Abschnitt fasst die wichtigsten Module, Entitäten und Endpunkte zusammen.

Laufzeit & Einstiegspunkte

• backend/index.js initialisiert Express, Socket.IO, lädt .env, sorgt für Schema-Validierung (ensureDatabaseSchema) und Default-Daten (ensureSuperuserFromEnv, ensureDefaultsFromEnv).
• Start via npm start (siehe package.json); Migrationen über npm run migrate.
• Datenbankdatei: backend/data/stackpulse.db, WAL-Modus aktiv.

Module

Modul	Pfad	Aufgabe
Auth/Superuser	auth/superuser.js	Registrieren/Verifizieren von Superusern, Login, Passwortvalidierung, Sicherheitsphrasen.
Users & Groups	users/*, groups/*, permissions/*	CRUD für Benutzer, Gruppen, Rechtezuweisung, Ableitung effektiver Berechtigungen. Rechte-Labels z. B. Bereich & Navigation, Benutzergruppen bearbeiten, Benutzer löschen.
Setup	setup/index.js	Verwaltung registrierter Portainer-Server, sichere Ablage der API-Keys, Setup-Status.
Logging	logging/eventLogs.js	Einheitliches Ereignislogging (Insert, Filter, Delete, Export).
Maintenance	maintenance/state.js + Helper in index.js	Wartungsmodus, SSH-Konfiguration, Update-Skripte und Ausführung.
Portainer Proxy	Funktionen in index.js	Kommunikation mit Portainer (axiosInstance + dynamische baseURL), Environment-Erkennung und Redeploy-Strecke.

API-Überblick (Auszug)

Setup & Server

Methode	Route	Beschreibung
GET	/api/setup/status	Gibt zurück, ob Server/API-Key/Superuser vorhanden sind.
POST	/api/setup/test-portainer	Verifiziert URL + API-Key gegen Portainer.
POST	/api/setup/portainer-stacks	Listet Stacks (für Preview im Wizard).
POST	/api/setup/complete	Markiert Setup als abgeschlossen und hinterlegt Server/API-Key.
DELETE	/api/setup/servers/:id	Entfernt einen registrierten Portainer-Server.
PUT	/api/setup/servers/:id/api-key	Überschreibt API-Key.
PUT	/api/setup/self-stack	Speichert die ID des StackPulse-Stacks, damit dieser nicht redeployed wird.

Authentifizierung

Methode	Route	Beschreibung
POST	/api/auth/login	Username/Passwort-Login, setzt HTTP-only Cookie.
POST	/api/auth/logout	Session beenden & Cookie löschen.
GET	/api/auth/session	Liefert eingeloggten Benutzer + Permissions.
POST	/api/auth/recover/verify & /reset	Passwortreset über Sicherheitsphrase.
GET/POST/DELETE	/api/auth/superuser/*	Abfrage, Registrierung oder Entfernen des Superusers.

Benutzer & Gruppen

Methode	Route	Beschreibung
GET/POST	/api/users	Liste anlegen, neue Benutzer erstellen.
GET/PUT/DELETE	/api/users/:id	Details lesen, bearbeiten oder löschen.
PUT	/api/users/:id/groups	Gruppenmitgliedschaften aktualisieren.
PUT	/api/users/:id/active	Benutzer aktivieren/deaktivieren.
GET/POST	/api/users/:id/security-phrase, /renew	Sicherheitsphrase anzeigen bzw. neu generieren.
GET/POST	/api/groups	Gruppen auflisten oder neu anlegen.
PUT/DELETE	/api/groups/:id	Gruppe editieren oder entfernen.
GET/PUT	/api/groups/:id/permissions	Berechtigungen lesen/setzen.

Stacks & Redeploy

Methode	Route	Beschreibung
GET	/api/stacks	Aggregierte Liste inkl. Filter, Self-Stack-Blockade und Redeploy-Status.
PUT	/api/stacks/:id/redeploy	Redeploy eines einzelnen Stacks.
PUT	/api/stacks/redeploy-selection	Redeploy einer Liste übermittelter stackIds.
PUT	/api/stacks/redeploy-all	Redeploy aller Stacks (Recht Redeploy Alle).

Das Backend veröffentlicht den Redeploy-Fortschritt parallel über Socket.IO (redeployStatus Event) und unterscheidet die Phasen queued, started, success, error, info.

Logging & Wartung

Methode	Route	Beschreibung
GET	/api/logs	Filterbare/Paginierbare Event-Logs.
DELETE	/api/logs/:id oder /api/logs	Einzelne oder gefilterte Logs löschen.
GET	/api/logs/export	CSV-Export anhand der Query-Filter.
GET/POST	/api/maintenance/mode	Status abfragen oder toggeln.
GET	/api/maintenance/config	Liefert Maintenance-Status, Update-Skript & SSH-Config.
PUT/DELETE	/api/maintenance/ssh-config	SSH-Credentials speichern/entfernen.
POST	/api/maintenance/test-ssh	Verbindungstest mit optionalem Override.
PUT/DELETE	/api/maintenance/update-script	Custom Update-Skript pflegen.
POST	/api/maintenance/portainer-update	Update-Kommando per SSH ausführen (mit Custom/Default-Skript).

Datenbank & Schema

• ensureDatabaseSchema() erzeugt Tabellen bei jedem Start, inklusive Default-Gruppen, Permissions, Settings, Server-Einträge und Trigger.
• Permissions werden anhand der Blueprint-Datei backend/db/dbs eingelesen. Jede Permission definiert Key, Label (z. B. Bereich & Navigation, Server bearbeiten, SSH/Update-Skript, Update durchführen, Doppelte Stacks), Level (full, read, none) und Abhängigkeiten.
• Events werden in event_logs gespeichert. Relevante Felder:
  • category, event_type, action, status, severity
  • entity_type, entity_id, entity_name
  • actor_type, actor_id, actor_name
  • context_type, context_id, context_label
  • message, metadata (JSON)
• Filter-Parameter (ids, categories, eventTypes, status, stackIds, Zeitfenster) werden in buildEventLogFilter zentral verarbeitet.

Berechtigungssystem

• Jeder Benutzer gehört zu beliebig vielen Gruppen; die effektiven Rechte ergeben sich aus der höchsten Ausprägung pro Permission (Labels wie Bereich & Navigation, Server bearbeiten, SSH/Update-Skript, Update durchführen, Doppelte Stacks).
• Superuser erhalten alle Berechtigungen und können nicht über das UI entzogen werden.
• PermissionGate im Frontend spiegelt die gleichen Keys. Wichtigste Bereiche:
  • Redeploy einzeln/Auswahl/Alle
  • Bereich & Navigation (Logs), Logs Exportieren, Logs löschen
  • Bereich & Navigation (Benutzer), Benutzer bearbeiten/löschen, Sicherheitsschlüssel
  • Bereich & Navigation (Benutzergruppen), Benutzergruppen bearbeiten/löschen
  • Wartung: Bereich & Navigation (Wartung), Server-Sektion, Server bearbeiten/löschen, SSH/Update-Skript, Update durchführen, Doppelte Stacks

Redeploy-Workflow

1. Eingehender Request wird mit maintenanceGuard geprüft (Maintenance-Modus blockiert optional Redeploys).
2. Das Backend ermittelt den zugehörigen Portainer-Endpoint (resolvePortainerEnvironmentId).
3. Der Redeploy wird über Portainer ausgeführt (/api/stacks/:id/redeploy), Log-Einträge werden erstellt.
4. broadcastRedeployStatus() aktualisiert das In-Memory-Tracking (redeployingStacks) und sendet Socket.IO Events.
5. Fehler führen zu event_logs-Einträgen mit severity=error, UI zeigt Toasts via ToastProvider.

Wartungs- und Updatepfad

• maintenance/state.js persistiert Aktivierung & Nachricht im Setting maintenance_mode.
• SSH-Konfigurationen (Host, Port, User, Passwort, extra args) werden verschlüsselt gespeichert (getPortainerSshConfig).
• Update-Skripte lassen sich überschreiben, Standard-Skript liegt in DEFAULT_PORTAINER_UPDATE_SCRIPT (Bash-Befehle).
• Update-Status hält Laufzeiten, letzte Ergebnisse und Logauszüge in-memory & Settings bereit.

Erweiterungstipps

• Neue API-Routen sollten requirePermission(..) nutzen, Logging via logEvent() hinzufügen und – falls Portainer-Aufrufe stattfinden – das axiosInstance verwenden.
• Einstellungen stets über db/settings.js verwalten, damit UI & CLI konsistent bleiben.
• Für breaking DB-Änderungen existiert kein Migrations-Framework – erweitere ensureDatabaseSchema inkl. Versionsflag, um Idempotenz sicherzustellen.