131 lines
4.1 KiB
Markdown
131 lines
4.1 KiB
Markdown
# 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."
|