Setup Guide

Complete the 10-step Setup Wizard after installing FlowSquad — covering every field, every pre-requisite, and every configuration option from SSL/TLS to license activation.

Before You Begin

Gather the following credentials and settings before starting the wizard. Having everything ready avoids partial completions and reduces the chance of needing to re-run individual steps.

Step 1 — Infrastructure & Database

Step 1 covers two independent sub-sections: SSL/TLS Configuration and Database Configuration. Both can be configured in either order.

SSL/TLS Configuration (Optional — Direct HTTPS)

Click Test SSL Configuration to validate the certificate and key can be loaded, then click Save SSL Configuration. FlowSquad will restart on port 443 after the full wizard completes.

Database Configuration

FlowSquad requires an external PostgreSQL or MySQL database to store all product data, requirements, artifacts, and users. A small SQLite configuration database (flowsquad_engine.db) is created automatically alongside the application — you do not configure this here.

Pre-requisites

• A running PostgreSQL 14+ or MySQL 8.0+ server accessible from the FlowSquad host
• A dedicated database and a dedicated user account created in advance (recommended) — or FlowSquad can create the database for you if the user has CREATE DATABASE privileges
• The firewall allows TCP on port 5432 (PostgreSQL) or 3306 (MySQL) from the FlowSquad server IP

Creating the Database User (PostgreSQL — recommended)

sudo -u postgres psql

CREATE DATABASE flowsquad;
CREATE USER flowsquad_app WITH PASSWORD 'replace-with-strong-password';
GRANT CONNECT ON DATABASE flowsquad TO flowsquad_app;
\c flowsquad
GRANT USAGE, CREATE ON SCHEMA public TO flowsquad_app;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO flowsquad_app;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO flowsquad_app;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO flowsquad_app;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO flowsquad_app;
\q

Creating the Database User (MySQL)

sudo mysql -u root
CREATE DATABASE flowsquad CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'flowsquad_app'@'%' IDENTIFIED BY 'replace-with-strong-password';
GRANT ALL PRIVILEGES ON flowsquad.* TO 'flowsquad_app'@'%';
FLUSH PRIVILEGES;
EXIT;

Fields in the Wizard

Click Test Connection to validate the credentials. FlowSquad applies all required database schema migrations automatically if the connection test passes. Click Save & Continue.

Step 2 — Vector Database

The vector database stores the semantic embeddings of your codebase and documents. It powers all AI retrieval — Analyze, AskProduct, Quality Score, and Security Scan all query this store.

Options

Fields — ChromaDB

No fields required. Select ChromaDB (Local) and click Save & Continue.

Step 3 — LLM Provider

FlowSquad requires at least one AI (LLM) provider to generate requirements, epics, stories, designs, and test cases. You must configure the global default here; per-product overrides can be set later from the Admin Panel.

Supported Providers

Fields — OpenAI

Fields — GitHub Models

Fields — Anthropic Claude

Fields — Ollama

Click Test Connection to verify the API key is valid and the provider is reachable. Click Save & Continue.

Step 4 — Authentication

Choose how users will sign in to FlowSquad. Multiple authentication methods can be enabled simultaneously — for example, Local Accounts (always on) plus LDAP for corporate users, plus SAML for executive accounts. Each method is independently configured and tested.

Local Accounts (Always Active)

Local authentication is always enabled and cannot be disabled. It provides the initial admin account and is the fallback if SSO is unavailable. Passwords are stored using bcrypt (12 rounds) — never in plain text.

• Minimum password length is configurable (default: 8 characters)
• Password complexity rules are configurable in Admin Panel -> Settings -> Security after setup
• No external dependencies

LDAP / Active Directory

Pre-requisites: A dedicated LDAP service account with read-only directory access. The FlowSquad server must be able to reach the LDAP server on port 389 (LDAP) or port 636 (LDAPS).

Group-to-Role Mapping

Map AD/LDAP groups to FlowSquad roles. Users in the mapped groups automatically receive the corresponding role on every login.

• CN=FlowSquad-Admins,OU=Groups,DC=company,DC=com -> Global Admin
• CN=FlowSquad-ProdAdmins,OU=Groups,DC=company,DC=com -> Product Admin
• CN=FlowSquad-Users,OU=Groups,DC=company,DC=com -> Regular User

SAML 2.0 SSO

Pre-requisites: You need IdP metadata (SSO URL and X.509 certificate) from your identity provider — Keycloak, Okta, Azure AD, OneLogin, ADFS, Google Workspace, or any standard SAML 2.0 IdP.

