BAMOE Canvas is a web application that provides authoring tools for Decisions and Workflows, directly in the browser. It enables different profiles of user (business automation developers and business policy managers) to create, edit and manage Decisions and Workflows, through editors and service integrations such as Git for syncing repositories, and OpenShift and Kubernetes for deploying your Business Services in development mode via the Dev Deployments feature.

BAMOE Canvas depends on two backend applications to provide full functionality:

  • BAMOE Extended Services: powers features like the DMN Runner and static validation of DMN, and BPMN models.

  • BAMOE CORS proxy: allows BAMOE Canvas web app to communicate with Git and Cloud providers.

BAMOE Canvas and its two backend applications are available as container images.

These images are published to Quay.io and can be used to run containers locally or with any cloud provider.

Note
 All three image versions must be the same for deployment to work.

Deploying to Kubernetes or OpenShift with the Helm Chart (recommended)

BAMOE Canvas Helm Chart is a Helm chart based on the open-source Apache KIE Sandbox and it is a technology that can enable you to install multi-container services with a single command: Helm, See https://helm.sh for more information.

Installing the Chart

Use the following command to do a default installation:

helm install my-bamoe-canvas oci://quay.io/bamoe/canvas-helm-chart --version={VERSION}.

OpenShift install

First, you may need to get the default OpenShift domain for your routes with the following command:

oc get ingresses.config cluster --output jsonpath={.spec.domain}

If you do not have access rights to this configuration, try creating a dummy Route resource and checking its domain.

helm pull oci://quay.io/bamoe/canvas-helm-chart --version={VERSION} --untar
helm install my-bamoe-canvas ./canvas-helm-chart --values ./canvas-helm-chart/values-openshift.yaml --set global.openshiftRouteDomain="<YOUR_OCP_ROUTE_DOMAIN>"

Kubernetes install

helm pull oci://quay.io/bamoe/canvas-helm-chart --version={VERSION} --untar
helm install my-bamoe-canvas ./canvas-helm-chart --values ./canvas-helm-chart/values-kubernetes.yaml --set global.kubernetesClusterDomain="<YOUR_KUBERNETES_CLUSTER_DOMAIN>" --set global.kubernetesIngressClass="<YOUR_KUBERNETES_INGRESS_CLASS>"

Minikube install

helm pull oci://quay.io/bamoe/canvas-helm-chart --version={VERSION} --untar
helm install my-bamoe-canvas ./canvas-helm-chart --values ./canvas-helm-chart/values-minikube-nginx.yaml

Uninstalling the Chart

Follow the command to uninstall the my-bamoe-canvas deployment:

helm uninstall my-bamoe-canvas

Passing environmental variables

This Chart uses default environmental variables from values.yaml file. You can override the variables by passing them through the command line. See BAMOE Canvas Helm Chart configuration reference for all options.

helm install my-bamoe-canvas ./src --set image.repository=quay.io

Deploying BAMOE Canvas to OpenShift via CLI

If you have an OpenShift cluster and are logged in via the oc CLI tool, follow these steps to deploy BAMOE Canvas and its dependencies.

Note
 Labeling the resources is optional, but it will make organizing and identifying your deployed resources significantly easier.

  1. Define some variables that will be useful to name and label the resources created.

    export APP_PART_OF=bamoe-canvas-app
export APP_NAME_EXTENDED_SERVICES=bamoe-extended-services
export APP_NAME_CORS_PROXY=bamoe-cors-proxy
export APP_NAME_BAMOE_CANVAS=bamoe-canvas

  2. Deploy BAMOE Extended Services and label its resources

    oc new-app quay.io/bamoe/extended-services:9.2.1-ibm-0005 --name=$APP_NAME_EXTENDED_SERVICES
oc create route edge --service=$APP_NAME_EXTENDED_SERVICES
oc label services/$APP_NAME_EXTENDED_SERVICES app.kubernetes.io/part-of=$APP_PART_OF
oc label routes/$APP_NAME_EXTENDED_SERVICES app.kubernetes.io/part-of=$APP_PART_OF
oc label deployments/$APP_NAME_EXTENDED_SERVICES app.kubernetes.io/part-of=$APP_PART_OF
oc label deployments/$APP_NAME_EXTENDED_SERVICES app.openshift.io/runtime=golang

  3. Deploy BAMOE CORS proxy and label its resources

    oc new-app quay.io/bamoe/cors-proxy:9.2.1-ibm-0005 --name=$APP_NAME_CORS_PROXY
