docs initial
This commit is contained in:
@@ -0,0 +1,41 @@
|
||||
# Benutzergruppen & Rechte
|
||||
|
||||
Dieser Bereich verwaltet Rollenmodelle und bestimmt, welche Aktionen Benutzer:innen durchführen dürfen. Du benötigst `user-groups-access` zum Lesen sowie `user-groups-edit`/`user-groups-delete` für Änderungen.
|
||||
|
||||
## Gruppen anlegen
|
||||
1. Button **Gruppe erstellen** wählen.
|
||||
2. Pflichtfelder:
|
||||
- **Name** (z. B. „Ops Team“)
|
||||
- **Beschreibung** (Hilfestellung für Kolleg:innen)
|
||||
3. Optional Tag-Farbe oder Icon setzen (für bessere Übersicht in der Benutzerliste).
|
||||
4. Speichern – die Gruppe erscheint sofort in der Übersicht.
|
||||
|
||||
## Gruppen bearbeiten
|
||||
- Zeile anklicken, um das Detailpanel zu öffnen.
|
||||
- Du kannst Name, Beschreibung und Zugehörige Benutzer (nur Anzeige) sehen.
|
||||
- Zum Bearbeiten der Rechte klicke auf **Berechtigungen bearbeiten**.
|
||||
|
||||
## Rechte vergeben
|
||||
Der Rechte-Dialog zeigt die gesamte Permissionstruktur in Kategorien (Stacks, Logs, Benutzer, Wartung etc.).
|
||||
|
||||
1. Wähle die gewünschte Kategorie aus.
|
||||
2. Setze für jede Permission einen Level:
|
||||
- **none** – kein Zugriff
|
||||
- **read** – Zugriff auf Ansicht/Lesen
|
||||
- **full** – volle Bearbeitungsrechte
|
||||
3. Abhängigkeiten werden automatisch hervorgehoben. Beispiel: Um `logs-delete` nutzen zu dürfen, muss `logs-access` mindestens `full` sein.
|
||||
4. Speichern bestätigt die Anpassungen. StackPulse aktualisiert sofort die effektiven Rechte aller Benutzer in dieser Gruppe.
|
||||
|
||||
## Benutzer zu Gruppen hinzufügen
|
||||
- Dies geschieht im Benutzer-Detailpanel (siehe [Benutzerverwaltung](users.md)).
|
||||
- Die Liste zeigt alle vorhandenen Gruppen; ein Benutzer kann mehreren Gruppen angehören.
|
||||
- Die effektiven Rechte sind die jeweils höchsten Levels aller Gruppen.
|
||||
|
||||
## Gruppen löschen
|
||||
- Nur möglich, wenn keine Benutzer ausschließlich von dieser Gruppe abhängen (es erfolgt ein Warnhinweis).
|
||||
- Löschen entfernt keine Benutzer, aber deren effektive Rechte können sich dadurch verringern.
|
||||
|
||||
## Best Practices
|
||||
- Erstelle zunächst eine Basisgruppe (z. B. „Viewer“) mit `read`-Rechten für Stacks und Logs.
|
||||
- Verwende separate Gruppen für sensible Aktionen wie Wartung oder Superuser-Verwaltung.
|
||||
- Nutze sprechende Beschreibungen, damit Kolleg:innen sofort erkennen, wofür eine Gruppe gedacht ist.
|
||||
@@ -0,0 +1,13 @@
|
||||
# Benutzerhandbuch
|
||||
|
||||
Dieses Kapitel beschreibt die Bedienung von StackPulse aus Sicht von Administrator:innen und Operators. Es orientiert sich an den Seiten im Dashboard und erklärt für jeden Bereich typische Abläufe sowie die notwendigen Berechtigungen. Screenshots kannst du später ergänzen; die Texte nennen bereits alle Buttons, Eingabefelder und Statusanzeigen.
|
||||
|
||||
**Reihenfolge**
|
||||
1. [Setup](setup.md) – richtet Portainer-Anbindung und Superuser ein.
|
||||
2. [Stacks](stacks.md) – zeigt alle Stacks, Redeploy-Aktionen und Filter.
|
||||
3. [Logs](logs.md) – Nachvollziehbarkeit, Filter & Export.
|
||||
4. [Wartung](maintenance.md) – Maintenance-Mode, Updates und SSH-Konfiguration.
|
||||
5. [Benutzer](users.md) – Konten verwalten, Phrasen ausgeben, Passwörter setzen.
|
||||
6. [Benutzergruppen & Rechte](groups.md) – Rollen modellieren und Berechtigungen zuweisen.
|
||||
|
||||
Jede Seite nennt die erforderlichen Permissions. Sobald du dich anmeldest, führt dich StackPulse zunächst automatisch durch den Setup-Assistenten; danach landet man auf der Stacks-Übersicht.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Logs-Seite
|
||||
|
||||
Die Logs-Seite dient der Nachvollziehbarkeit aller Aktionen (Redeploy, Login, Wartung, Benutzerverwaltung). Sie steht Benutzer:innen mit der Permission `logs-access` zur Verfügung.
|
||||
|
||||
## Überblick
|
||||
- Filterleiste mit Suchfeld, Zeitspanne, Kategorie und Status.
|
||||
- Tabelle mit Severity-Farben, Nachricht, Zeitstempel und Kontextinformationen.
|
||||
- Aktionen oberhalb der Tabelle: **Exportieren** und **Löschen**.
|
||||
|
||||
## Filtern
|
||||
1. **Zeitfenster:** Datumsfelder „Von“ und „Bis“ setzen. Standardmäßig zeigt StackPulse die letzten 24 Stunden.
|
||||
2. **Kategorie/Status:** Dropdowns nutzen, um z. B. `redeploy` oder `wartung` auszuwählen.
|
||||
3. **Freitext:** Suchfeld durchsucht `message`, `entity_name` und `metadata`.
|
||||
4. **Erweiterte Filter:** Klick auf „Weitere Filter“ öffnet zusätzliche Optionen (Actor, Stack-ID, Severity).
|
||||
|
||||
## Export
|
||||
- Button **CSV exportieren** klickst du erst, nachdem die Filter stehen. StackPulse erstellt eine CSV-Datei mit denselben Parametern.
|
||||
- Der Download startet im Browser; in containerisierten Umgebungen kannst du denselben Endpoint (`/api/logs/export`) auch automatisiert aufrufen.
|
||||
|
||||
## Löschen
|
||||
- Einzelne Logs: Papierkorb in der Zeile (Permission `logs-delete`).
|
||||
- Batch-Löschung: Button **Gefilterte Einträge löschen**; es erscheint ein Sicherheitsdialog mit Zusammenfassung der aktiven Filter.
|
||||
- Beachte, dass gelöschte Logs nicht wiederhergestellt werden können.
|
||||
|
||||
## Detailansicht
|
||||
- Klick auf eine Tabellenzeile, um ein Seitenpanel mit vollständigem JSON (`metadata`), Kontext (Stack, Benutzer, Quelle) und ggf. Redeploy-Timings zu öffnen.
|
||||
- Über **Stack öffnen** gelangst du direkt zur Stacks-Seite mit gesetztem Filter.
|
||||
@@ -0,0 +1,43 @@
|
||||
# Wartungsbereich
|
||||
|
||||
Der Wartungsbereich bündelt alle Funktionen rund um Maintenance-Mode, Serververwaltung, Update-Skripte und SSH-Verbindungen. Sichtbar für Benutzer:innen mit `maintenance-access` (Teilbereiche erfordern zusätzliche Unterrechte).
|
||||
|
||||
## Portainer-Status
|
||||
- Klick auf **Status prüfen**, um eine Live-Abfrage gegen Portainer durchzuführen. Ergebnis zeigt API-Verfügbarkeit, Endpoint-IDs und Auth-Status.
|
||||
- Häufige Fehler werden direkt erklärt (z. B. fehlender API-Key oder Netzwerkprobleme).
|
||||
|
||||
## Maintenance-Mode
|
||||
1. Schalter **Wartungsmodus aktivieren** toggeln.
|
||||
2. Optionale Nachricht eingeben (z. B. „Upgrade um 22:00 Uhr“); sie erscheint im gesamten UI als Banner.
|
||||
3. Aktivieren/Deaktivieren protokolliert automatisch Events in den Logs.
|
||||
|
||||
## Server & API-Key verwalten
|
||||
- Register „Server“ listet alle Portainer-Instanzen.
|
||||
- Über **Server hinzufügen** kannst du Name + URL ergänzen und anschließend API-Key speichern.
|
||||
- Buttons in der Tabelle:
|
||||
- **API-Key aktualisieren** – neues Token einsetzen.
|
||||
- **Server löschen** – nur möglich, wenn mindestens ein weiterer Server existiert oder du sofort neue Daten einträgst.
|
||||
|
||||
## Self-Stack ID
|
||||
- Feld „Eigener Stack“ akzeptiert die Stack-ID, in der StackPulse selbst läuft.
|
||||
- Nach dem Speichern sind Redeploy-Aktionen für diesen Stack im Dashboard deaktiviert.
|
||||
|
||||
## SSH-Konfiguration
|
||||
Erforderliche Permission: `maintenance-ssh-update`.
|
||||
1. Host, Port, Benutzername eintragen. Optional Passwort und zusätzliche SSH-Argumente (z. B. `-o StrictHostKeyChecking=no`).
|
||||
2. Passwort wird verschlüsselt gespeichert; alternativ kannst du Public-Key-Auth nutzen und das Feld leer lassen.
|
||||
3. **Verbindung testen**: StackPulse baut eine SSH-Verbindung auf und zeigt das Ergebnis in Echtzeit.
|
||||
|
||||
## Update-Skript
|
||||
- Standard-Skript wird angezeigt und kann als Ausgangspunkt genutzt werden.
|
||||
- Eigenes Skript: Inhalt in das Editorfeld kopieren und speichern. StackPulse prüft auf leere Zeilen und Basisbefehle.
|
||||
- Skript zurücksetzen entfernt die benutzerdefinierte Variante und stellt den Default wieder her.
|
||||
|
||||
## Portainer-Update auslösen
|
||||
1. Stelle sicher, dass Wartungsmodus aktiv ist und SSH-Konfiguration + Skript korrekt sind.
|
||||
2. Klicke auf **Update starten**. Der aktuelle Fortschritt erscheint in einem Logpanel.
|
||||
3. Der Button bleibt deaktiviert, solange ein Update läuft. Über **Status aktualisieren** kannst du den Fortschritt erneut abfragen.
|
||||
|
||||
## Fehlerbehandlung
|
||||
- Bei SSH-Fehlern zeigt StackPulse die genaue Ausgabe an. Passe Host/Port/Benutzer oder Skript an.
|
||||
- Falls das Update-Skript Probleme verursacht, kannst du es jederzeit stoppen, indem du Portainer manuell prüfst und ggf. das Skript anpasst.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Setup-Assistent
|
||||
|
||||
Beim ersten Start erscheint automatisch der Setup-Bereich. Du erreichst ihn später jederzeit über `/setup`, solange nicht alle Schritte abgeschlossen sind.
|
||||
|
||||
## Voraussetzungen
|
||||
- Portainer Business Edition mit gültigem API-Key
|
||||
- Superuser-Zugangsdaten (entweder schon per Umgebungsvariablen gesetzt oder über diesen Assistenten festlegen)
|
||||
|
||||
## Schritt 1: Portainer-Server anlegen
|
||||
1. Formularfelder **Server-URL** und optional **Name** ausfüllen.
|
||||
- URL inkl. Protokoll (z. B. `https://portainer.example.com`).
|
||||
- Bezeichnung dient ausschließlich als Anzeige im Dashboard.
|
||||
2. Auf **Verbindung testen** klicken.
|
||||
- Erfolgreich: grüner Hinweis, die Endpoints werden erkannt.
|
||||
- Fehlgeschlagen: Fehlermeldung prüfen (häufig Zertifikats-/Firewall-Themen).
|
||||
3. Mit **Speichern & Weiter** bestätigst du den Servereintrag. StackPulse legt ihn verschlüsselt in SQLite ab.
|
||||
|
||||
## Schritt 2: API-Key hinterlegen
|
||||
1. API-Key im Feld **Portainer API Key** einfügen.
|
||||
2. Optional kannst du über **Stacks laden** kontrollieren, ob Portainer Stacks zurückliefert.
|
||||
3. Mit **Speichern** wird der Schlüssel verschlüsselt gespeichert. Du kannst ihn später im Maintenance-Bereich austauschen.
|
||||
|
||||
## Schritt 3: Superuser registrieren
|
||||
1. Falls du `SUPERUSER_*` Variablen gesetzt hast, zeigt StackPulse an, dass bereits ein Superuser existiert – du kannst direkt weiter.
|
||||
2. Ansonsten Benutzername, E-Mail und Passwort vergeben. Das Passwort dient nur für diesen Account; weitere Benutzer folgen später.
|
||||
3. Auf **Superuser anlegen** klicken. Nach Erfolg wird der Login-Button eingeblendet.
|
||||
|
||||
## Abschluss & Login
|
||||
- Sobald alle drei Schritte abgeschlossen sind, erscheint die Schaltfläche **Zum Login**.
|
||||
- Melde dich mit dem Superuser an. StackPulse legt im Hintergrund initiale Berechtigungen, Default-Gruppen und Sicherheitspassphrasen an.
|
||||
|
||||
## Setup wiederholen oder ändern
|
||||
- Über das Dashboard → **Wartung** → Abschnitt *Serververwaltung* kannst du zusätzliche Portainer-Server hinzufügen oder entfernen.
|
||||
- Superuser lässt sich im Bereich **Benutzer** löschen, sofern du `maintenance-superuser-delete` besitzt.
|
||||
- Der Self-Stack (StackPulse-eigener Stack) kann in der Wartung gepflegt werden, damit er nicht versehentlich redeployed wird.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Stacks-Seite
|
||||
|
||||
Die Stacks-Ansicht ist der Startpunkt nach dem Login und liefert einen Überblick über alle Stacks der angebundenen Portainer-Instanz.
|
||||
|
||||
## Aufbau
|
||||
- **Header** mit Suchfeld, Filterchips für Status sowie Buttons für Redeploy-Aktionen.
|
||||
- **Tabelle** mit Name, Endpoint, Status, letzte Aktion, Redeploy-Status und verfügbaren Buttons.
|
||||
- **Live-Status**: Über Socket.IO wird jede Veränderung (queued/started/success/error) sofort eingeblendet.
|
||||
|
||||
## Filter & Suche
|
||||
1. Verwende das Suchfeld oben rechts, um nach Namen oder IDs zu filtern.
|
||||
2. Statuschips (z. B. „running“, „warning“) toggeln per Klick und lassen sich kombinieren.
|
||||
3. Über die Spaltenköpfe kannst du sortieren; ein erneuter Klick kehrt die Reihenfolge um.
|
||||
|
||||
## Redeploy-Aktionen
|
||||
| Aktion | Voraussetzung | Vorgehen |
|
||||
|--------|---------------|----------|
|
||||
| **Einzelner Stack** | Permission `stacks-redeploy-single` | Button **Redeploy** in der jeweiligen Zeile klicken und bestätigen. |
|
||||
| **Mehrere Stacks** | `stacks-redeploy-selection` | Checkboxen der gewünschten Stacks aktivieren, anschließend **Redeploy Auswahl**. |
|
||||
| **Alle Stacks** | `stacks-redeploy-all` | Button **Redeploy alle** auslösen. Nutze vorher Filter, um sicherzugehen, dass alle Stacks korrekt angezeigt werden. |
|
||||
|
||||
Während eines Redeploys erscheint pro Stack ein Fortschrittsbadge. Du kannst das Panel schließen; beim nächsten Besuch wird der aktuelle Status aus dem Backend gelesen.
|
||||
|
||||
## Redeploy-Status verstehen
|
||||
- **Queued** – Auftrag ist vorgemerkt.
|
||||
- **Started** – Portainer verarbeitet Redeploy.
|
||||
- **Success** – Vorgang erfolgreich abgeschlossen.
|
||||
- **Error** – Fehlerdetails findest du in der Logs-Seite.
|
||||
- **Info** – Informative Hinweise, etwa wenn Portainer einen Stack überspringt.
|
||||
|
||||
## Selbstschutz
|
||||
- Falls du die Variable `SELF_STACK_ID` gesetzt hast, markiert StackPulse den eigenen Stack als „geschützt“. Redeploy-Buttons werden deaktiviert und mit einem Info-Tooltip versehen.
|
||||
|
||||
## Troubleshooting aus der Ansicht
|
||||
- Klicke auf das Warnsymbol in der Tabellenzeile, um Fehlerdetails einzublenden.
|
||||
- Nutze den Link „Zu Logs springen“, der direkt eine gefilterte Ansicht in der Log-Seite öffnet (Stack-ID ist vorausgewählt).
|
||||
@@ -0,0 +1,39 @@
|
||||
# Benutzerverwaltung
|
||||
|
||||
Die Benutzerseite ermöglicht das Anlegen, Bearbeiten und Deaktivieren von Konten. Du benötigst mindestens die Permission `users-access` (lesen) bzw. `users-edit`/`users-delete` für Änderungen.
|
||||
|
||||
## Benutzer anlegen
|
||||
1. Button **Benutzer anlegen** klicken.
|
||||
2. Formularfelder ausfüllen:
|
||||
- Benutzername (eindeutig, wird für Login genutzt)
|
||||
- Anzeigename (optional)
|
||||
- E-Mail-Adresse
|
||||
- Passwort (kann später geändert werden)
|
||||
- Gruppen auswählen (siehe Abschnitt „Benutzergruppen“)
|
||||
3. Optional: Benutzer sofort aktivieren/deaktivieren.
|
||||
4. Mit **Speichern** bestätigen. Der Benutzer erscheint in der Tabelle und erhält automatisch eine Sicherheitspassphrase.
|
||||
|
||||
## Benutzer bearbeiten
|
||||
- In der Tabelle auf eine Zeile klicken, um das Detailpanel zu öffnen.
|
||||
- Du kannst Anzeigename, E-Mail, Passwort und Gruppen ändern.
|
||||
- Änderungen an Gruppen erfordern `users-edit` sowie Gruppenrechte (`user-groups-access`).
|
||||
|
||||
## Konto deaktivieren/reaktivieren
|
||||
- Toggle **Aktiv** im Detailpanel.
|
||||
- Deaktivierte Konten können sich nicht mehr anmelden, bleiben aber in der Historie.
|
||||
|
||||
## Sicherheitspassphrase
|
||||
1. Button **Sicherheitspassphrase anzeigen** im Detailpanel.
|
||||
2. StackPulse zeigt einen QR-Code und den alphanumerischen Code. Dieser wird nur einmal angezeigt, bis du bestätigst, dass er heruntergeladen wurde.
|
||||
3. Über **Neu generieren** kannst du eine neue Phrase erstellen (Permission `users-security-phrase`). Informiere den Benutzer über die neue Phrase und markiere anschließend „heruntergeladen“.
|
||||
|
||||
## Passwort zurücksetzen
|
||||
- Admins können direkt im Detailpanel ein neues Passwort setzen.
|
||||
- Benutzer:innen selbst nutzen die Auth-Seite „Passwort vergessen“: Sie geben Username + Sicherheitsphrase ein und definieren anschließend ein neues Passwort.
|
||||
|
||||
## Suche & Filter
|
||||
- Nutze das Suchfeld, um nach Benutzername oder E-Mail zu suchen.
|
||||
- Filterchips für Status (aktiv/inaktiv) erleichtern das Auffinden gesperrter Accounts.
|
||||
|
||||
## Massenaktionen
|
||||
- Mehrfachauswahl (Checkboxen) erlaubt das gleichzeitige Aktivieren/Deaktivieren oder Löschen mehrerer Benutzer. Vorsicht: Löschen entfernt auch Audit-Verweise.
|
||||
Reference in New Issue
Block a user