There are three fields to fill in. Everything else is auto-generated.

The SP fields (SP Entity ID, ACS URL /saml/callback, Single Logout URL /saml/logout) are auto-generated from the Entity ID you enter and displayed as read-only values to copy into your IdP. There is no separate “Attribute Mapping” section — FlowSquad automatically reads the email SAML attribute. For a full Keycloak SAML walkthrough, see the Reference Guide — Keycloak SAML.

OAuth2 Social / Enterprise Login

Pre-requisites: An OAuth2 application registered in your provider's developer console with the correct redirect URI.

The redirect URI to register in each provider's console is:

https://flowsquad.yourcompany.com/oauth2/<provider>/callback

# Examples:
https://flowsquad.yourcompany.com/oauth2/github/callback
https://flowsquad.yourcompany.com/oauth2/google/callback
https://flowsquad.yourcompany.com/oauth2/microsoft/callback
https://flowsquad.yourcompany.com/oauth2/okta/callback
https://flowsquad.yourcompany.com/oauth2/keycloak/callback
https://flowsquad.yourcompany.com/oauth2/custom/callback

Multi-Factor Authentication (MFA)

MFA is configured in Setup Wizard Step 4. When enabled, users can enrol MFA from the 🔑 MFA button in the navigation bar. Enforcement policies can make MFA mandatory for all users or admins only.

MFA Methods

Enforcement Policies

Step 5 — Source Control

Connect FlowSquad to your source control provider to enable direct codebase loading via Git URL in the Analyze tab. This step is optional — you can also load codebases via ZIP file or local path without any configuration here.

Pre-requisites

• A personal access token (PAT) or service account token with read-only repository access
• The token must be authorised for your organisation if SAML SSO is enforced on GitHub

Enter the token and click Test Connection. FlowSquad attempts to list repositories accessible to the token to confirm it is valid. Click Save & Continue (or Skip if not configuring source control now).

Step 6 — Collaboration Tools

Connect FlowSquad to Jira and Confluence to enable pushing generated artifacts (Epics, Stories, Tasks, Designs) directly to your project management and documentation tools. Both integrations are optional and can be configured or updated later via Admin Panel -> Settings.

Jira Setup

Pre-requisites: A Jira account (Cloud or Server/Data Center). For Jira Cloud, you need an API token (not your account password). For Jira Server, you use your username and password.

Confluence Setup

Pre-requisites: A Confluence account with create-page permissions in your target space.

Step 7 — Create Admin Users

Create the initial administrator account(s). Accounts created here receive the Global Administrator role, which grants unrestricted access to all products, all user management functions, and all system settings.

Fields

You can create multiple admins in this step by clicking + Add Another Admin. At least one admin account is required to proceed.

Step 8 — License Activation

Upload your FlowSquad Enterprise license file (.lic). License validation is performed locally — no internet access is required.

Pre-requisites

• A valid .lic license file from your FlowSquad account manager or the partner portal
• For Docker or Kubernetes deployments: the FLOWSQUAD_CLUSTER_ID environment variable must match the ID used when the license was generated
• For Linux bare-metal or Windows: /etc/machine-id (Linux) or the Windows machine GUID is used automatically

Uploading the License

1. Click Upload License File and select your .lic file.
2. FlowSquad validates the RSA-4096 signature, expiration date, and machine ID binding.
3. If valid, license details are displayed: license type, company name, maximum products, and validity period.
4. Click Activate & Continue.

Step 9 — System Settings

Step 9 configures system-level services. Both sub-sections are optional but Email (SMTP) is strongly recommended — it is required for MFA email OTP, password reset emails, and audit alert notifications.

Email Server (SMTP)

Click Send Test Email to verify the SMTP configuration, then click Save Configuration.

Audit Logging

Audit logging is always enabled and cannot be disabled — it is a compliance requirement. You can configure retention and alert behaviour:

Step 10 — Complete Setup

The final step presents a summary of your complete configuration. Review each section:

• SSL/TLS — enabled/disabled; certificate path (if direct HTTPS)
• Database — type, host, port, database name (password redacted)
• Vector Database — ChromaDB (local)
• LLM Provider — provider name and selected default model
• Authentication — enabled methods and their test status; MFA enforcement policy
• Source Control — connected provider (if configured)
• Collaboration Tools — Jira and/or Confluence connection status
• Admin Accounts — list of created Global Admin emails
• License — type, validity, and product limit
• System Settings — SMTP email status; audit log retention

