Redflag/docs/3_BACKLOG/P0-005_Setup-Flow-Broken.md

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

// 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

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:

   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

# 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."