BAMOE Canvas is a web application that provides authoring tools for Decisions and Workflows, directly in the browser. It allows users to create, edit and manage Decisions and Workflows, by providing editors and other tools, such as Git integration for syncing repositories, OpenShift and Kubernetes integration for deploying your files, and much more.

It depends on two backend applications to reach its full potential:

  • Extended Services: This powers features like DMN Runner, static validation of DMN, BPMN models, and also provides a proxy to communicate with OpenShift and Kubernetes clusters.

  • Git CORS Proxy: Provides a proxy to allow BAMOE Canvas web app to communicate with Git providers, like github.com and bitbucket.org.

BAMOE Canvas itself, as well as 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 in any cloud provider.

Note
 The exact same version needs to be used for a deployment with these three images to work.

Deploying BAMOE Canvas to OpenShift

If you have a 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 much 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_GIT_CORS_PROXY=bamoe-git-cors-proxy
export APP_NAME_BAMOE_CANVAS=bamoe-canvas

  2. Deploy Extended Services and label its resources

    oc new-app quay.io/bamoe/extended-services:9.0.1 --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 Git CORS Proxy and label its resources

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

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

    oc new-app quay.io/bamoe/canvas:9.0.1 --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_GIT_CORS_PROXY_URL=https://$(oc get route $APP_NAME_GIT_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’re deploying them to a local OpenShift instance (i.e. via CRC), the BAMOE Canvas web app, the Extended Services and Git 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.

Installing and configuring BAMOE Canvas images manually via Docker

Configuring Extended Services

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

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

Configuring Git CORS Proxy

docker run -p 8090:8080 -it quay.io/bamoe/git-cors-proxy:9.0.1
# 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 Canvas

In particular, this image needs to be run with two environment variables that will allow it to communicate with its backend services:

KIE_SANDBOX_EXTENDED_SERVICES_URL

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

KIE_SANDBOX_GIT_CORS_PROXY_URL

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

If you’re running locally, following the previous steps, use this command to start you 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_GIT_CORS_PROXY_URL=http://localhost:8090 \
  quay.io/bamoe/canvas:9.0.1
# Add the -d flag to run in detached mode.

The HTTP server is accessed via port 8080.

Several customization options are available. Check more configurations available via environment variables here: https://quay.io/repository/bamoe/canvas?tab=info

Note

Those addresses need to be accessible from the users' machines, as BAMOE Canvas will communicate with 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_DMN_DEV_DEPLOYMENT_BASE_IMAGE_URL.

This environment variable points to a container image that is used when creating a Dev deployment for Decisions.

By default, BAMOE Canvas is configured to fetch this image from https://quay.io/repository/kie-tools/dmn-dev-deployment-base-image @ 0.30.4

Important

The pre-configured image is NOT part of BAMOE, and comes from the open-source KIE community. People installing BAMOE Canvas must change KIE_SANDBOX_DMN_DEV_DEPLOYMENT_BASE_IMAGE_URL to make sure the used image meets their requirements. For a reference on how to build your own image that is compatible with BAMOE Canvas Dev deployments, please go to the KIE community’s source code for dmn-dev-deployment-base-image at https://github.com/kiegroup/kie-tools/tree/0.30.4/packages/dmn-dev-deployment-base-image

If you’re installing BAMOE Canvas to an air-gapped environment, you’re going to need to configure KIE_SANDBOX_DMN_DEV_DEPLOYMENT_BASE_IMAGE_URL to point to an image in a registry where the Cloud providers used by BAMOE Canvas users can access.

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_DMN_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, please refer to the image’s description.

Other installation methods

BAMOE Canvas can also be deployed via Docker Compose, check out our tutorial here: Docker Compose.

Securing your Installation

It’s highly recommended to have a secure protocol (HTTPS) available for the BAMOE Canvas installation. To enable that, please follow your Kubernetes distribution documentation on how to enable it.

It’s also recommended for all services that BAMOE Canvas will have access to, like remote git repositories or container orchestration like OpenShift, to have all access tokens have a token expiration policy.