Configuration Database Security

The configuration database (flowsquad_engine.db) stores API keys, credentials, and license information. All sensitive values are automatically encrypted at the field level before storage — no additional configuration is required. Click Complete Setup to finish.

Click Complete Setup. FlowSquad saves the configuration and applies any final database migrations. You are redirected to the login page.

Post-Setup Checklist

After completing the wizard, verify the following before onboarding users:

• Login with the Global Admin account you created succeeds
• Admin Panel is accessible at /admin after login
• License Management shows the correct license type, company name, and validity dates
• LLM Configuration shows the provider as connected (green status)
• Database Settings shows the product database as connected
• If SSO is configured: test login via each enabled SSO method
• Create a test product and run a test AI generation to confirm the LLM pipeline works end-to-end
• MFA enabled on the Global Admin account (User Preferences -> Security -> Enable MFA)
• Admin password changed from the setup temporary value (if applicable)
• SMTP email configured for system notifications (Admin Panel -> Settings -> Email)

Troubleshooting

Database Connection Failed

Symptoms: "Connection refused" or "could not connect to server" when clicking Test Connection in Step 1.

Solutions:

1. Confirm the database service is running: sudo systemctl status postgresql (Linux) or Get-Service postgresql* (Windows)
2. Check that listen_addresses in postgresql.conf includes the FlowSquad server's IP (or '*')
3. Verify the firewall allows the database port from the FlowSquad host: sudo ufw allow 5432/tcp
4. Test the connection manually: psql -h <host> -U flowsquad_app -d flowsquad

LLM "Invalid API Key" (401)

Symptoms: Test Connection returns authentication error in Step 3.

Solutions:

1. Verify there are no leading/trailing spaces in the pasted API key
2. For OpenAI: check billing is active and the key is not restricted to specific IPs at platform.openai.com -> API keys
3. For Anthropic: confirm the key starts with sk-ant- and was created in the correct workspace
4. Generate a new key from the provider's console and re-enter it

LDAP "Invalid Credentials" (Correct Password)

Symptoms: Test Connection fails with "LDAP bind failed" even though the service account password is correct.

Solutions:

1. Verify the Bind DN format exactly — use ldapsearch to confirm: ldapsearch -H ldap://ad.company.com -D "CN=svc-flowsquad,OU=ServiceAccounts,DC=company,DC=com" -W -b "DC=company,DC=com" "(sAMAccountName=svc-flowsquad)"
2. Check the service account password has not expired in Active Directory
3. If using LDAPS (port 636), ensure the server's certificate is trusted: import the CA certificate to the FlowSquad server's trust store
4. Broaden the User Search Base to DC=company,DC=com to cover users across all OUs

SAML "Invalid SAML Response"

Symptoms: User authenticates at IdP but FlowSquad shows "Invalid SAML response" or "Signature validation failed".

Solutions:

1. Verify the SP Entity ID in your IdP matches the auto-filled value in FlowSquad exactly, including port number: https://flowsquad.company.com:5000/saml/metadata
2. Download the SP certificate from FlowSquad (Step 4 -> SAML -> "Generate SP Certificate" -> Download) and import it into your IdP
3. Confirm both "Sign Assertions" and "Sign Document" are enabled in your IdP
4. Check that the Email Attribute name in FlowSquad matches the attribute name your IdP sends

License "Validation Failed — Machine ID Mismatch"

Symptoms: License upload fails with machine ID or cluster ID mismatch error in Step 8.

Solutions:

1. For Docker: verify FLOWSQUAD_CLUSTER_ID environment variable in docker-compose.yml matches the ID provided when the license was issued
2. For Linux: check /etc/machine-id is correctly mounted into the container: - /etc/machine-id:/etc/host-machine-id:ro
3. For Kubernetes: confirm the flowsquad-machine secret contains the correct cluster ID
4. Contact support@flowsquad.ai with your deployment type and machine ID if re-issuance is needed

Setup Wizard Does Not Appear on First Load

Symptoms: Navigating to FlowSquad shows a login page or a blank page instead of the Setup Wizard.

Solutions:

1. If the wizard was previously partially completed, navigate to /setup directly
2. If the wizard is locked due to a previous failed run, stop FlowSquad, remove the flowsquad_engine.db file from the data directory, and restart — this resets all setup state (warning: all previous settings are lost)
3. Check the application logs for startup errors: Linux: sudo journalctl -u flowsquad -f; Docker: docker compose logs -f