Setup Wizard Walkthrough
First-run setup wizard for initializing Beep.AI.Server
Overview
On first launch, Beep.AI.Server presents a Setup Wizard that guides you through:
- Database initialization and configuration
- Admin account creation
- Authentication mode selection (Local, OAuth2, LDAP, Azure AD)
- Hardware detection and model recommendations
- Optional Redis and Celery configuration
Wizard Routes
| Route | Purpose |
|---|---|
/setup | Initial setup and configuration pages |
/wizard | First-run scenario wizard (pick scenario, guided steps) |
/wizard/api | Wizard JSON API (step state, validation, completion) |
/admin/scenario | Cross-scenario reset and upgrade controls (admin only) |
/voice-bot | Voice bot configuration wizard |
Note
The /setup routes are publicly accessible (no auth required) so the wizard can run before any admin account exists. All other routes redirect to /setup until the wizard is complete.
Wizard State Machine
The wizard tracks progress using the WizardState model with step-by-step completion tracking:
- Step 1: Environment check and prerequisites
- Step 2: Database configuration
- Step 3: Admin account creation
- Step 4: Authentication method selection
- Step 5: Hardware detection
- Step 6: Optional services (Redis, Celery)
- Step 7: Review and finalize
Warning
The setup enforcer middleware runs on every request. If configuration is reset or database is missing, all users are redirected back to /setup. The /admin/scenario routes allow administrators to reset or upgrade scenarios post-setup.
After Setup
Once the wizard completes:
- The admin dashboard becomes available at
/admin - AI services show overview pages with environment setup
- Service bootstrap starts (lazy initialization of LLM, RAG, Agents, etc.)
- API endpoints under
/v1/*become available with Bearer token auth