Add docs and project files - force for Culurien
This commit is contained in:
Fimeg
130
docs/3_BACKLOG/P0-005_Setup-Flow-Broken.md
Normal file
130
docs/3_BACKLOG/P0-005_Setup-Flow-Broken.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# P0-005: Setup Flow Broken - Critical Onboarding Issue
|
||||
|
||||
**Priority:** P0 (Critical)
|
||||
**Date Identified:** 2025-12-13
|
||||
**Status:** ACTIVE ISSUE - Breaking fresh installations
|
||||
|
||||
## Problem Description
|
||||
|
||||
Fresh RedFlag installations show the setup UI but all API calls fail with HTTP 502 Bad Gateway, preventing server configuration. Users cannot:
|
||||
1. Generate signing keys (required for v0.2.x security)
|
||||
2. Configure database settings
|
||||
3. Create the initial admin user
|
||||
4. Complete server setup
|
||||
|
||||
## Error Messages
|
||||
|
||||
```
|
||||
XHR GET http://localhost:3000/api/health [HTTP/1.1 502 Bad Gateway]
|
||||
XHR POST http://localhost:3000/api/setup/generate-keys [HTTP/1.1 502 Bad Gateway]
|
||||
```
|
||||
|
||||
## Root Cause Analysis
|
||||
|
||||
### Issue 1: Auto-Created Admin User
|
||||
**Location**: `aggregator-server/cmd/server/main.go:170`
|
||||
|
||||
```go
|
||||
// Always creates admin user on startup - prevents setup detection
|
||||
userQueries.EnsureAdminUser(cfg.Admin.Username, cfg.Admin.Username+"@redflag.local", cfg.Admin.Password)
|
||||
```
|
||||
|
||||
**Problem**:
|
||||
- Admin user is created automatically from config before any UI is shown
|
||||
- Setup page can't detect "no users exist" state
|
||||
- User never gets redirected to proper setup flow
|
||||
- Default credentials (if any) are unknown to user
|
||||
|
||||
### Issue 2: 502 Bad Gateway Errors
|
||||
**Possible Causes**:
|
||||
|
||||
1. **Database Not Ready**: Setup endpoints may need database, but it's not initialized
|
||||
2. **Missing Error Handling**: Setup handlers might panic or return errors
|
||||
3. **CORS/Port Issues**: Frontend on :3000 calling backend on :8080 may be blocked
|
||||
4. **Incomplete Configuration**: Setup routes may depend on config that isn't loaded
|
||||
|
||||
**Location**: `aggregator-server/cmd/server/main.go:73`
|
||||
```go
|
||||
router.POST("/api/setup/generate-keys", setupHandler.GenerateSigningKeys)
|
||||
```
|
||||
|
||||
### Issue 3: Setup vs Login Flow Confusion
|
||||
**Current Behavior**:
|
||||
1. User builds and starts RedFlag
|
||||
2. Auto-created admin user exists (from .env or defaults)
|
||||
3. User sees setup page but doesn't know credentials
|
||||
4. API calls fail (502 errors)
|
||||
5. User stuck - can't login, can't configure
|
||||
|
||||
**Expected Behavior**:
|
||||
1. Detect if no admin users exist
|
||||
2. If no users: Force setup flow, create first admin
|
||||
3. If users exist: Show login page
|
||||
4. Setup should work even without full config
|
||||
|
||||
## Reproduction Steps
|
||||
|
||||
1. Fresh clone/installation:
|
||||
```bash
|
||||
git clone <redflag-repo>
|
||||
cd RedFlag
|
||||
docker compose build
|
||||
docker compose up
|
||||
```
|
||||
|
||||
2. Navigate to http://localhost:8080 (or :3000 depending on config)
|
||||
|
||||
3. **OBSERVED**: Shows setup page
|
||||
|
||||
4. Click "Generate Keys" or try to configure
|
||||
|
||||
5. **OBSERVED**: 502 Bad Gateway errors in browser console
|
||||
|
||||
6. **RESULT**: Cannot complete setup, no way to login
|
||||
|
||||
## Impact
|
||||
|
||||
- **Critical**: New users cannot install/configure RedFlag
|
||||
- **Security**: Can't generate signing keys (breaks v0.2.x security)
|
||||
- **UX**: Confusing flow (setup vs login)
|
||||
- **Onboarding**: Complete blocker for adoption
|
||||
|
||||
## Files to Investigate
|
||||
|
||||
- `aggregator-server/cmd/server/main.go:73` - Setup route mounting
|
||||
- `aggregator-server/cmd/server/main.go:170` - Auto-create admin user
|
||||
- `aggregator-server/internal/api/handlers/setup.go` - Setup handlers
|
||||
- `aggregator-server/internal/services/signing.go` - Key generation logic
|
||||
- `docker-compose.yml` - Port mapping issues
|
||||
|
||||
## Quick Test
|
||||
|
||||
```bash
|
||||
# Check if setup endpoint responds
|
||||
curl -v http://localhost:8080/api/setup/generate-keys
|
||||
|
||||
# Expected: Either keys or error message
|
||||
# Observed: 502 Bad Gateway
|
||||
|
||||
# Check server logs
|
||||
docker-compose logs server | grep -A5 -B5 "generate-keys\|502\|error"
|
||||
```
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] Setup page detects "no admin users" state correctly
|
||||
- [ ] Setup API endpoints return meaningful responses (not 502)
|
||||
- [ ] User can generate signing keys via setup UI
|
||||
- [ ] User can configure database via setup UI
|
||||
- [ ] First admin user created via setup (not auto-created)
|
||||
- [ ] After setup: User redirected to login with known credentials
|
||||
|
||||
## Temporary Workaround
|
||||
|
||||
Until fixed, users must:
|
||||
1. Check `.env` file for any default admin credentials
|
||||
2. If none, check server startup logs for auto-created user
|
||||
3. Manually configure signing keys (if possible)
|
||||
4. Skip setup UI entirely
|
||||
|
||||
**This is not acceptable for production."
|
||||
Reference in New Issue
Block a user