-
Notifications
You must be signed in to change notification settings - Fork 0
Plans completed PLAN setup flow redesign
Den Setup-Wizard in zwei Phasen aufteilen: eine kurze, zeitlimitierte Admin-Erstellung mit Auto-Login (Phase 1) und ein zeitloses, authentifiziertes Onboarding über eine Dashboard-Checklist (Phase 2). Damit wird der Zeitdruck bei der Ersteinrichtung eliminiert und gleichzeitig die Architektur für künftige Auth-Methoden (OAuth, Portal) vorbereitet.
/wizard (unauthentifiziert, 5-Min-Timeout für ALLES)
Step 1: Admin (Username + Password) ~10s
Step 2: Organization (ID + Name) ~10s
Step 3: Environment (Socket Path) ~10s [optional]
Step 4: Stack Sources (Catalog Selection) ~15s [optional]
Step 5: Container Registries (v2 API Flow) 30s–3min [optional]
Step 6: Complete Setup ~5s
Probleme:
- 5-Minuten-Timeout für den gesamten Flow, obwohl nur Step 1 sicherheitsrelevant ist
- Timer startet bei Container-Start, nicht bei erstem Zugriff
- Registry-Prüfungen (Step 5) können allein mehrere Minuten dauern
- Bei Timeout: Alles verloren, kompletter Neustart (Container restart)
- Organization-Erstellung ist an Admin-Erstellung gekoppelt (verhindert OAuth/Portal)
PHASE 1: /wizard (unauthentifiziert, 5-Min-Timeout)
Admin erstellen → Auto-Login (JWT im Response)
PHASE 2: /dashboard (authentifiziert, KEIN Timeout)
Onboarding-Checklist:
☐ Organization einrichten ← Pflicht, blockt andere Items
☐ Docker Environment einrichten ← Optional
☐ Stack Sources hinzufügen ← Optional
☐ Container Registries prüfen ← Optional
[Einrichtung abschließen] oder [Später erledigen]
| Komponente | Pfad | Nutzen |
|---|---|---|
| LoginEndpoint (JWT-Generierung) | Api/Endpoints/Auth/LoginEndpoint.cs |
Response-Shape als Vorbild für Auto-Login |
| TokenService | Infrastructure.Security/Authentication/TokenService.cs |
JWT-Generierung für Auto-Login |
| AuthContext | WebUi/src/context/AuthContext.tsx |
Token-Storage in localStorage |
| Dashboard Error Banner | WebUi/src/pages/Dashboard.tsx:49-53 |
UI-Pattern für Onboarding-Banner |
| WizardGuard | WebUi/src/components/wizard/WizardGuard.tsx |
Redirect-Logik anpassen |
| Settings-Seiten | WebUi/src/pages/Settings/ |
Environment, Sources, Registries bereits vorhanden |
| OrganizationProvisioningService | Application/Services/OrganizationProvisioningService.cs |
Org-Erstellung + Role-Assignment |
| WizardTimeoutService | Infrastructure/Configuration/WizardTimeoutService.cs |
Timeout-Logik anpassen |
Reihenfolge basierend auf Abhängigkeiten:
-
Feature 1: Auto-Login nach Admin-Erstellung – CreateAdminEndpoint gibt JWT zurück, Frontend loggt automatisch ein (PR #106)
- Betroffene Dateien:
-
Api/Endpoints/Wizard/CreateAdminEndpoint.cs(Response erweitern) -
Application/UseCases/Wizard/CreateAdmin/CreateAdminHandler.cs(Token generieren) -
WebUi/src/api/wizard.ts(Response-Typ anpassen) -
WebUi/src/pages/Wizard/AdminStep.tsx(Auto-Login nach Erstellung) -
WebUi/src/context/AuthContext.tsx(setAuthFromToken-Methode)
-
- Abhängig von: –
- Betroffene Dateien:
-
Feature 2: Wizard auf Phase 1 reduzieren – Nur noch Admin-Erstellung, dann Redirect zum Dashboard (PR #108)
- Betroffene Dateien:
-
WebUi/src/pages/Wizard/index.tsx(1 Step statt 6, Redirect nach Login) -
WebUi/src/pages/Wizard/WizardLayout.tsx(vereinfachtes Layout, kein Stepper) -
WebUi/src/components/wizard/WizardGuard.tsx(Logik anpassen)
-
- Entscheidung: Alte Steps (Org, Env, Sources, Registries) bleiben als Dateien erhalten, werden aber nicht mehr im Wizard verwendet — Settings-Seiten übernehmen
- Abhängig von: Feature 1
- Betroffene Dateien:
-
Feature 3: Onboarding-Status API – Neuer Endpoint für den Einrichtungsstatus (PR #109)
- Neue Dateien:
Application/UseCases/Onboarding/GetOnboardingStatus/GetOnboardingStatusQuery.csApplication/UseCases/Onboarding/GetOnboardingStatus/GetOnboardingStatusHandler.csApi/Endpoints/Onboarding/GetOnboardingStatusEndpoint.cs
- Response:
interface OnboardingStatus { isComplete: boolean; // Alle Pflicht-Items erledigt isDismissed: boolean; // User hat Checklist geschlossen items: { organization: { done: boolean; name?: string }; environment: { done: boolean; count: number }; stackSources: { done: boolean; count: number }; registries: { done: boolean; count: number }; }; }
- Handler prüft: Org vorhanden? Environments vorhanden? Sources vorhanden? Registries vorhanden?
- Abhängig von: –
- Neue Dateien:
-
Feature 4: Onboarding-Checklist UI – Dashboard-Komponente mit Setup-Fortschritt (PR #110)
- Neue Dateien:
WebUi/src/components/onboarding/OnboardingChecklist.tsxWebUi/src/api/onboarding.ts
- Geänderte Dateien:
-
WebUi/src/pages/Dashboard.tsx(Checklist einbinden)
-
- Design:
- Amber/Blue-Banner oben im Dashboard (nicht modal, nicht blockierend)
- Checklist-Items mit Status-Icons (✓ erledigt, → einrichten)
- Organization als erstes Item, muss erledigt sein bevor andere aktiv werden
- Jedes Item verlinkt zur entsprechenden Settings-Seite
- "Einrichtung abschließen"-Button → markiert Onboarding als complete
- "Später erledigen"-Button → dismisst die Checklist (localStorage + API)
- Abhängig von: Feature 3
- Neue Dateien:
-
Feature 5: Organization-Erstellung aus Dashboard – Org-Setup als eigenständigen Flow (PR #111)
- Neue Dateien:
-
WebUi/src/pages/Settings/Organization/SetupOrganization.tsx(oder Modal) -
Api/Endpoints/Organization/CreateOrganizationEndpoint.cs(authentifiziert)
-
- Betroffene Dateien:
-
WebUi/src/components/onboarding/OnboardingChecklist.tsx(Link zu Org-Setup)
-
- Entscheidung: Einfaches Formular (Name + ID), nutzt bestehenden
OrganizationProvisioningService - Wichtig: Endpoint ist authentifiziert (JWT), nicht AllowAnonymous
- Abhängig von: Feature 3
- Neue Dateien:
-
Feature 6: Timeout-Scope einschränken – Timeout gilt nur noch für Phase 1 (PR #112)
- Betroffene Dateien:
-
Api/Endpoints/Wizard/WizardTimeoutPreProcessor.cs(nur noch für CreateAdmin) -
Infrastructure/Configuration/WizardTimeoutService.cs(ggf. vereinfachen) -
Application/UseCases/Wizard/GetWizardStatus/GetWizardStatusHandler.cs(States anpassen)
-
- Wizard-States werden vereinfacht:
-
NotStarted→ Kein Admin vorhanden -
Installed→ Admin vorhanden (Wizard abgeschlossen) -
AdminCreatedundOrganizationSetentfallen (Onboarding übernimmt)
-
- Abhängig von: Feature 2
- Betroffene Dateien:
-
Feature 7: Dismiss-Endpoint + Cleanup – Onboarding-Dismiss persistieren, alte Wizard-Steps bereinigen (PR #113)
- Neue Dateien:
Api/Endpoints/Onboarding/DismissOnboardingEndpoint.cs
- Betroffene Dateien:
-
Infrastructure/Configuration/SystemConfig.cs(OnboardingDismissed Flag)
-
- Alte Wizard-Endpoints die unangetastet bleiben (abwärtskompatibel für API/E2E):
- SetOrganization, SetEnvironment, SetSources, SetRegistries, Install
- Diese werden weiterhin funktionieren, sind aber nicht mehr Teil des UI-Wizard
- Abhängig von: Feature 4
- Neue Dateien:
-
Tests – Unit + E2E
- Abhängig von: Feature 1-7
-
Dokumentation:
/document-featurefür neue Flows – E2E-Tests, Screenshots und Anleitungen- Abhängig von: Tests
- Details: Siehe Abschnitt "Dokumentationsplan" unten
- Ergebnis: wizard.spec.ts komplett neugeschrieben (8 Tests), 3 Screenshots generiert, initial-setup.md DE+EN neugeschrieben
-
Dokumentation: Bestehende Docs aktualisieren – Referenzen auf alten Wizard-Flow korrigieren
- Abhängig von:
/document-feature - Ergebnis: quickstart.md, installation/index.mdx in DE+EN aktualisiert
- Abhängig von:
-
Phase abschließen – Alle Tests grün, PR gegen main
- Abhängig von: alle
Backend:
CreateAdminEndpoint Response erweitern:
public class CreateAdminResponse
{
public bool Success { get; init; }
public string? Message { get; init; }
// NEU: Auto-Login-Daten
public string? Token { get; init; }
public string? Username { get; init; }
public string? Role { get; init; }
}CreateAdminHandler: Nach erfolgreicher User-Erstellung den TokenService aufrufen:
// Nach: await _userRepository.AddAsync(user, ct);
var token = _tokenService.GenerateToken(user);
return new CreateAdminResult(
Success: true,
Message: "Admin user created successfully",
Token: token,
Username: user.Username,
Role: "admin");Frontend:
AuthContext erweitern um setAuthDirectly(token, user):
// Neue Methode in AuthContext
const setAuthDirectly = (token: string, user: { username: string; role: string }) => {
localStorage.setItem('auth_token', token);
localStorage.setItem('auth_user', JSON.stringify(user));
setToken(token);
setUser(user);
};AdminStep nach erfolgreicher Erstellung:
const response = await createAdmin({ username, password });
if (response.success && response.token) {
setAuthDirectly(response.token, {
username: response.username!,
role: response.role!,
});
// Redirect zum Dashboard (mit Onboarding-Checklist)
navigate('/dashboard');
}Wizard index.tsx:
// Statt 6 Steps: Nur noch Admin-Erstellung
// Wenn wizardState === 'Installed' → redirect /login
// Wenn wizardState === 'NotStarted' → AdminStep anzeigen
// Nach Admin-Erstellung → Auto-Login → redirect /dashboardWizardLayout:
- Kein Stepper mehr (nur noch 1 Step)
- Titel: "Welcome to ReadyStackGo"
- Untertitel: "Create your admin account to get started"
- Countdown-Timer bleibt (für den einen Step)
WizardGuard:
- Prüft nur noch: Ist ein Admin vorhanden?
- Wenn nein → /wizard
- Wenn ja → Dashboard passieren lassen
Handler-Logik:
public async Task<OnboardingStatus> Handle(GetOnboardingStatusQuery query, CancellationToken ct)
{
var hasOrg = await _orgRepository.GetAllAsync(ct) is { Count: > 0 };
var org = hasOrg ? (await _orgRepository.GetAllAsync(ct)).First() : null;
var envCount = hasOrg ? await _environmentRepository.CountAsync(ct) : 0;
var sourceCount = await _stackSourceRepository.CountAsync(ct);
var registryCount = await _registryRepository.CountAsync(ct);
var isDismissed = await _systemConfigService.GetValueAsync("OnboardingDismissed", ct) == "true";
return new OnboardingStatus
{
IsComplete = hasOrg, // Org ist das einzige Pflicht-Item
IsDismissed = isDismissed,
Items = new OnboardingItems
{
Organization = new(hasOrg, org?.Name),
Environment = new(envCount > 0, envCount),
StackSources = new(sourceCount > 0, sourceCount),
Registries = new(registryCount > 0, registryCount)
}
};
}Design-Konzept:
┌─────────────────────────────────────────────────────────┐
│ 🔧 Complete Your Setup [Dismiss ✕] │
│ │
│ ✓ Admin account created │
│ → Set up your organization [Configure →] │
│ ○ Add a Docker environment (requires org) │
│ ○ Configure stack sources (requires org) │
│ ○ Set up container registries (optional) │
│ │
│ [Complete Setup] │
└─────────────────────────────────────────────────────────┘
- Amber-Border solange Org fehlt, Blue-Border wenn nur optionale Items offen
- Items ohne Org sind ausgegraut mit "(requires organization)" Hinweis
- Erledigte Items zeigen grünen Haken + Zusammenfassung (z.B. "2 environments configured")
- "Configure →" Button führt zur jeweiligen Settings-Seite
- "Complete Setup" Button ruft Dismiss-Endpoint auf und blendet Banner aus
- "Dismiss ✕" speichert in localStorage UND API (überlebt Browser-Wechsel)
Neuer authentifizierter Endpoint:
POST /api/organizations
Body: { id: string, name: string }
Response: { success: boolean, organizationId: string }
Auth: JWT (RequirePermission: not needed, admin check sufficient)
Nutzt bestehenden OrganizationProvisioningService.ProvisionOrganization().
UI: Einfaches Inline-Formular oder Modal, das aus der Onboarding-Checklist geöffnet wird. Felder: Organization Name (Pflicht), Organization ID (auto-generated aus Name, editierbar).
Vereinfachte Wizard-States:
| Alt | Neu | Bedeutung |
|---|---|---|
| NotStarted | NotStarted | Kein Admin, Wizard nötig |
| AdminCreated | — | |
| OrganizationSet | — | |
| Installed | Installed | Admin existiert, Wizard abgeschlossen |
GetWizardStatusHandler:
// Vereinfacht:
// 1. Timeout gelockt? → NotStarted
// 2. Admin existiert? → Installed
// 3. Sonst → NotStartedWizardTimeoutPreProcessor:
- Bleibt auf CreateAdminEndpoint
- Wird von allen anderen Wizard-Endpoints entfernt (die werden entweder authentifiziert oder bleiben als Legacy-API)
- Sollen die alten Wizard-Endpoints (SetOrganization, SetEnvironment, etc.) erhalten bleiben? → Ja, für API-Kompatibilität und E2E-Tests, aber nicht mehr im UI-Wizard
- Soll die Org-Erstellung ein Modal oder eine eigene Seite sein? → Klären in Feature 5
- Timeout-Dauer anpassen? 5 Min für nur Admin-Erstellung ist großzügig genug
| Entscheidung | Optionen | Gewählt | Begründung |
|---|---|---|---|
| Phase-1-Scope | A) Admin+Org B) Nur Admin | B) Nur Admin | Ermöglicht künftige OAuth/Portal-Integration. Org gehört zur Konfiguration, nicht zur Authentifizierung. |
| Auto-Login | A) Redirect zu /login B) JWT im Response | B) JWT im Response | Kein zusätzlicher Klick, nahtloser Übergang. Gleiche Token-Logik wie LoginEndpoint. |
| Onboarding-UI | A) Eigene Seite B) Dashboard-Banner C) Modal | B) Dashboard-Banner | Nicht-blockierend, User sieht sofort das Dashboard. Banner ist prominent aber nicht aufdringlich. |
| Org-Pflicht | A) Alles optional B) Org Pflicht | B) Org Pflicht | Environments, Sources, Registries brauchen eine Org. Ohne Org ist nichts konfigurierbar. |
| Alte Wizard-Endpoints | A) Entfernen B) Behalten C) Deprecaten | B) Behalten | Abwärtskompatibilität für API-User und E2E-Tests. Kein Breaking Change. |
| Timeout nach Admin | A) Timeout läuft weiter B) Timeout wird gelöscht | B) Timeout wird gelöscht | Nach Admin-Erstellung ist die Instanz "claimed". Timeout hat seinen Zweck erfüllt. |
Diese Architektur ermöglicht direkt:
| Szenario | Phase 1 wird zu | Phase 2 ändert sich |
|---|---|---|
| OAuth (GitHub, Google) | "Sign in with X" Button → erster User wird Admin | Unverändert |
| Zentrales Portal | "Authenticate with Portal" → Admin + Org wird vom Portal geliefert | Org-Item entfällt aus Checklist |
| Distribution (v0.27) |
ISetupWizardDefinitionProvider liefert Auth-Methode |
IOnboardingDefinitionProvider liefert Checklist-Items |
| Multi-Tenant | Portal-Auth → Org-Auswahl statt Org-Erstellung | Checklist pro Org |
Folgende Features erhalten eine vollständige Dokumentation via /document-feature:
Bisherige Docs (initial-setup.md DE/EN) beschreiben 4 Wizard-Steps. Komplett neu schreiben:
-
E2E-Test:
e2e/wizard-setup.spec.ts(ersetzt bestehende Wizard-Tests falls vorhanden)- Test: Wizard-Seite öffnen → Admin-Formular sichtbar
- Test: Admin erstellen → Auto-Login → Redirect zum Dashboard
- Test: Timeout-Verhalten (optional, schwer zu testen)
-
Screenshots (neu):
-
setup-01-welcome.png— Wizard-Seite mit Admin-Formular -
setup-02-admin-created.png— Erfolg + Auto-Login-Redirect
-
-
Screenshots (zu ersetzen/entfernen):
-
initial-setup-01-admin.png→ ersetzt durchsetup-01-welcome.png -
initial-setup-02-organization.png→ entfällt (Org jetzt im Onboarding) -
initial-setup-03-environment.png→ entfällt (Env jetzt in Settings) -
initial-setup-04-complete.png→ entfällt
-
-
Docs (Rewrite):
-
en/getting-started/initial-setup.md— komplett neu: "Create Admin → Auto-Login → Dashboard" -
de/getting-started/initial-setup.md— deutsche Version
-
Komplett neue Dokumentation für das Dashboard-Onboarding:
-
E2E-Test:
e2e/onboarding-checklist.spec.ts- Test: Checklist erscheint nach erstem Login
- Test: Organisation erstellen → Item wird grün
- Test: Environment einrichten → Item wird grün
- Test: "Einrichtung abschließen" → Banner verschwindet
- Test: "Dismiss" → Banner verschwindet, erscheint nicht mehr
-
Screenshots (neu):
-
onboarding-01-checklist.png— Dashboard mit Onboarding-Banner (alle Items offen) -
onboarding-02-org-setup.png— Org-Erstellung (Modal oder Formular) -
onboarding-03-partial.png— Teilweise erledigte Items -
onboarding-04-complete.png— Alle Items erledigt
-
-
Docs (neu):
-
en/docs/onboarding.md— Schritt-für-Schritt: Org → Env → Sources → Registries -
de/docs/onboarding.md— deutsche Version
-
Dateien die nicht via /document-feature abgedeckt werden, aber Wizard-Referenzen enthalten:
| Datei | Änderung |
|---|---|
en/introduction.mdx |
"Complete the Setup Wizard" → "Create your admin account" + "Complete the onboarding checklist" |
de/introduction.mdx |
"Setup Wizard durchlaufen" → "Admin-Konto erstellen" + "Onboarding-Checklist abschließen" |
en/index.mdx |
Link-Card "Initial Setup" Description anpassen |
de/index.mdx |
Link-Card "Ersteinrichtung" Description anpassen |
en/getting-started/quickstart.md |
"Initial Setup" Verweis aktualisieren |
de/getting-started/quickstart.md |
"Ersteinrichtung" Verweis aktualisieren |
en/getting-started/first-deployment.md |
Prerequisite "Setup wizard completed" → "Admin created and organization configured" |
de/getting-started/first-deployment.md |
Prerequisite "Setup-Wizard abgeschlossen" → "Admin erstellt und Organisation eingerichtet" |
en/getting-started/installation/index.mdx |
"Configure admin account and organization in the setup wizard" → neuer Text |
de/getting-started/installation/index.mdx |
Analog aktualisieren |
| Datei | Änderung |
|---|---|
en/docs/wizard-registries.md |
"fifth step of the Setup Wizard" → Referenz auf Settings/Onboarding. Wizard-Navigation entfällt, nur noch Settings-Kontext |
de/docs/wizard-registries.md |
Analog: "fünfter Schritt" → Settings-basierte Dokumentation |
en/docs/stack-sources.md |
Wizard-Step-4-Abschnitt entfernen oder umschreiben auf Onboarding/Settings |
de/docs/stack-sources.md |
Analog aktualisieren |
en/docs/index.md |
Wizard-Referenz in Stack-Sources-Beschreibung entfernen |
de/docs/index.md |
Analog aktualisieren |
| Datei | Änderung |
|---|---|
docs/Setup-Wizard/Wizard-Flow.md |
State-Machine aktualisieren: 4 States → 2 States, Flow-Diagramm anpassen, Endpoints-Liste aktualisieren |
docs/Security/Initial-Setup.md |
Security-Modell anpassen: Timeout nur für Admin-Erstellung, Onboarding ist authentifiziert |
docs/Home.md |
"Setup Wizard" Feature-Beschreibung aktualisieren |
docs/Getting-Started/Overview.md |
"guided setup wizard" → "admin creation + guided onboarding" |
docs/Getting-Started/Installation.md |
Wizard-Flow-Beschreibung aktualisieren |
docs/Getting-Started/Quick-Start.md |
Wizard-Referenzen anpassen |
Diese Dateien enthalten historische oder kontextuelle Wizard-Referenzen. Nur aktualisieren wenn die Referenz irreführend wird:
-
docs/Architecture/Overview.md— Wizard als Komponente -
docs/Architecture/Container-Lifecycle.md— Container-Init + Wizard -
docs/Configuration/Config-Files.md— Wizard-State-Config -
docs/Reference/Technical-Specification.md— Wizard-Details -
docs/Reference/Full-Specification.md— Wizard-Spec -
docs/Reference/Multi-Environment.md— Environment Setup im Wizard-Kontext -
docs/Security/Overview.md— Initial-Setup-Flow - Versions-Referenzen (
v0.6-sqlite-multiuser.md,v0.14-stack-upgrade.md,v0.16-state-machine-refactoring.md) — historisch, kein Update nötig
| Screenshot | Quelle |
|---|---|
setup-01-welcome.png |
A1: Wizard-Setup E2E |
setup-02-admin-created.png |
A1: Wizard-Setup E2E |
onboarding-01-checklist.png |
A2: Onboarding E2E |
onboarding-02-org-setup.png |
A2: Onboarding E2E |
onboarding-03-partial.png |
A2: Onboarding E2E |
onboarding-04-complete.png |
A2: Onboarding E2E |
| Screenshot | Grund |
|---|---|
initial-setup-01-admin.png |
Ersetzt durch setup-01-welcome.png
|
initial-setup-02-organization.png |
Org-Erstellung jetzt im Onboarding |
initial-setup-03-environment.png |
Environment jetzt in Settings |
initial-setup-04-complete.png |
"Complete Setup" Step entfällt |
Wizard-Registries-Screenshots (wizard-reg-01 bis wizard-reg-07) bleiben erhalten, da die Registry-Konfiguration weiterhin über Settings zugänglich ist. Die Docs werden aber umformuliert (von "Wizard Step 5" zu "Settings-basiert / Onboarding-verlinkt").
1. Features 1-7 implementieren + Tests
2. /document-feature A1 (Setup Wizard Rewrite)
3. /document-feature A2 (Onboarding Checklist)
4. Phase B1 (Kritische PublicWeb-Updates)
5. Phase B2 (Kontext-Anpassungen PublicWeb)
6. Phase B3 (Interne Docs)
7. Phase C (Screenshot-Cleanup)
8. PublicWeb Build prüfen (`npm run build`)
Getting Started
Architecture
Configuration
Security
Setup Wizard
Development
Operations
CI/CD
Reference
- Roadmap
- API Reference
- Configuration Reference
- Manifest Schema
- Multi-Environment
- Stack Sources
- Plugin System
- Technical Specification
- Full Specification
Specifications
Release Notes