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:1.19.10. The web application allows an authenticated user to administrate the FLOWX platform.

In order to configure the docker image you need to configure the next parameters:

flowx-process-renderer:
  env:
    BASE_API_URL: {{the one configured as host in the nginx}}
    PROCESS_API_PATH: {{something like /engine}}
    KEYCLOAK_ISSUER: {{openid provider - ex: https://something/auth/realms/realmName}}  
    KEYCLOAK_REDIRECT_URI: {{url of the SPA}}
    KEYCLOAK_CLIENT_ID: {{client ID}}
    STATIC_ASSETS_PATH: {{mediaLibrary.s3.publicUrl }}/{{env}}

---

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