tackle2-ui

Konveyor UI component

Build and Test Status

branch	last merge CI	last merge image build	nightly CI
main
release-0.5
release-0.4
release-0.3

branch	last merge e2e CI	nightly e2e CI
main
release-0.5
release-0.4
release-0.3

Development

Prerequisites

• Node.js >= 20 (see the engines block of package.json for specifics)
• minikube (optional): setup your local minikube instance with your container manager of choice

Quick start

Clone the repository

To get started, clone the repo to your development workstation and install the required dependencies locally with NPM.

git clone https://github.com/konveyor/tackle2-ui
cd tackle2-ui
npm install

Connect to or setup a Konveyor instance

• Existing instance? Make sure kubectl is configured to connect to the cluster where the existing operator is deployed.

• New instance? The process for setting up a Konveyor operator to run on a local Kubernetes cluster via minikube is detailed in the local setup document.

Run the development server

With an existing Konveyor environment available, and kubectl configured to use it, a local development server served tackle2-ui instance can be started with:

npm run start:dev

Your development server should start up and serve the locally running UI from:

http://localhost:9000

Konveyor environment setup

Summary of tasks to setup a local environment:

1. Setup an kubernetes instance with OLM to support the Konveyor operator
2. Install the Konveyor operator
3. Create the Konveyor CR
4. Run your local dev server

The most common and the recommended environment is to setup minikube and deploy the operator there.

A general guide for installing minikube and Konveyor is also available in the project documentation Installing Konveyor.

For information to help install on any Kubernetes platform see the Konveyor operator readme.

Understanding the local development environment

Konveyor runs in a Kubernetes compatible environment (e.g. Openshift, Kubernetes or minikube) and is typically deployed with Tackle2 Operator (OLM). Although the UI pod has access to tackle2 APIs from within the cluster, the UI can also be executed outside the cluster and access Tackle APIs endpoints by proxy.

The React and Patternfly based UI is composed of web pages served by an http server with proxy capabilities.

• In production mode, Express (Node.js) plays the role of both UI server and proxy server (using http-proxy-middleware). Everything is served on port 8080. The /auth and /hub routes are proxied to their services. All other routes serve the UI bundle where they are handled by react-router.

• In development mode, webpack-dev-server plays the role of UI server and Express plays the role of proxy server only. This allows webpack-dev-server to provide development features such as hot reload. The webpack-dev-server serves the UI on port 9000. The /auth and /hub routes are forwarded to port 8080 for Express to handle.

The Express server/src/setupProxy.js proxies use the environment variables TACKLE_HUB_URL and SSO_SERVER_URL to define the backend endpoints:

• If the Tackle Hub variable TACKLE_HUB_URL is not defined, the URL http://localhost:9002 is used by default.

• If the Tackle Keycloak (SSO) variable SSO_SERVER_URL is not defined, the URL http://localhost:9001 is used by default.

Running the UI outside the cluster

To enable running the UI outside the cluster, port forwardings must be activated to route the Tackle Keycloak (SSO) and Tackle Hub requests to the services on the cluster. Use the script npm run port-forward to easily start the forwards. The script npm run start:dev will also setup port forwarding to all tackle2 services concurrently with starting the dev server.

To manually setup the kubectl port forwards, open a terminal and run each following command separately:

$ kubectl port-forward svc/tackle-keycloak-sso -n konveyor-tackle 9001:8080
$ kubectl port-forward svc/tackle-hub -n konveyor-tackle 9002:8080

Note: The npm run port-forward or kubectl port-forward commands need to remain running for the ports to be available.

Accessing the Minikube Kubernetes dashboard

We may need to access the dashboard, either simply to see what's happening under the hood, or to troubleshoot an issue.

There are two ways to setup access to the dashboard:

1. We can use the minikube dashboard command. Use to following to open on an explicit port and only show the URL instead of opening the default browser directly:

   $ minikube dashboard --port=18080 --url=true

2. We can use the kubectl port-forward command to enable access to the dashboard:

   $ kubectl port-forward svc/kubernetes-dashboard -n kubernetes-dashboard 30090:80

   We can now access the minikube dashboard on http://localhost:30090

Troubleshooting

Note - The steps described are executed on a Fedora 38 workstation, but will likely work on any recent Linux distribution.

• For minikube setups that rely on virtualization, the only prerequisites are to enable virtualization extensions in the BIOS/EFI of the machine, to install libvirt and to add our user to the libvirt group.

• Ensure that your minikube installation directory is available in your $PATH environment variable. This is usually /usr/local/bin/ or something similar depending on your OS of choice.

• The following command gives us the IP address assigned to the node created by Minikube. It's used when interacting with tackle UI image installed on the minikube cluster.

$ minikube ip
192.168.39.23

Pull Request (PR) Process

Please read the Pull Request (PR) Process section of the Konveyor versioning and branching doc for more information.

Contributing

We welcome contributions to this project! If you're interested in contributing, please read the konveyor/community CONTRIBUTING doc for more information on how to get started.

Code of Conduct

Refer to Konveyor's Code of Conduct page