tackle2-ui

Overview

tackle2-ui is the web-based user interface for Konveyor, an open-source application modernization platform. It provides tools for assessing, analyzing, and migrating applications to Kubernetes. The UI is built with React and PatternFly, communicates with the Konveyor Hub REST API, and runs as a containerized Node.js application within the Konveyor operator deployment.

Key capabilities include application inventory management, assessment questionnaires, static code analysis, migration wave planning, dependency tracking, and issue/insight visualization.

Build and Test Status

branch	last merge CI	last merge image build	nightly CI
main
release-0.10
release-0.9

branch	last merge e2e CI	nightly e2e CI
main
release-0.10
release-0.9

Development

Prerequisites

• Node.js >= 22 (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

The dev server enables the agentic console by default. Against a Hub without the agentic API its pages fail on load; hide it with AGENTIC_ENABLED=false npm run start:dev (see Understanding the local development environment).

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.

Understanding the local development environment

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

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

• The server component, an express based nodejs server, handles the application code and proxies to the HUB backend via the /hub path and to the Hub's OIDC provider via the /oidc path.

• In production mode, the application code is served as statically built UI assets. A small handler inserts relevant environment information on the root page. This configures how the UI runs in the browser; the set of variables and their defaults is clientConfig in server/src/serverConfig.js, typed as ClientEnv in common/src/env-types.ts. The server's listener port is configurable via environment variables and defaults to :8080.

• In development mode, the application code is proxied to the client's webpack-dev-server running on port :9003. The server's listener port is configurable via environment variables and defaults to :9000.

• The server proxies server/src/proxies.js use the environment variable TACKLE_HUB_URL to define the proxy endpoint:

  • /hub → TACKLE_HUB_URL defines the location of the HUB REST endpoint. If it is not defined, the URL http://localhost:9002 is used by default.
  • /oidc → Proxied to the Hub's built-in OIDC provider (same target as /hub).

• The agentic console (agent runs, agents, skills, workflows) is feature-flagged and off by default. The server passes two variables to the browser with the rest of the environment:

  • AGENTIC_ENABLED → true shows the console. It needs a Hub that serves the /agentic/* API with an agentic-controller behind it; against any other Hub leave it off.
  • AGENTIC_STEER_ENABLED → true additionally lets you send free-text instructions to a live run and stop its turn from the chat panel. Off keeps the panel read-only (the agent's own questions can still be answered).

  Both default to false in production and to true under npm run start:dev. See ARCHITECTURE.md for what each flag gates.

Running the UI outside the cluster

To enable running the UI outside the cluster, port forwarding must be activated to route Konveyor 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 Konveyor services concurrently with starting the dev server.

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

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

Testing

Unit Tests

Run the unit test suites across the monorepo with:

npm run test

For more details on unit testing, see docs/tests.md.

End-to-End (E2E) Tests

The project includes Cypress-based end-to-end tests that validate the UI against a running Konveyor instance.

Quick start for running e2e tests against your local dev server:

# 1. Establish your own `.env` and prepare to run
npm clean-install
cp -i cypress/.env.example cypress/.env

# 2. Start your local dev server (in one terminal)
npm run start:dev

# 3. Run tests against localhost:9000 (in another terminal)
cd cypress
npm run e2e:run:local

Run tests against a different URL (run the prepare steps as above then):

# Against minikube
npm run e2e:run:minikube

# Against any URL
npm run e2e:run:local -- --config baseUrl=https://your-konveyor-instance.example.com

For comprehensive e2e testing documentation, including environment setup, test tags, CI integration, and QE workflows, see cypress/README.md.

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