oc create route edge --service=$APP_NAME_CORS_PROXY
oc label services/$APP_NAME_CORS_PROXY app.kubernetes.io/part-of=$APP_PART_OF
oc label routes/$APP_NAME_CORS_PROXY app.kubernetes.io/part-of=$APP_PART_OF
oc label deployments/$APP_NAME_CORS_PROXY app.kubernetes.io/part-of=$APP_PART_OF
oc label deployments/$APP_NAME_CORS_PROXY app.openshift.io/runtime=nodejs

  4. Finally, deploy the BAMOE Canvas image, setting the environment variables required to connect it to the BAMOE Extended Services and BAMOE CORS proxy backends.

    oc new-app quay.io/bamoe/canvas:9.2.1-ibm-0005 --name=$APP_NAME_BAMOE_CANVAS \
  -e KIE_SANDBOX_EXTENDED_SERVICES_URL=https://$(oc get route $APP_NAME_EXTENDED_SERVICES --output jsonpath={.spec.host}) \
  -e KIE_SANDBOX_CORS_PROXY_URL=https://$(oc get route $APP_NAME_CORS_PROXY --output jsonpath={.spec.host})
oc create route edge --service=$APP_NAME_BAMOE_CANVAS
oc label services/$APP_NAME_BAMOE_CANVAS app.kubernetes.io/part-of=$APP_PART_OF
oc label routes/$APP_NAME_BAMOE_CANVAS app.kubernetes.io/part-of=$APP_PART_OF
oc label deployments/$APP_NAME_BAMOE_CANVAS app.kubernetes.io/part-of=$APP_PART_OF
oc label deployments/$APP_NAME_BAMOE_CANVAS app.openshift.io/runtime=js
OpenShift topology after BAMOE Canvas deployment
Figure 1. The OpenShift topology after BAMOE Canvas deployment

Your BAMOE Canvas instance should be up and accessible via the route created in this last step. To get it, run this command:

oc get route $APP_NAME_BAMOE_CANVAS --output jsonpath={.spec.host}
Note
 All services will be available via https, which means that if you are deploying them to a local OpenShift instance (i.e. via CRC), the BAMOE Canvas web app, the BAMOE Extended Services and BAMOE CORS proxy backends will all be using self-signed certificates, causing warnings in your browser. To fix this, access each URL individually and allow them in your browser.

Running locally with Docker Compose

BAMOE Canvas and its related services can be run locally using Docker Compose.

See Docker Installation and Compose Plugin Installation for more information.

The bamoe-9.2.1-docker-compose.zip can only be downloaded from IBM Passport Advantage, and you can find information on the BAMOE 9.2 Download Document.

Run

To Run BAMOE Canvas with Docker Compose follow these steps:

  1. Extract the downloaded bamoe-9.2.1-docker-compose.zip.

  2. In a terminal, navigate to the extracted folder: bamoe-9.2.1-canvas-docker-compose.

  3. Run the command:

    docker compose up

BAMOE Canvas will be available at http://localhost:9090.

Running locally with Docker

Configuring BAMOE Extended Services

docker run -p 21345:21345 -it quay.io/bamoe/extended-services:9.2.1-ibm-0005
# Add the -d flag to run in detached mode.

Access the API through port 21345, no additional configuration is necessary.

Configuring BAMOE CORS proxy

docker run -p 8090:8080 -it quay.io/bamoe/cors-proxy:9.2.1-ibm-0005
# Add the -d flag to run in detached mode.

The API is accessible via port 8090 (8080 is reserved for the bamoe-canvas image). No additional configuration is necessary.

Configuring BAMOE Canvas

This image must be run with two environment variables that will allow it to communicate with the two backend services:

KIE_SANDBOX_EXTENDED_SERVICES_URL

E.g., https://extended-services.bamoe.my-company.com

KIE_SANDBOX_CORS_PROXY_URL

E.g., https://cors-proxy.bamoe.my-company.com

