Documentation Index
Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
Use this file to discover all available pages before exploring further.
Prerequisites management
Ingress routing
The FlowX Designer is a single-page application (SPA) served from its own pod, with backend API calls proxied to the Process Engine, Application Manager, and the various plugins. Routing for the Designer and every backend service is rendered by the FlowX Helm chart — there is no separate hand-authored NGINX configuration in 5.9.x. The Designer itself is exposed on the public host at/ (path preserved), with a wildcard *.public-host rule that supports workspace-per-subdomain access. Each backend service the Designer calls has its own ingress rule rendered by the chart (see Ingress configuration guide for the complete route reference).
For SPA-specific concerns — TLS, cookie affinity, custom domains — configure these through the chart values (services.designer.ingress.public.annotations, services.designer.ingress.public.extraTls) or share your requirements with FlowX so they are wired in during the upgrade.
Upgrading from 5.1.x? See Ingress routing and CORS migration for the NGINX → chart-rendered routing transition.
Steps to deploy Frontend app
The FlowX.AI Designer is an SPA application that is packaged in a docker image withnginx. The web application allows an authenticated user to administrate the FlowX platform. Environment variables are injected at container startup via envsubst.
Application configuration
| Environment Variable | Description | Default Value |
|---|---|---|
BASE_API_URL | Backend API base URL (the host configured in the NGINX ingress) | - |
ADMIN_API_URL | Admin API URL, used for admin-specific backend calls | - |
PROCESS_API_PATH | API path prefix for the process engine (e.g. /engine) | - |
STATIC_ASSETS_PATH | Public URL for static assets / media library CDN | - |
BASE_HREF | HTML base href override for non-root deployments | / |
VERSION | Application version string displayed in the UI | - |
ROOT_DOMAIN | Root domain for the application | - |
COLLABORATION_POLLING_INTERVAL | Polling interval in milliseconds for collaboration features | - |
LEGACY_HTTP_VERSION | Enables legacy HTTP polling mode with SSE reconnect on page visibility change | false |
Authentication (OpenID Connect)
| Environment Variable | Description | Default Value |
|---|---|---|
KEYCLOAK_ISSUER | OpenID Connect provider issuer URL (e.g. https://your-idp/auth/realms/realmName) | - |
KEYCLOAK_REDIRECT_URI | OAuth redirect URI (URL of the SPA) | - |
KEYCLOAK_CLIENT_ID | OAuth client ID | - |
KEYCLOAK_SCOPES | OAuth scopes requested during authentication | openid profile email |
DEFAULT_ORGANIZATION_NAME | Default organization name for login | - |
REQUIRE_HTTPS | Require HTTPS for OAuth communication | true |
SHOW_DEBUG_INFORMATION | Show OAuth debug information in the browser console | true |
DISABLE_AT_HASH_CHECK | Disable at_hash claim validation | false |
SKIP_ISSUER_CHECK | Skip OAuth issuer URL validation | - |
STRICT_DISCOVERY_DOCUMENT_VALIDATION | Enforce strict OIDC discovery document validation | - |
Troubleshooting
Common issues
NGINX configuration errors
NGINX configuration errors
Symptoms: 502 Bad Gateway or 404 errors when accessing the Designer.Solutions:
- Verify the ingress annotations are correct, especially
rewrite-targetpaths - Check that backend service names and ports match your Kubernetes service definitions
- Ensure CORS origins include all domains the Designer is accessed from
- Validate the
hostvalues in ingress rules match your DNS configuration - Check NGINX controller logs for detailed routing errors:
kubectl logs -n ingress-nginx <controller-pod>
SSO/authentication failures
SSO/authentication failures
Symptoms: Redirect loops, blank screens after login, or 401 errors.Solutions:
- Verify
KEYCLOAK_ISSUERmatches the realm URL exactly (including/auth/realms/<realm>) - Ensure
KEYCLOAK_REDIRECT_URImatches the SPA URL configured in the Keycloak client - Check that the Keycloak client ID (
KEYCLOAK_CLIENT_ID) exists and is enabled - Confirm the Keycloak client has the correct redirect URIs and web origins configured
- Clear browser cookies and local storage, then try again
WebSocket connection issues
WebSocket connection issues
Symptoms: Real-time updates not working, SSE events not received, process testing hangs.Solutions:
- Verify the SSE ingress configuration routes
/api/eventsto the events-gateway service - Check that
nginx.ingress.kubernetes.io/cors-allow-headersincludes required headers - Ensure the events-gateway service is running and healthy
- Confirm network policies allow traffic from the Designer ingress to the events-gateway pod
- Check for proxy timeout settings that may terminate long-lived connections
Related resources
Ingress Configuration
Configure routing, CORS, and TLS for FlowX services
IAM Configuration
Identity and access management setup