diff --git a/404.html b/404.html index e241ecb..867cafb 100644 --- a/404.html +++ b/404.html @@ -207,6 +207,450 @@ + + + + + + + + + + + +
  • + + + + + + + + + + +
    • + + + + + + + + + + + + + + +
  • + + + + + + + + + + +
    • + + + diff --git a/architecture/index.html b/architecture/index.html new file mode 100644 index 0000000..d145a86 --- /dev/null +++ b/architecture/index.html @@ -0,0 +1,1007 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Architektur - Stackpulse Dokumentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + Skip to content + + +
    +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    + +
    + + + + + +

    Architektur

    +

    StackPulse folgt einer klassischen Client/Server-Architektur, bei der das Backend den Single-Source-of-Truth darstellt und das Frontend ausschließlich über wohldefinierte REST- und Socket.IO-Schnittstellen kommuniziert.

    +
    ┌────────────┐      HTTPS + WebSocket      ┌───────────────┐      HTTPS       ┌────────────────┐
+│  Frontend  │ ─────────────────────────▶  │   Backend     │ ───────────────▶ │ Portainer API │
+│ (React)    │ ◀───── Auth-Cookie + JSON ─ │ (Express)     │ ◀─────────────── │  Business Ed.  │
+└────────────┘      Redeploy Events       └───────────────┘   (Axios Proxy)   └────────────────┘
+                                             │
+                                             ▼
+                                     SQLite Datenbank
+
    +

    Hauptschichten

    +
      +
    • Frontend (Vite + Material Tailwind): stellt alle Views, Formulare, Tabellen und Echtzeit-Widgets bereit. Die AuthProvider-Komponente verwaltet Session, Permissions und Socket-Verbindungen.
      • +
    • Backend (Express + better-sqlite3): aggregiert Daten aus Portainer, persistiert Benutzer/Gruppen/Logs, verwaltet Sessions und stößt Redeploy- sowie Wartungsprozesse an.
      • +
    • Persistenz (SQLite): Datei backend/data/stackpulse.db, WAL-Modus aktiviert. Tabellen umfassen u. a. users, groups, permissions, servers, server_api_keys, event_logs, settings sowie Hilfstabellen für Tokens und Sicherheitspassphrasen.
      • +
    +

    Datenflüsse

    +
      +
    1. Setup-Phase: /api/setup/* nimmt Serverdaten entgegen, verschlüsselt API-Keys (aes-256-gcm via PORTAINER_API_SECRET) und erstellt Einträge in servers/server_api_keys.
      2. +
    2. Authentication: /api/auth/login erstellt Sessions (JWT-ähnliche Tokens in Cookies), AuthProvider ruft /api/auth/session zyklisch ab und speichert Berechtigungen.
      3. +
    3. Stack-Übersicht: Frontend ruft /api/stacks auf. Das Backend proxyt Portainer /api/endpoints/:id/docker/stacks, ergänzt Caching, interne Metadaten und liefert Redeploy-Status.
      4. +
    4. Redeploy: UI stößt /api/stacks/:id/redeploy, /api/stacks/redeploy-selection oder /api/stacks/redeploy-all an. Das Backend ruft Portainer-Endpoints, protokolliert Events und broadcastet Fortschritt via Socket.IO redeployStatus.
      5. +
    5. Logging: Jeder relevante Vorgang erzeugt Einträge in event_logs (siehe logging/eventLogs.js). Frontend filtert/paginiert über /api/logs und kann Exporte /api/logs/export herunterladen.
      6. +
    6. Wartung: /api/maintenance/* verwaltet Maintenance-Mode, SSH-Zugänge, Update-Skripte und serverseitige Settings (db/settings.js).
      7. +
    +

    Verzeichnis-Referenz

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    PfadInhalt
    backend/index.jsHerzstück der API inkl. Routing, Socket.IO, Redeploy, Setup, Auth.
    backend/auth/Superuser-Verwaltung, Passwort- und Tokenfunktionen, Sicherheitsphrasen.
    backend/db/SQLite-Initialisierung (ensure.js/schemaEnsure.js), Settings-Layer, DB-Blueprints.
    backend/logging/Event-Log Modellierung, Filter/Export/Delete.
    backend/groups/, backend/users/, backend/permissions/Domain-Logik für Benutzer- & Rechteverwaltung.
    backend/maintenance/Maintenance-Mode sowie SSH-/Update-Konfiguration.
    frontend/src/React-App (Layouts, Pages, Widgets, Provider). routes.jsx definiert Navigation & Permissions.
    scripts/Hilfsskripte (z. B. start-dev.sh).
    Dockerfile, docker-compose*.ymlBuild- & Deployment-Spezifikation.
    +

    Konfiguration & Secrets

    +
      +
    • API-Keys und Passwörter werden verschlüsselt in SQLite abgelegt (server_api_keys, settings).
      • +
    • Settings (Maintenance, Update-Skripte, SSH) nutzen db/settings.js mit JSON-Serialisierung.
      • +
    • Das Backend erzwingt HTTPS-Requests Richtung Portainer (https.Agent mit deaktivierter Zertifikatsprüfung für interne Netze).
      • +
    • Socket.IO lauscht auf demselben Port wie Express (/socket.io). CORS ist aktuell für alle Origins offen – für produktive Deployments empfiehlt sich ein Reverse Proxy mit Authentifizierung.
      • +
    +

    Skalierung & Grenzen

    +
      +
    • SQLite eignet sich für Einzelinstanzen. Für höhere Last empfiehlt sich eine Umstellung auf Postgres/MySQL (der Code kapselt Zugriffe weitgehend in db/*).
      • +
    • Redeploy-Operationen werden seriell behandelt (redeployingStacks + Status-Caching). Parallele Ausführung ist möglich, solange Portainer dies unterstützt.
      • +
    • Logging wird ausschließlich serverseitig betrieben; Client-seitige Filterung erfolgt über Query-Parameter.
      • +
    +

    Die weiteren Kapitel vertiefen Backend- und Frontend-spezifische Details.

    + + + + + + + + + + + + + +
    +
    + + + +
    + +
    + + + +
    +
    +
    +
    + + + + + + + + + + + + + \ No newline at end of file diff --git a/backend/index.html b/backend/index.html new file mode 100644 index 0000000..c504046 --- /dev/null +++ b/backend/index.html @@ -0,0 +1,1429 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Backend & API - Stackpulse Dokumentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + Skip to content + + +
    +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    + +
    + + + + + +

    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

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ModulPfadAufgabe
    Auth/Superuserauth/superuser.jsRegistrieren/Verifizieren von Superusern, Login, Passwortvalidierung, Sicherheitsphrasen.
    Users & Groupsusers/*, groups/*, permissions/*CRUD für Benutzer, Gruppen, Rechtezuweisung, Ableitung effektiver Berechtigungen.
    Setupsetup/index.jsVerwaltung registrierter Portainer-Server, sichere Ablage der API-Keys, Setup-Status.
    Logginglogging/eventLogs.jsEinheitliches Ereignislogging (Insert, Filter, Delete, Export).
    Maintenancemaintenance/state.js + helper in index.jsWartungsmodus, SSH-Konfiguration, Update-Skripte und Ausführung.
    Portainer ProxyFunktionen in index.jsKommunikation mit Portainer (axiosInstance + dynamische baseURL), Environment-Erkennung und Redeploy-Strecke.
    +

    API-Überblick (Auszug)

    +

    Setup & Server

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    MethodeRouteBeschreibung
    GET/api/setup/statusGibt zurück, ob Server/API-Key/Superuser vorhanden sind.
    POST/api/setup/test-portainerVerifiziert URL + API-Key gegen Portainer.
    POST/api/setup/portainer-stacksListet Stacks (für Preview im Wizard).
    POST/api/setup/completeMarkiert Setup als abgeschlossen und hinterlegt Server/API-Key.
    DELETE/api/setup/servers/:idEntfernt einen registrierten Portainer-Server.
    PUT/api/setup/servers/:id/api-keyÜberschreibt API-Key.
    PUT/api/setup/self-stackSpeichert die ID des StackPulse-Stacks, damit dieser nicht redeployed wird.
    +

    Authentifizierung

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    MethodeRouteBeschreibung
    POST/api/auth/loginUsername/Passwort-Login, setzt HTTP-only Cookie.
    POST/api/auth/logoutSession beenden & Cookie löschen.
    GET/api/auth/sessionLiefert eingeloggten Benutzer + Permissions.
    POST/api/auth/recover/verify & /resetPasswortreset über Sicherheitsphrase.
    GET/POST/DELETE/api/auth/superuser/*Abfrage, Registrierung oder Entfernen des Superusers.
    +

    Benutzer & Gruppen

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    MethodeRouteBeschreibung
    GET/POST/api/usersListe anlegen, neue Benutzer erstellen.
    GET/PUT/DELETE/api/users/:idDetails lesen, bearbeiten oder löschen.
    PUT/api/users/:id/groupsGruppenmitgliedschaften aktualisieren.
    PUT/api/users/:id/activeBenutzer aktivieren/deaktivieren.
    GET/POST/api/users/:id/security-phrase, /renewSicherheitsphrase anzeigen bzw. neu generieren.
    GET/POST/api/groupsGruppen auflisten oder neu anlegen.
    PUT/DELETE/api/groups/:idGruppe editieren oder entfernen.
    GET/PUT/api/groups/:id/permissionsBerechtigungen lesen/setzen.
    +

    Stacks & Redeploy

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    MethodeRouteBeschreibung
    GET/api/stacksAggregierte Liste inkl. Filter, Self-Stack-Blockade und Redeploy-Status.
    PUT/api/stacks/:id/redeployRedeploy eines einzelnen Stacks.
    PUT/api/stacks/redeploy-selectionRedeploy einer Liste übermittelter stackIds.
    PUT/api/stacks/redeploy-allRedeploy aller Stacks (Permission stacks-redeploy-all).
    +

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

    +

    Logging & Wartung

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    MethodeRouteBeschreibung
    GET/api/logsFilterbare/Paginierbare Event-Logs.
    DELETE/api/logs/:id oder /api/logsEinzelne oder gefilterte Logs löschen.
    GET/api/logs/exportCSV-Export anhand der Query-Filter.
    GET/POST/api/maintenance/modeStatus abfragen oder toggeln.
    GET/api/maintenance/configLiefert Maintenance-Status, Update-Skript & SSH-Config.
    PUT/DELETE/api/maintenance/ssh-configSSH-Credentials speichern/entfernen.
    POST/api/maintenance/test-sshVerbindungstest mit optionalem Override.
    PUT/DELETE/api/maintenance/update-scriptCustom Update-Skript pflegen.
    POST/api/maintenance/portainer-updateUpdate-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, 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.
      • +
    • Superuser erhalten alle Berechtigungen und können nicht über das UI entzogen werden.
      • +
    • PermissionGate im Frontend spiegelt die gleichen Keys. Wichtigste Bereiche:
      • +
    • stacks-* (Redeploy)
      • +
    • logs-*
      • +
    • users-* & user-groups-*
      • +
    • maintenance-* (inkl. Unterrechte maintenance-server-*, maintenance-ssh-update, maintenance-update)
      • +
    +

    Redeploy-Workflow

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

    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.
      • +
    + + + + + + + + + + + + + +
    +
    + + + +
    + +
    + + + +
    +
    +
    +
    + + + + + + + + + + + + + \ No newline at end of file diff --git a/frontend/index.html b/frontend/index.html new file mode 100644 index 0000000..fd2ce83 --- /dev/null +++ b/frontend/index.html @@ -0,0 +1,1086 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Frontend - Stackpulse Dokumentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + Skip to content + + +
    +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    + +
    + + + + + +

    Frontend

    +

    Das Frontend basiert auf React 18, Vite und dem Material Tailwind Dashboard. Es nutzt Context Provider für Authentifizierung, Seitenstatus, Toaster und Wartungsinformationen.

    +

    Build & Skripte

    + + + + + + + + + + + + + + + + + + + + + +
    BefehlBeschreibung
    npm run devStartet den Vite Dev-Server (Port 5173, HMR aktiviert).
    npm run buildErstellt ein Production-Bundle (frontend/dist). Das Dockerfile kopiert dieses Paket ins Backend (backend/public).
    npm run previewVorschau auf das gebaute Bundle.
    +

    Projektstruktur

    +
    frontend/src
+├── App.jsx                # Entry-Point, registriert Layouts & Provider
+├── components/           # AuthProvider, PermissionGate, Toast/Maintenance/PageProvider
+├── layouts/              # Dashboard-Layout (Sidebar, Navbar) & Auth-Layout
+├── pages/
+│   ├── auth/             # SignIn, SignUp, ForgotPassword, SignOut
+│   ├── dashboard/        # Stacks, Logs, Maintenance, Users, Usergroups, Detailseiten
+│   └── setup/            # Setup-Wizard & Helper Screens
+├── routes.jsx            # zentrale Navigationsdefinition inkl. Permissions
+├── widgets/, data/, configs/, assets/
+└── tailwind.css          # Tailwind Layer & Custom Styles
+
    +

    Routing & Navigation

    +
      +
    • routes.jsx beschreibt sowohl Dashboard- als auch Auth-Routen. Jede Dashboard-Seite besitzt optional ein permission-Objekt, das vom PermissionGate ausgewertet wird.
      • +
    • Der Layout-Switch erfolgt über layouts/index.jsx, das wiederum Sidebar/Topbar-Komponenten aus dem Material Tailwind Dashboard nutzt.
      • +
    • Auth-Routen (/sign-in, /sign-up, /forgot-password, /logout) werden im Auth-Layout ohne Sidebar dargestellt.
      • +
    +

    State-Management & Contexts

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    ProviderAufgabe
    AuthProviderSpeichert User, Permissions, Session-Status. Stellt refreshSession, logout, hasPermission bereit.
    PageProviderZentrale UI-Zustände (z. B. Ladeanzeigen, modale Dialoge) für Dashboard-Komponenten.
    ToastProviderGlobale Notifications (z. B. Redeploy-Erfolg/Fehler).
    MaintenanceProviderCached Maintenance-Status, erkennt aktive Maintenance Modes und zeigt Hinweise.
    +

    Wichtige Seiten

    +
      +
    • Stacks (pages/dashboard/stacks.jsx): Hauptübersicht mit Tabellen, Suche, Filtern, Bulk- und Einzelredeploy. Bindet socket.io-client für Live-Updates (redeployStatus).
      • +
    • Logs (pages/dashboard/logs.jsx): Tabellenansicht mit Statusfarben, Filterchips, Export-/Delete-Aktionen. Nutzt axios-Queries gegen /api/logs.
      • +
    • Maintenance (pages/dashboard/maintenance.jsx): Formulare zur Verwaltung von Update-Skript, SSH-Konfiguration, Maintenance-Mode-Toggle und Portainer-Statusprüfung.
      • +
    • Users / Usergroups: CRUD-Oberfläche für Benutzer, Gruppen, Berechtigungszuweisung inkl. Sicherheitsphrasen-Handling.
      • +
    • Setup (pages/setup): Schrittweiser Wizard (Server -> API-Key -> Superuser). Wird solange angezeigt, bis /api/setup/status vollständig ist.
      • +
    +

    Datenzugriff

    +
      +
    • HTTP-Anfragen erfolgen via axios (global konfiguriert in frontend/src/components/AuthProvider bzw. direkt in den Seiten). Cookies werden automatisch vom Browser beigesteuert (credentials: 'include').
      • +
    • Socket.IO wird nur im Stack-Dashboard verwendet; Verbindungsaufbau erfolgt in stacks.jsx (io('/', { path: '/socket.io' })).
      • +
    • Fehlerbehandlung: Jede Seite zeigt Toasts und/oder Inline-Warnungen. Auth-Fehler leiten zur Loginseite um.
      • +
    +

    Styling & Komponenten

    +
      +
    • Tailwind Utility-Klassen liefert Material Tailwind bereits vordefiniert (Theme in configs).
      • +
    • Custom-Komponenten wie Tabellen, Filterchips oder Formulare sind überwiegend in widgets/ ausgelagert.
      • +
    • Icons stammen aus @heroicons/react. Farben/Typografie folgen Creative Tim Vorgaben, können aber zentral in frontend/src/configs angepasst werden.
      • +
    +

    Erweiterungshinweise

    +
      +
    1. Neue Seiten: Route in routes.jsx ergänzen, optional PermissionGate konfigurieren und Seite unter pages/dashboard oder pages/auth anlegen.
      2. +
    2. API-Anbindungen: Verwende axios und achte auf try/catch, damit 401/403 sauber abgefangen werden. Bei kritischen Anforderungen refreshSession aufrufen.
      3. +
    3. State teilen: Nutze bestehende Provider bzw. erzeuge einen eigenen Context in components/.
      4. +
    4. Deployment: npm run build liefert ein Self-Contained Bundle. Das Backend dient anschließend als Static Host (express.static).
      5. +
    +

    Damit bietet das Frontend eine anpassbare, klar strukturierte Oberfläche, die eng mit den Backend-Permissions verzahnt ist.

    + + + + + + + + + + + + + +
    +
    + + + +
    + +
    + + + +
    +
    +
    +
    + + + + + + + + + + + + + \ No newline at end of file diff --git a/getting-started/index.html b/getting-started/index.html new file mode 100644 index 0000000..353ab81 --- /dev/null +++ b/getting-started/index.html @@ -0,0 +1,1120 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Getting Started - Stackpulse Dokumentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + Skip to content + + +
    +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    + +
    + + + + + +

    Getting Started

    +

    Dieser Leitfaden hilft dir, StackPulse lokal oder als Container aufzusetzen und die ersten Schritte im UI abzuschließen.

    +

    Voraussetzungen

    +
      +
    • Node.js >= 20 und npm für lokale Entwicklung
      • +
    • Docker & Docker Compose (optional aber empfohlen für Deployment)
      • +
    • Zugriff auf eine Portainer Business Edition samt API-Key
      • +
    • Shell-Zugang zum Host, auf dem StackPulse laufen soll
      • +
    +

    Repository & Abhängigkeiten

    +
    # Repository klonen
+# git clone <repo-url>
+cd stackpulse
+
+# Skript ausführbar machen
+chmod +x scripts/start-dev.sh
+
    +

    Lokale Dev-Umgebung

    +

    Das Skript scripts/start-dev.sh richtet Backend und Frontend automatisch ein:

    +
      +
    1. Backend: npm install, npm run migrate (erstellt/aktualisiert backend/data/stackpulse.db), npm start
      2. +
    2. Frontend: npm install, npm run dev (Port 5173) und ein einmaliges npm run build, um statische Assets ins Backend zu spiegeln
      3. +
    +

    Nach erfolgreichem Start: +- Frontend dev server: http://localhost:5173 +- Backend API & statische Assets: http://localhost:4001

    +

    Zum Stoppen STRG+C verwenden.

    +

    Manuelles Starten

    +
    # Backend
+cd backend
+npm install
+npm run migrate
+PORTAINER_URL=https://portainer.local npm start
+
+# Frontend in zweiter Shell
+cd frontend
+npm install
+npm run dev
+
    +

    Das Backend liest Umgebungsvariablen beim Start. Alternativ kannst du eine .env neben backend/index.js anlegen.

    +

    Zentrale Umgebungsvariablen

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VariableBeschreibung
    PORTAINER_URLBasis-URL zu deiner Portainer-Instanz (inkl. Protokoll). Kann später im Setup-UI überschrieben werden.
    PORTAINER_API_KEYAPI-Key für Portainer. Wird in der DB verschlüsselt abgelegt, sobald du ihn im Setup speicherst.
    PORTAINER_SERVER_NAMEOptionaler Anzeigename für den Server während des Setups.
    PORTAINER_API_SECRETÜberschreibt den Schlüssel, der zur Verschlüsselung des API-Keys verwendet wird.
    SUPERUSER_USERNAME, SUPERUSER_EMAIL, SUPERUSER_PASSWORDLegt einen Superuser automatisch beim Start an (falls nicht vorhanden).
    SELF_STACK_IDStack-ID von StackPulse selbst. Wird genutzt, um eigene Redeploys zu blockieren.
    AUTH_COOKIE_NAME, AUTH_SESSION_TTL_MS, AUTH_COOKIE_SECUREFeintuning für die Session-Verwaltung der API.
    SECURITY_PHRASE_SECRETSeed für die Generierung kryptografischer Sicherheitsphrasen.
    PORTAINER_SSH_SECRETSecret für SSH-Passwortverschlüsselung (Wartungs-Update).
    DISPLAYWird an Kindprozesse weitergereicht, wenn Portainer-Updates ausgelöst werden müssen (Default :9999).
    +

    Weitere Einstellungen (SSH-Config, Update-Skripte) verwaltest du später direkt im Maintenance-Bereich des UI.

    +

    Ersteinrichtung im UI

    +
      +
    1. Öffne das Frontend (/setup führt dich automatisch durch den Wizard).
      2. +
    2. Lege den Portainer-Server und den zugehörigen API-Key an – StackPulse testet die Verbindung per /api/setup/test-portainer.
      3. +
    3. Registriere einen Superuser oder verwende den per Umgebungsvariablen automatisch angelegten Account.
      4. +
    4. Nach erfolgreicher Einrichtung kannst du dich anmelden und erhältst Zugriff auf Dashboard, Logs, Benutzer & Wartung.
      5. +
    +

    Docker-Deployment

    +
    # docker-compose.yml (Auszug)
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "4001:4001"
+    volumes:
+      - stackpulse_data:/app/backend/data
+    restart: unless-stopped
+    environment:
+      - PORTAINER_URL=https://portainer.example.com
+      - PORTAINER_API_KEY=xxxx
+      - SUPERUSER_USERNAME=admin
+      - SUPERUSER_EMAIL=admin@example.com
+      - SUPERUSER_PASSWORD=changeme
+      - SELF_STACK_ID=123
+volumes:
+  stackpulse_data:
+
    +
      +
    1. docker compose up -d --build
      2. +
    2. Das Frontend ist anschließend unter Port 4001 (via Backend public/) erreichbar.
      3. +
    3. Datenbank & Einstellungen liegen im benannten Volume stackpulse_data.
      4. +
    +

    Datenbank & Migration

    +
      +
    • Datei: backend/data/stackpulse.db
      • +
    • Migration: npm run migrate (führt backend/db/ensure.js aus und erzeugt Schema, Rechte, Defaults)
      • +
    • Backup: Datei oder Volume regelmäßig sichern; enthält Benutzer, Logs und gespeicherte Secrets.
      • +
    +

    Damit bist du bereit für die tieferen Kapitel zu Architektur sowie Backend- und Frontend-Details.

    + + + + + + + + + + + + + +
    +
    + + + +
    + +
    + + + +
    +
    +
    +
    + + + + + + + + + + + + + \ No newline at end of file diff --git a/index.html b/index.html index 52fac0b..926f4c8 100644 --- a/index.html +++ b/index.html @@ -10,6 +10,8 @@ + + @@ -60,7 +62,7 @@
    - + Skip to content @@ -252,10 +254,10 @@
    @@ -308,10 +776,10 @@