If you are running locally, following the previous steps, use this command to start your BAMOE Canvas instance with the backend services:

docker run -p 8080:8080 -it \
  -e KIE_SANDBOX_EXTENDED_SERVICES_URL=http://localhost:21345 \
  -e KIE_SANDBOX_CORS_PROXY_URL=http://localhost:8090 \
  quay.io/bamoe/canvas:9.2.1-ibm-0005
# Add the -d flag to run in detached mode.

The HTTP server is accessed via port 8080.

Several customization options are available. For more information on the configurations available via environment variables see BAMOE Canvas’s image description on Quay.io.

Note

Those addresses need to be accessible from the users' machines, as BAMOE Canvas will make requests to them directly from the user’s browser. Using internal IP/DNS services will not work. Requests are made directly from the user’s browser to both URLs configured above.

Another very important environment variable to consider when deploying BAMOE Canvas is KIE_SANDBOX_DEV_DEPLOYMENT_BASE_IMAGE_URL. It points to a container image that is used when creating a Dev Deployment.

By default, BAMOE Canvas is configured to fetch this image from https://quay.io/bamoe/canvas-dev-deployment-base:9.2.0-ibm-0004.

If you are installing BAMOE Canvas in an air-gapped environment, you will need to configure KIE_SANDBOX_DEV_DEPLOYMENT_BASE_IMAGE_URL to point to an image in a registry where the Cloud providers used by BAMOE Canvas users can access it.

For example, imagine a user is creating Dev Deployments for Decisions on BAMOE Canvas to a local Kubernetes they have installed on their machine, for example Kind or Minikube. This local Kubernetes instance needs to be able to download the image configured in KIE_SANDBOX_DEV_DEPLOYMENT_BASE_IMAGE_URL. The same is true for remote Kubernetes and OpenShift instances that the users of BAMOE Canvas will configure to create their Dev Deployments for Decisions.

For other customization options of BAMOE Canvas, see BAMOE Canvas’s image description on Quay.io.

Securing your installation

It is recommended to have a secure protocol (HTTPS) available for the BAMOE Canvas installation as well as all services that BAMOE Canvas has access to, such as remote git repositories, or container orchestration like OpenShift. To enable that, follow your Kubernetes distribution documentation on how to enable a secure protocol.

Configuring custom Accelerators for your organization

Accelerators are Git repositories that contain a skeleton of an application and will convert a working directory with your .dmn and .bpmn files into a fully functional application that can be built and deployed. But they can also be used to store configurations that are common to all new Business Service projects within an organization, making them available in BAMOE Canvas for all users in your organization.

Your custom Accelerator should be a public Git repository. After creating it, you need to write a specific JSON configuration that is used in the KIE_SANDBOX_ACCELERATORS environment variable for BAMOE Canvas:

{
    "name": "Your Accelerator name",
    "iconUrl": "https://link.to/your/logo/image",
    "gitRepositoryUrl": "https://github.com/...",
    "gitRepositoryGitRef": "branchName",
    "dmnDestinationFolder": "path/to/place/dmn/files",
    "bpmnDestinationFolder": "path/to/place/bpmn/files",
    "otherFilesDestinationFolder": "path/to/place/other/files"
}

  • name: This is how the Accelerator will be known inside BAMOE Canvas.

  • iconUrl: An optional parameter to add an image/logo alongside you Accelerator name.

  • gitRepositoryUrl: This is where your Accelerator is hosted. Should be an URL that can be used with git clone.

  • gitRepositoryGitRef: Where in your repository is this Accelerator located. Could be a branch, commit, tag, anything that can be used with git checkout.

  • dmnDestinationFolder: Where your DMN and PMML files will be moved to after applying the Accelerator (relative to the project root).

  • bpmnDestinationFolder: Where your BPMN files will be moved to after applying the Accelerator (relative to the project root).

  • otherFilesDestinationFolder: Where other files will be moved to after applying the Accelerator (relative to the project root).

Configuring the KIE_SANDBOX_ACCELERATORS environment variable

This environment variable accepts an array of Accelerators configurations in the format described above.

By default, it comes pre-configured with:

