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

# FlowX Designer setup

> To set up FlowX Designer in your environment, follow this guide.

## 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](https://docs.flowx.ai/6.x/setup-guides/ingress-configuration.md) 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](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/ingress-routing.md) for the NGINX → chart-rendered routing transition.

### Outbound network access

In restricted or air-gapped networks, the FlowX Designer loads a few assets over HTTPS from external domains **at runtime, from the end user's browser**. Allowlist the following domains, or route them through an approved outbound proxy, so the Designer works correctly:

| Domain | Port | Used for |
| - | - | - |
| `cdn.ckeditor.com` | 443 | Rich-text editor for document and notification templates |
| `esm.sh` | 443 | Runtime dependencies for custom (code) components |
| `fonts.googleapis.com` | 443 | Web font stylesheets (Roboto, Material Icons) |
| `fonts.gstatic.com` | 443 | Web font files referenced by the stylesheets above |

> [!NOTE]
>
> These requests originate from the user's browser, not from the cluster, so the allowlist must apply to the network the Designer is accessed from (corporate proxy, VPN, or client firewall), not only to cluster egress.

***

## Steps to deploy Frontend app

The FlowX.AI Designer is an SPA application that is packaged in a docker image with `nginx`. 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. `/onboarding`, matching the process engine ingress path) | - |
| `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

> [accordion] NGINX configuration errors
>
> **Symptoms:** 502 Bad Gateway or 404 errors when accessing the Designer.
>
> **Solutions:**
>
> 1. Verify the ingress annotations are correct, especially `rewrite-target` paths
> 2. Check that backend service names and ports match your Kubernetes service definitions
> 3. Ensure CORS origins include all domains the Designer is accessed from
> 4. Validate the `host` values in ingress rules match your DNS configuration
> 5. Check NGINX controller logs for detailed routing errors: `kubectl logs -n ingress-nginx <controller-pod>`

> [accordion] SSO/authentication failures
>
> **Symptoms:** Redirect loops, blank screens after login, or 401 errors.
>
> **Solutions:**
>
> 1. Verify `KEYCLOAK_ISSUER` matches the realm URL exactly (including `/auth/realms/<realm>`)
> 2. Ensure `KEYCLOAK_REDIRECT_URI` matches the SPA URL configured in the Keycloak client
> 3. Check that the Keycloak client ID (`KEYCLOAK_CLIENT_ID`) exists and is enabled
> 4. Confirm the Keycloak client has the correct redirect URIs and web origins configured
> 5. Clear browser cookies and local storage, then try again

> [accordion] WebSocket connection issues
>
> **Symptoms:** Real-time updates not working, SSE events not received, process testing hangs.
>
> **Solutions:**
>
> 1. Verify the SSE ingress configuration routes `/api/events` to the events-gateway service
> 2. Check that `APPLICATION_CORS_ALLOWORIGIN` on the events-gateway service includes the Designer origin. On 5.9.x, each backend service handles CORS, and the NGINX `cors-*` annotations have no effect. See [CORS handling in the ingress configuration](https://docs.flowx.ai/6.x/setup-guides/ingress-configuration.md#application_cors_alloworigin)
> 3. Ensure the events-gateway service is running and healthy
> 4. Confirm network policies allow traffic from the Designer ingress to the events-gateway pod
> 5. Check for proxy timeout settings that may terminate long-lived connections

***

## Related resources

> [card] [Ingress Configuration](https://docs.flowx.ai/6.x/setup-guides/ingress-configuration.md)
>
> Configure routing, CORS, and TLS for FlowX services

> [card] [IAM Configuration](https://docs.flowx.ai/6.x/setup-guides/access-management/configuring-an-iam-solution.md)
>
> Identity and access management setup


## Related topics

- [FlowX CMS setup](https://docs.flowx.ai/6.x/setup-guides/cms-setup.md)
- [FlowX Admin setup](https://docs.flowx.ai/6.x/setup-guides/admin-setup-guide.md)
- [FlowX Engine setup](https://docs.flowx.ai/6.x/setup-guides/flowx-engine-setup-guide/engine-setup.md)
- [FlowX Events Gateway setup](https://docs.flowx.ai/6.x/setup-guides/events-gateway-setup.md)
- [Intro to NGINX](https://docs.flowx.ai/6.x/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-nginx.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.