Deep Dive

10-Step Setup Wizard: Enterprise AI Platform, Running in Under an Hour

Database, VectorDB, LLM, SSO, Git, Confluence, users, license, and security — all configured through a guided wizard. No YAML required.

What Are the 10 Steps in the FlowSquad Setup Wizard?

The Setup Wizard launches automatically on first boot when no valid configuration is detected. It is also accessible post-deployment from Admin → System → Re-run Wizard for reconfiguration. Each step includes a "Test Connection" or "Validate" action that confirms the configuration is correct before allowing progression to the next step — preventing partial configurations that cause cryptic startup failures.

• 1
  License Activation

  Enter the FlowSquad license key to activate the instance tier (Community, Professional, Enterprise). License validation is performed offline via signature verification — no outbound internet call required. Determines feature limits (max products, max users, air-gap mode).

• 2
  Database Configuration

  Configure the primary application database: PostgreSQL (recommended for production), MySQL/MariaDB, or SQLite (development only). Enter host, port, database name, username, and password. "Test Connection" runs a schema compatibility check and reports missing migrations.

• 3
  VectorDB Configuration

  Select ChromaDB (local HTTP server, recommended for air-gapped) or Pinecone (managed cloud). For ChromaDB, enter the host:port. For Pinecone, enter the API key and environment. "Test Connection" verifies collection creation permissions and returns the current index size.

• 4
  LLM Provider Configuration

  Select from OpenAI, Anthropic, Azure OpenAI, or Ollama. Enter the API key (or base URL for Ollama). Select the default model and configure temperature and max token limits. "Test Connection" sends a 10-token test prompt to confirm the provider responds correctly.

• 5
  Embedding Model Configuration

  Configure the ONNX embedding model path (defaults to bundled all-MiniLM-L6-v2) or point to a custom ONNX model file. Validates model input/output tensor shapes against FlowSquad's expected 384-dim interface.

• 6
  SSO / Authentication Configuration

  Enable SAML 2.0 SSO by uploading the IdP metadata XML (Okta, Azure AD, Ping, etc.) and configuring the SP entity ID and ACS URL. Or configure local authentication with password policy settings. MFA (TOTP) enforcement is toggled here.

• 7
  Git Provider Integration

  Connect GitHub, GitLab, Bitbucket, or Azure DevOps. Enter the OAuth app credentials or Personal Access Token. Configure webhook registration for push events (enables incremental re-indexing). Select the default repository visibility for new products.

• 8
  Jira & Confluence Integration

  Enter the Jira/Confluence base URL, username, and API token. Configure the default Jira project key for new products and the Confluence space key for documentation export. "Test Connection" verifies write permissions to both systems.

• 9
  User Provisioning

  Create the initial Global Admin account. Optionally import users from the connected SSO directory. Configure RBAC group-to-role mappings for SSO users. Set session timeout and password rotation policies for local auth users.

• 10
  Security & Audit Configuration

  Set the Fernet encryption key for field-level encryption (or generate a new one). Configure audit log retention period (default 90 days). Enable IP allowlisting for Admin panel access. Review and accept the security checklist before wizard completion.

How Does FlowSquad Support Multiple Database Backends?

FlowSquad's data layer uses an ORM abstraction (SQLAlchemy) that supports 3 production database backends: PostgreSQL 13+, MySQL 8.0+, and MariaDB 10.6+. SQLite is available for development and evaluation environments only (not recommended for multi-user production deployments due to write concurrency limitations). The database schema includes 34 tables covering products, users, roles, content, audit logs, LLM cost tracking, and integration credentials.

For high-availability production deployments, FlowSquad supports PostgreSQL with read replicas — all write operations route to the primary, while read-heavy operations (audit log queries, cost tracking reports) can be offloaded to replicas via the DB_READ_REPLICA_URL environment variable. Connection pooling (PgBouncer) is recommended for deployments exceeding 50 concurrent users.

How Do You Configure SSO / SAML 2.0 in FlowSquad?

FlowSquad's SAML 2.0 Service Provider implementation is wizard-driven. After uploading the IdP metadata XML in Step 6, FlowSquad automatically extracts the SSO URL, certificate, and entity ID. The wizard then displays the FlowSquad SP metadata XML for you to register in your IdP (Okta, Azure AD, Ping Identity, etc.). The round-trip configuration takes approximately 8 minutes for Okta and 12 minutes for Azure AD.

SAML attribute mapping allows FlowSquad to read the user's email, display name, and group memberships from the SAML assertion. Group memberships are used for role auto-assignment: if a user is in the flowsquad-admins group in Okta, they are automatically assigned Global Admin in FlowSquad. This eliminates manual role assignment for teams with mature IdP group hygiene.

How Do You Set Up the VectorDB Connection?

Step 3 of the wizard presents a dropdown between ChromaDB and Pinecone. For ChromaDB, FlowSquad connects to an existing ChromaDB HTTP server (you deploy ChromaDB separately using its Docker image). For Pinecone, FlowSquad creates the required collections automatically using the Pinecone API on first connection. Both backends use the same internal VectorDB interface — switching backends later requires a full re-index but no application code changes.

What Happens After the Wizard Completes?

After Step 10, FlowSquad runs a post-wizard health check that verifies all configured connections are live and responsive. If all checks pass, the wizard marks setup as complete and redirects to the dashboard. If any check fails, the wizard identifies the failing step and allows inline correction before proceeding. The first Global Admin is automatically logged in, and the "Create Your First Product" onboarding flow launches immediately — from wizard start to first product created typically takes under 52 minutes in enterprise deployments.