[
    {
        "name": "Quarkus (Full)",
        "iconUrl": "images/canvas_accelerator_logo_quarkus_full.png",
        "gitRepositoryUrl": "https://github.com/ibm/bamoe-canvas-quarkus-accelerator",
        "gitRepositoryGitRef": "9.2.1-ibm-0005-quarkus-full",
        "dmnDestinationFolder": "src/main/resources",
        "bpmnDestinationFolder": "src/main/resources",
        "otherFilesDestinationFolder": "src/main/resources"
    },
    {
        "name": "Quarkus (DMN)",
        "iconUrl": "images/canvas_accelerator_logo_quarkus_dmn.png",
        "gitRepositoryUrl": "https://github.com/ibm/bamoe-canvas-quarkus-accelerator",
        "gitRepositoryGitRef": "9.2.1-ibm-0005-quarkus-dmn",
        "dmnDestinationFolder": "src/main/resources",
        "bpmnDestinationFolder": "src/main/resources",
        "otherFilesDestinationFolder": "src/main/resources"
    }
]

This value can be overwritten to add your own custom Accelerators, replacing the default ones, or appending to them.

Configuring GitHub Enterprise Server, GitLab, or BitBucket Data Center

To allow users to connect to your organization’s source code control instance, you will need to configure the KIE_SANDBOX_AUTH_PROVIDERS environment variable on your BAMOE Canvas installation. For more information refer to the BAMOE Canvas image description on Quay.io.

Once you have done this BAMOE Canvas users have access to the functionality available in the different integrations:

Configuration reference for BAMOE Canvas Helm Chart

The following table lists the configurable parameters of the BAMOE Canvas chart and their default values.

Key Type Default Description

global.ingressSource

string

""

Which ingress source is being used (none/"minikube"/"kubernetes"/"openshift") Obs.: For NOTES generation only

global.kubernetesClusterDomain

string

""

If using Minikube or Kubernetes, set the cluster domain

global.kubernetesIngressClass

string

""

If using Minikube or Kubernetes, set the Ingress class (i.e: nginx)

global.openshiftRouteDomain

string

""

If using OpenShift Routes, set the Route domain

fullnameOverride

string

""

Overrides charts full name

nameOverride

string

""

Overrides charts name

cors_proxy.autoscaling

object

{"enabled":false,"maxReplicas":100,"minReplicas":1,"targetCPUUtilizationPercentage":80}

CORS Proxy HorizontalPodAutoscaler configuration (https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)

cors_proxy.fullnameOverride

string

""

Overrides charts full name

cors_proxy.image

object

{"account":"kie-tools","name":"cors-proxy-image","pullPolicy":"IfNotPresent","registry":"quay.io","tag":"latest"}

Image source configuration for the CORS Proxy image

cors_proxy.imagePullSecrets

list

[]

Pull secrets used when pulling CORS Proxy image

cors_proxy.ingress

object

{"annotations":{},"className":"{{ .Values.global.kubernetesIngressClass }}","enabled":false,"hosts":[{"host":"cors-proxy.{{ .Values.global.kubernetesClusterDomain }}","paths":[{"path":"/","pathType":"ImplementationSpecific"}]}],"tls":[]}

