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 load balancer from the FlowX Engine. This routing mechanism handles API calls from 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:

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:

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:

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:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/cors-allow-headers: "<your_defaultCorsAllowHeaders_value>"
  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

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

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

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>

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

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

Ingress Configuration

Configure routing, CORS, and TLS for FlowX services

IAM Configuration

Identity and access management setup