> ## 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 ### NGINX For optimal operation the FlowX.AI Designer should use a separate [NGINX](../docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-nginx) load balancer from the **FlowX Engine**. This routing mechanism handles API calls from the [SPA](./designer-setup-guide#for-configuring-the-spa) (single page application) to the backend service, to the engine and to various plugins. Here's an example/suggestion of an NGINX setup: #### For routing calls to plugins: ```jsx theme={"system"} metadata: annotations: kubernetes.io/ingress.class: nginx nginx.ingress.kubernetes.io/enable-cors: "true" nginx.ingress.kubernetes.io/cors-allow-methods: GET, PUT, POST, DELETE, PATCH nginx.ingress.kubernetes.io/cors-allow-origin: "http://localhost:4200,http://localhost:80,http://localhost:8080" nginx.ingress.kubernetes.io/rewrite-target: /$2 name: flowx-admin-plugins-subpaths spec: rules: - host: {{host}} http: paths: - path: /notification(/|$)(.*) backend: serviceName: notification servicePort: 80 - path: /document(/|$)(.*) backend: serviceName: document servicePort: 80 tls: - hosts: - {{host}} secretName: {{tls secret}} ``` #### For routing calls to the engine Three different configurations are needed: 1. For viewing the current instances of processes running in the Engine: ```jsx theme={"system"} apiVersion: extensions/v1beta1 kind: Ingress metadata: annotations: kubernetes.io/ingress.class: nginx nginx.ingress.kubernetes.io/rewrite-target: /api/instances/$2 nginx.ingress.kubernetes.io/enable-cors: "true" nginx.ingress.kubernetes.io/cors-allow-methods: GET, PUT, POST, DELETE, PATCH nginx.ingress.kubernetes.io/cors-allow-origin: "http://localhost:4200,http://localhost:80,http://localhost:8080" name: flowx-admin-engine-instances spec: rules: - host: {{host}} http: paths: - path: /api/instances(/|$)(.*) backend: serviceName: {{engine-service-name}} servicePort: 80 ``` 2. For testing process definitions from the FLOWX Designer, route API calls and SSE communication to the Engine backend. Setup for routing REST calls: ```jsx theme={"system"} apiVersion: extensions/v1beta1 kind: Ingress metadata: annotations: kubernetes.io/ingress.class: nginx nginx.ingress.kubernetes.io/rewrite-target: /api/$2 nginx.ingress.kubernetes.io/enable-cors: "true" nginx.ingress.kubernetes.io/cors-allow-methods: GET, PUT, POST, DELETE, PATCH nginx.ingress.kubernetes.io/cors-allow-origin: "http://localhost:4200,http://localhost:80,http://localhost:8080" name: flowx-admin-engine-rest-api spec: rules: - host: {{host}} http: paths: - path: /{{PROCESS_API_PATH}}/api(/|$)(.*) backend: serviceName: {{engine-service-name}} servicePort: 80 ``` Setup for routing SSE communication: ```jsx theme={"system"} apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: nginx.ingress.kubernetes.io/cors-allow-headers: "" name: flowx-public-subpath-events-rewrite spec: rules: - host: {{host}} http: paths: - backend: service: name: events-gateway port: name: http path: /api/events(/|$)(.*) ``` 3. For accessing the REST API of the backend microservice ```jsx theme={"system"} apiVersion: extensions/v1beta1 kind: Ingress metadata: annotations: kubernetes.io/ingress.class: nginx nginx.ingress.kubernetes.io/proxy-body-size: "4m" nginx.ingress.kubernetes.io/enable-cors: "true" nginx.ingress.kubernetes.io/cors-allow-methods: GET, PUT, POST, DELETE, PATCH nginx.ingress.kubernetes.io/cors-allow-origin: "http://localhost:4200,http://localhost:80,http://localhost:8080" name: flowx-admin-api spec: rules: - host: {{host}} http: paths: - path: / backend: serviceName: {{flowx-admin-service-name}} servicePort: 80 tls: - hosts: - {{host}} secretName: {{tls secret}} ``` #### For configuring the SPA ```jsx theme={"system"} apiVersion: extensions/v1beta1 kind: Ingress metadata: annotations: certmanager.k8s.io/issuer: letsencrypt-prod kubernetes.io/ingress.class: nginx ingress.kubernetes.io/affinity: cookie name: flowx-designer-spa spec: rules: - host: {{host of web app}} http: paths: - backend: serviceName: {{flowx-designer-service-name}} servicePort: 80 tls: - hosts: - {{host of web app}} secretName: {{tls secret}} ``` *** ## 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. `/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 **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 ` **Symptoms:** Redirect loops, blank screens after login, or 401 errors. **Solutions:** 1. Verify `KEYCLOAK_ISSUER` matches the realm URL exactly (including `/auth/realms/`) 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 **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 `nginx.ingress.kubernetes.io/cors-allow-headers` includes required headers 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 Configure routing, CORS, and TLS for FlowX services Identity and access management setup ## Related topics - [FlowX CMS setup](/5.1/setup-guides/cms-setup.md) - [FlowX Admin setup](/5.1/setup-guides/admin-setup-guide.md) - [FlowX Events Gateway setup](/5.1/setup-guides/events-gateway-setup.md) - [FlowX Engine setup](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup.md) - [Intro to NGINX](/5.1/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-nginx.md)