CORS Proxy OpenShift Route configuration (https://docs.openshift.com/container-platform/4.14/networking/routes/route-configuration.html)

cors_proxy.name

string

"cors-proxy"

The CORS Proxy application name

cors_proxy.nameOverride

string

""

Overrides charts name

cors_proxy.openshiftRoute

object

{"annotations":{},"enabled":false,"host":"cors-proxy.{{ .Values.global.openshiftRouteDomain }}","tls":{"insecureEdgeTerminationPolicy":"None","termination":"edge"}}

CORS Proxy OpenShift Route configuration (https://docs.openshift.com/container-platform/4.14/networking/routes/route-configuration.html)

cors_proxy.service

object

{"nodePort":"","port":8080,"type":"ClusterIP"}

CORS Proxy Service configuration (https://kubernetes.io/docs/concepts/services-networking/service/)

cors_proxy.serviceAccount

object

{"annotations":{},"create":true,"name":""}

CORS Proxy ServiceAccount configuration (https://kubernetes.io/docs/concepts/security/service-accounts/)

extended_services.autoscaling

object

{"enabled":false,"maxReplicas":100,"minReplicas":1,"targetCPUUtilizationPercentage":80}

BAMOE Extended Services HorizontalPodAutoscaler configuration (https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)

extended_services.fullnameOverride

string

""

Overrides charts full name

extended_services.image

object

{"account":"bamoe","name":"extended-services","pullPolicy":"IfNotPresent","registry":"quay.io","tag":"9.2.1"}

Image source configuration for the BAMOE Extended Services image

extended_services.imagePullSecrets

list

[]

Pull secrets used when pulling BAMOE Extended Services image

extended_services.ingress

object

{"annotations":{},"className":"{{ .Values.global.kubernetesIngressClass }}","enabled":false,"hosts":[{"host":"extended-services.{{ .Values.global.kubernetesClusterDomain }}","paths":[{"path":"/","pathType":"ImplementationSpecific"}]}],"tls":[]}

BAMOE Extended Services Ingress configuration (https://kubernetes.io/docs/concepts/services-networking/ingress/)

extended_services.name

string

"extended-services"

The BAMOE Extended Services application name

extended_services.nameOverride

string

""

Overrides charts name

extended_services.openshiftRoute

object

{"annotations":{},"enabled":false,"host":"extended-services.{{ .Values.global.openshiftRouteDomain }}","tls":{"insecureEdgeTerminationPolicy":"None","termination":"edge"}}

BAMOE Extended Services OpenShift Route configuration (https://docs.openshift.com/container-platform/4.14/networking/routes/route-configuration.html)

extended_services.service

object

{"nodePort":"","port":21345,"type":"ClusterIP"}

BAMOE Extended Services Service configuration (https://kubernetes.io/docs/concepts/services-networking/service/)

extended_services.serviceAccount

object

{"annotations":{},"create":true,"name":""}

BAMOE Extended Services ServiceAccount configuration (https://kubernetes.io/docs/concepts/security/service-accounts/)

kie_sandbox.autoscaling

object

{"enabled":false,"maxReplicas":100,"minReplicas":1,"targetCPUUtilizationPercentage":80}

BAMOE Canvas HorizontalPodAutoscaler configuration (https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)

kie_sandbox.env

list

[{"name":"KIE_SANDBOX_EXTENDED_SERVICES_URL","value":"http://127.0.0.1:21345"},{"name":"KIE_SANDBOX_CORS_PROXY_URL","value":"http://127.0.0.1:8081"}]

Env variables for BAMOE Canvas deployment

kie_sandbox.fullnameOverride

string

""

Overrides charts full name

kie_sandbox.image

object

{"account":"bamoe","name":"canvas","pullPolicy":"IfNotPresent","registry":"quay.io","tag":"9.2.1"}

Image source configuration for the BAMOE Canvas image

kie_sandbox.imagePullSecrets

list

[]

Pull secrets used when pulling BAMOE Canvas image

kie_sandbox.ingress

object

{"annotations":{},"className":"{{ .Values.global.kubernetesIngressClass }}","enabled":false,"hosts":[{"host":"kie-sandbox.{{ .Values.global.kubernetesClusterDomain }}","paths":[{"path":"/","pathType":"ImplementationSpecific"}]}],"tls":[]}

BAMOE Canvas Ingress configuration (https://kubernetes.io/docs/concepts/services-networking/ingress/)

kie_sandbox.name

string

"kie_sandbox"

The BAMOE Canvas application name

kie_sandbox.nameOverride

string

""

Overrides charts name

kie_sandbox.openshiftRoute

object

{"annotations":{},"enabled":false,"host":"kie_sandbox.{{ .Values.global.openshiftRouteDomain }}","tls":{"insecureEdgeTerminationPolicy":"None","termination":"edge"}}

BAMOE Canvas OpenShift Route configuration (https://docs.openshift.com/container-platform/4.14/networking/routes/route-configuration.html)

kie_sandbox.service

object

{"nodePort":"","port":8080,"type":"ClusterIP"}

BAMOE Canvas Service configuration (https://kubernetes.io/docs/concepts/services-networking/service/)

kie_sandbox.serviceAccount

object

{"annotations":{},"create":true,"name":""}

BAMOE Canvas ServiceAccount configuration (https://kubernetes.io/docs/concepts/security/service-accounts/)