diff --git a/README.md b/README.md index e40038f562..7a6b2adee6 100644 --- a/README.md +++ b/README.md @@ -6,28 +6,30 @@ Konveyor UI component # Build and Test Status -| branch | last merge CI | last merge image build | nightly CI | -| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| main | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Amain+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Amain+event%3Apush) | [![Nightly CI (repo level @main)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-repo.yaml/badge.svg?branch=main&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-repo.yaml?query=branch%3Amain+event%3Aschedule) | -| release-0.5 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.5+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.5+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.5&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.5+event%3Aschedule) | -| release-0.4 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.4+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.4+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.4&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.ymlquery=branch%3Arelease-0.4+event%3Aschedule) | -| release-0.3 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.3+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.3+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.3&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.3+event%3Aschedule) | - -| branch | last merge e2e CI | nightly e2e CI | -| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| main | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Amain+event%3Apush) | [![Nightly CI (global konveyor CI @main)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-global.yaml/badge.svg?branch=main&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-global.yaml?query=branch%3Amain+event%3Aschedule) | -| release-0.5 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.5+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.5&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.5+event%3Aschedule) | -| release-0.4 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.4+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.4&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.4+event%3Aschedule) | -| release-0.3 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.3+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.3&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.3+event%3Aschedule) | +| branch | last merge CI | last merge image build | nightly CI | +| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| main | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Amain+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Amain+event%3Apush) | [![Nightly CI (repo level @main)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-repo.yaml/badge.svg?branch=main&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-repo.yaml?query=branch%3Amain+event%3Aschedule) | +| release-0.5 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.5+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.5+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.5&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.5+event%3Aschedule) | +| release-0.4 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.4+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.4+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.4&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.ymlquery=branch%3Arelease-0.4+event%3Aschedule) | +| release-0.3 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.3+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.3+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.3&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.3+event%3Aschedule) | + +| branch | last merge e2e CI | nightly e2e CI | +| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| main | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Amain+event%3Apush) | [![Nightly CI (global konveyor CI @main)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-global.yaml/badge.svg?branch=main&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-global.yaml?query=branch%3Amain+event%3Aschedule) | +| release-0.5 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.5+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.5&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.5+event%3Aschedule) | +| release-0.4 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.4+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.4&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.4+event%3Aschedule) | +| release-0.3 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.3+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.3&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.3+event%3Aschedule) | # Development ## Prerequisites -- [NodeJS](https://nodejs.org/en/) >= 16.x -- [minikube](https://minikube.sigs.k8s.io/docs/start) (optional): setup your local minikube instance with your container manager of choice. (Docker, Hyperkit, Hyper-V, KVM, Parallels, Podman, VirtualBox, or VMware Fusion/Workstation.) +- [Node.js](https://nodejs.org/en/) >= 20 (see the `engines` block of [package.json](./package.json) for specifics) +- [minikube](https://minikube.sigs.k8s.io/docs/start) (optional): setup your local minikube instance with your container manager of choice -## Installation +## Quick start + +### Clone the repository To get started, clone the repo to your development workstation and install the required dependencies locally with NPM. @@ -37,126 +39,52 @@ cd tackle2-ui npm install ``` -## Quick start - -With an existing Tackle2 environment available, one can start a locally served tackle2-ui instance with: - -```sh -npm run start:dev -``` - -## Tackle2 environment setup - -With the UI project setup out of the way, you can now begin setting up you local Tackle2 dev environment. The preferred local development option is to setup a minikube instance. -Alternatively, for information on general Kubernetes installation refer to [Tackle2 operator readme](https://github.com/konveyor/tackle2-operator#readme) file. - -### Minikube setup - -[Minikube](https://github.com/kubernetes/minikube) implements a local Kubernetes cluster on macOS, Linux, and Windows. See the minikube getting started guide [here.](https://minikube.sigs.k8s.io/docs/start/) +### Connect to or setup a Konveyor instance -All you need to run minikube is [Docker](https://docs.docker.com/engine/install/) (or similarly compatible) container or a Virtual Machine environment. +- **Existing instance?** Make sure `kubectl` is configured to connect to the cluster where + the existing operator is deployed. -By default, Minikube uses a [driver](https://minikube.sigs.k8s.io/docs/drivers/) with 6,000 MB of memory and 2 CPUs. This is not enough to run all the services, so we need to increase the allocated memory. In our experience, 10 GB of memory and 4 CPUs is fine: +- **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](docs/local-minikube-setup.md). -```sh -$ minikube config set memory 10240 -$ minikube config set cpus 4 -``` +### Run the development server -Note: Depending on your driver, administrator access may be required. Common choices include Docker for container-based virtualization and KVM for hardware-assisted virtualization on Linux systems. If you're not sure which driver is best for you or if you're encountering compatibility issues, Minikube also supports auto-selecting a driver based on your system's capabilities and installed software. - -From a terminal run: +With an existing Konveyor environment available, and `kubectl` configured to use it, a local development server served tackle2-ui instance can be started with: ```sh -$ minikube start --addons=dashboard --addons=ingress -``` - -Note: We need to enable the dashboard and ingress addons. The dashboard addon installs the dashboard service that exposes the Kubernetes objects in a user interface. The ingress addon allows us to create Ingress CRs to expose the Tackle UI and Tackle Hub API. - -Since the olm addon is disabled until OLM issue [2534](https://github.com/operator-framework/operator-lifecycle-manager/issues/2534) is resolved we need to install the [OLM manually](https://github.com/operator-framework/operator-lifecycle-manager/releases) i.e. for version `v0.28.0` we can use: - -```sh -curl -L https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.28.0/install.sh -o install.sh -chmod +x install.sh -./install.sh v0.28.0 -``` - -See also official Konveyor instructions for [Provisioning Minikube](https://konveyor.github.io/konveyor/installation/#provisioning-minikube). - -### Configuring kubectl for minikube - -You will need `kubectl` on your PATH and configured to control minikube in order to proceed. There are two ways to set this up: - -1. **Install kubectl yourself** - - If you already [have the `kubectl` CLI tool installed](https://kubernetes.io/docs/tasks/tools/#kubectl) and available on your PATH, the `minikube start` command should configure it to control the minikube cluster. You should see the following message when minikube starts if this worked correctly: - - ``` - 🏄 Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default - ``` - -2. **Use a shell alias for minikube's built-in kubectl** - - Minikube provides its own internal `kubectl` which you can use by running `minikube kubectl --` followed by your CLI arguments. If you want to use the built-in `minikube kubectl` as the `kubectl` on your PATH, you can set a shell alias. The following example shows how to do it for Bash on Fedora 35. - - ```sh - $ mkdir -p ~/.bashrc.d - $ cat << EOF > ~/.bashrc.d/minikube - alias kubectl="minikube kubectl --" - EOF - $ source ~/.bashrc - ``` - -### Installing the Konveyor operator - -Follow the official instructions for [Installing Konveyor Operator](https://konveyor.github.io/konveyor/installation/#installing-konveyor-operator) - -Alternative 1, use the script [`hack/setup-operator.sh`](./hack/setup-operator.sh). It is a local variation of the script from the operator that still allows overriding portions of the Tackle CR with environment variables. - -Alternative 2, the [konveyor/operator git repository](https://github.com/konveyor/operator) provides a script to install Tackle locally using `kubectl`. You can [inspect its source here](https://github.com/konveyor/operator/blob/main/hack/install-tackle.sh). This script creates the `konveyor-tackle` namespace, CatalogSource, OperatorGroup, Subscription and Tackle CR, then waits for deployments to be ready. - -#### Customizing the install script (optional) - -The install script provides optional environment variables you can use to customize the images and features used. See [the source of the script](https://github.com/konveyor/operator/blob/main/hack/install-tackle.sh) for all available variables. - -For example, if you wish to run tackle with keycloak authentication enabled, export the following variable before running the install script: - -```sh -$ export AUTH_REQUIRED=true +npm run start:dev ``` -#### Running the install script - -Before proceeding, if you are on macOS you will need to use [Homebrew](https://brew.sh/) to install the `coreutils` package: +Your development server should start up and serve the locally running UI from: -```sh -$ brew install coreutils ``` - -To run the install script (requires `kubectl` on your PATH configured for minikube): - -```sh -$ curl https://raw.githubusercontent.com/konveyor/operator/main/hack/install-tackle.sh | bash +http://localhost:9000 ``` -Alternatively, you can clone the [konveyor/operator git repository](https://github.com/konveyor/operator) and run `./hack/install-tackle.sh` from your clone, or you can execute its commands manually. +## Konveyor environment setup -⚠️ Note: While CRDs are being established, you may see the script output `NotFound` errors. You can safely ignore these. The script will wait 30 seconds to check for the CRD again before proceeding. +Summary of tasks to setup a local environment: -The installation is complete when the script outputs "condition met" messages and terminates. +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](#run-the-development-server) -### Start your local development server +The most common and the recommended environment is to [setup minikube and deploy +the operator](ocs/local-minikube-setup.md) there. -Now that your environment is ready, navigate to your installed tackle-ui directory and run your development server: +A general guide for installing minikube and Konveyor is also available in the project +documentation [Installing Konveyor](https://konveyor.github.io/konveyor/installation). -```sh -$ cd tackle2-ui -$ npm run start:dev -``` +For information to help install on any Kubernetes platform see the +[Konveyor operator readme](https://github.com/konveyor/tackle2-operator#readme). ## Understanding the local development environment -Tackle2 runs in a Kubernetes compatible environment (i.e. Openshift, Kubernetes or minikube) and is usually 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. +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. @@ -196,28 +124,27 @@ $ 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 Kubernetes dashboard +## 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. The dashboard addon is enabled in the default in recommended `minikube start` -command in the [Minikube setup section](#minikube-setup). +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. +There are two ways to setup access to the dashboard: -First, 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: +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: -```sh -$ minikube dashboard --port=18080 --url=true -``` + ```sh + $ minikube dashboard --port=18080 --url=true + ``` -Second, we can use the `kubectl port-forward` command to enable access to the dashboard: +2. We can use the `kubectl port-forward` command to enable access to the dashboard: -```sh -$ kubectl port-forward svc/kubernetes-dashboard -n kubernetes-dashboard 30090:80 -``` + ```sh + $ kubectl port-forward svc/kubernetes-dashboard -n kubernetes-dashboard 30090:80 + ``` -We can now access the minikube dashboard on `http://localhost:30090` + We can now access the minikube dashboard on `http://localhost:30090` ## Troubleshooting @@ -241,12 +168,6 @@ Please read the [Pull Request (PR) Process](https://github.com/konveyor/release- section of the [Konveyor versioning and branching doc](https://github.com/konveyor/release-tools/blob/main/VERSIONING.md) for more information. -## File Naming Conventions - -- Use kebab-case for file names. -- The root page/parent level components are placed directly in their respective directories. -- Presentation layer components are placed within the `components/` subdirectory of the parent component. - # Contributing We welcome contributions to this project! If you're interested in contributing, diff --git a/development.md b/docs/development.md similarity index 93% rename from development.md rename to docs/development.md index 3ec657c916..ecf8dbc838 100644 --- a/development.md +++ b/docs/development.md @@ -6,6 +6,12 @@ This document describes the process for running and developing tackle2-ui on you Tackle2-ui can be developed using macOS(x86_64 only) or Linux environments. +## File Naming Conventions + +- Use kebab-case for file names. +- The root page/parent level components are placed directly in their respective directories. +- Presentation layer components are placed within the `components/` subdirectory of the parent component. + ## React hooks Our project utilizes [Hooks](https://reactjs.org/docs/hooks-intro.html) wherever possible as this pattern has been proven and settled on in the react community. The hooks pattern is highly testable and provides a clear way to reuse stateful logic without overcomplicating components with complex lifecycle methods. Overall, we have largely left class components behind and have adopted functional components / hooks as the way forward. @@ -17,7 +23,7 @@ For handling spacing/layout requirements that do not fit the standard PF mold, w ## Form development -We are using [react-hook-form](https://react-hook-form.com) in tandem with [patternfly](https://www.patternfly.org). Custom wrapper components have been developed to aid with this integration and their usage can be referenced in the [proxy-form](./client/src/app/pages/proxies/proxy-form.tsx) component. +We are using [react-hook-form](https://react-hook-form.com) in tandem with [patternfly](https://www.patternfly.org). Custom wrapper components have been developed to aid with this integration and their usage can be referenced in the [proxy-form](/client/src/app/pages/proxies/proxy-form.tsx) component. ### Steps to create a form @@ -62,5 +68,5 @@ export interface FormValues { For more info about working on the Tackle 2.x UI, check out these READMEs: -- [tests.md](./tests.md) -- [internationalization.md](./INTERNATIONALIZATION.md) +- [tests.md](/docs/tests.md) +- [internationalization.md](/INTERNATIONALIZATION.md) diff --git a/docs/local-minikube-setup.md b/docs/local-minikube-setup.md new file mode 100644 index 0000000000..ff732a5a6c --- /dev/null +++ b/docs/local-minikube-setup.md @@ -0,0 +1,237 @@ +# Setting up Konveyor on a local minikube instance + +The preferred local development for the tackle2-ui is to install the Konveyor +operator on a minikube instance. When the operator is installed and running, +the UI development server can attach to it and use the operator's hub api. There +will also be a running UI instance to work with. + +The setup process follows the general steps: + +- install minikube +- start minikube with the **dashboard** and **ingress** addons +- install the operator framework (OLM) +- install the Konveyor operator +- optionally add test data + +## Install and start minikube + +[Minikube](https://github.com/kubernetes/minikube) implements a local Kubernetes cluster +and is available on macOS, Linux, and Windows. All you need to run minikube is a container +runtime ([Docker](https://docs.docker.com/engine/install/) or [podman](https://podman.io/docs/installation)) +or a Virtual Machine environment. + +See the minikube [getting started guide](https://minikube.sigs.k8s.io/docs/start/) for install +details for your platform. + +By default, Minikube uses a [driver](https://minikube.sigs.k8s.io/docs/drivers/) with 6 GB +of memory and 2 CPUs. This may not be enough to run all the services, so we need to increase +the allocated memory. In our experience, 10 GB of memory and 4 CPUs is fine: + +```sh +minikube config set memory 10240 +minikube config set cpus 4 +``` + +> [!IMPORTANT] +> Depending on your driver, administrator access may be required. Common driver choices are +> Docker for container-based virtualization and KVM for hardware-assisted virtualization on Linux +> systems. If you're not sure which driver is best for you or if you're encountering compatibility +> issues, minikube supports auto-selecting a driver based on your system's capabilities and +> installed software. + +Start minikube with the command: + +```sh +minikube start --addons=dashboard --addons=ingress +``` + +> [!NOTE] +> We need to enable the **dashboard** and **ingress** addons. The dashboard addon installs +> the dashboard service that provides a web UI for the Kubernetes objects. The ingress addon +> allows us to create Ingress CRs to expose the Tackle UI and Tackle Hub API. + +## Install OLM + +Since Konveyor is deployed as an operator, the [operator framework](https://operatorframework.io/)'s +[operator lifecycle manager (OLM)](https://olm.operatorframework.io/) needs to be installed +on our new minikube instance before installing the Konveyor operator. + +Since the minikube olm addon is disabled until OLM issue +[2534](https://github.com/operator-framework/operator-lifecycle-manager/issues/2534) +is resolved we need to install the [OLM manually](https://github.com/operator-framework/operator-lifecycle-manager/releases). + +For version `v0.28.0` (latest version as of 17-May-2024) use the scripts: + +```sh +curl -L https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.28.0/install.sh -o install.sh +chmod +x install.sh +./install.sh v0.28.0 +``` + +## Install the Konveyor Operator + +There are a few good ways to install the Konveyor operator: + +- Use the script [`hack/setup-operator.sh`](/hack/setup-operator.sh). It is a local variation of + the script from the operator that applies all CRs needed to install the Konveyor operator and + setup the Tackle instance. Use of this script is described in the next section. + +- Follow the official instructions for [Installing Konveyor Operator](https://konveyor.github.io/konveyor/installation/#installing-konveyor-operator) + +- Use one of the `hack/install-*` scripts in the [konveyor/operator](https://github.com/konveyor/operator) + repository. These scripts require `kubectl` and the `operator-sdk`. + +### Running the setup script + +To run the setup script without cloning the repo, make sure the `kubectl` command (not alias) +is working and configured for minikube instance, and that the bash shell is available: + +```sh +curl https://raw.githubusercontent.com/konveyor/tackle2-ui/main/hack/setup-operator.sh -o setup-operator.sh +chmod +x setup-operator.sh +./setup-operator.sh +``` + +You may also run the script directly from you tackle2-ui clone: + +```sh +cd tackle2-ui/hack +./setup-operator.sh +``` + +> [!WARNING] +> While CRDs are being established, you may see the script output `NotFound` errors. +> You can safely ignore these. The script will wait and recheck for the CRD again before +> proceeding. + +The installation is complete when the script outputs "condition met" messages and terminates. + +### Customizing the setup script + +The setup script provides optional environment variables that may be used to customize the +images used, settings, and features enabled during the install. + +Configuration environment variable include: +| variable | default | description | +| --- | --- | --- | +| TACKLE*CR | *(empty)\_ | Allows specifying the full Tackle CR | +| ADDON_ANALYZER_IMAGE | quay.io/konveyor/tackle2-addon-analyzer:latest | image for the ADDON_ANALYZER pod | +| ANALYZER_CONTAINER_REQUESTS_CPU | 0 | cpu count for the analyzer (0 is no restriction) | +| ANALYZER_CONTAINER_REQUESTS_MEMORY | 0 | memory size for the analyzer (0 is no restriction) | +| FEATURE_AUTH_REQUIRED | false | include keycloak SSO in operator deployment | +| HUB_BUCKET_VOLUME_SIZE | 100Gi | PV claim size for the HUB buckets | +| HUB_DATABASE_VOLUME_SIZE | 10Gi | PV claim size for the HUB database | +| HUB_IMAGE | quay.io/konveyor/tackle2-hub:lates | image for the HUB pod | +| IMAGE_PULL_POLICY | Always | When should images needed by the operator be pulled **link to docs for the pull policy** | +| NAMESPACE | konveyor-tackle | kubernetes namespace used | +| OPERATOR_INDEX_IMAGE | quay.io/konveyor/tackle2-operator-index:latest | base operator container image | +| UI_IMAGE | quay.io/konveyor/tackle2-ui:latest | image for the UI pod | +| UI_INGRESS_CLASS_NAME | nginx | nginx is the used as the ingress for minikube to access the UI | + +For example, if you wish to run tackle with keycloak authentication enabled, export the following variable before running the install script: + +```sh +export FEATURE_AUTH_REQUIRED=true +./setup-operator.sh +``` + +If the `TACKLE_CR` variable is defined, its contents will be used to create the `Tackle` +instance in lieu of one built in the script based on the other config variables. For +example, this will create a Tackle instance with authentication turned on and the UI +using a specially built test image: + +```sh +export TACKLE_CR=$(cat < ~/.bashrc.d/minikube + alias kubectl="minikube kubectl --" + EOF + source ~/.bashrc + ``` + + > [!WARNING] + > The alias will only work for an interactive shell. If you want to use `minikube kubectl --` + > as the command in scripts, you'll need to use a shim shell script. + +3. **Use a shim shell script to route kubectl to minikube** + + To be able to use `minikube kubectl --` as the command `kubectl` in general use (interactive + prompt and in other scripts), a simple shell script can be used. Any location that is in + the `$PATH` can be used. Installing for all system users can typically be done to `/usr/local/bin`: + + ```sh + cat << EOF > kubectl.sh + #! /usr/bin/env bash + minikube kubectl -- $@ + EOF + sudo install -m 777 kubectl.sh /usr/local/bin/kubectl + ``` + +## Starting Over + +If at any point your minikube Konveyor operator instance stops working properly, it +is simple to destroy the environment and rebuild. + +To destroy an existing minikube instance (with Konveyor installed): + +```sh +minikube stop +minikube delete +``` + +Rebuild by starting a new instance of minikube and following the rest of the +install steps in this document. diff --git a/tests.md b/docs/tests.md similarity index 100% rename from tests.md rename to docs/tests.md diff --git a/hack/README.md b/hack/README.md index 718857ef78..85e1488018 100644 --- a/hack/README.md +++ b/hack/README.md @@ -7,13 +7,13 @@ creating/importing various pieces of data. For creating a base set of data in a tackle-hub instance, a good place to start is [tackle-hub's hack folder](https://github.com/konveyor/tackle2-hub/tree/main/hack). -If you have hub running or port forwarded on port :9002, a basic set of data can be -added to the instance by: +If you have the Konveyor operator running on minikube without authentication, a basic +set of data can be added to the instance by: ```sh -> git clone https://github.com/konveyor/tackle2-hub.git -> cd tackle2-hub/hack -> HOST=localhost:9002 ./add/all.sh +git clone https://github.com/konveyor/tackle2-hub.git +cd tackle2-hub/hack +HOST=http://$(minikube ip)/hub ./add/all.sh ``` ## Useful commands diff --git a/hack/wsl/README.md b/hack/wsl/README.md new file mode 100644 index 0000000000..2bbed7923a --- /dev/null +++ b/hack/wsl/README.md @@ -0,0 +1,213 @@ +# Konveyor on Windows + +Running Konveyor on Windows has the same basic requirements as running +on Linux or Mac: + +- A kubernetes / minikube instance +- OLM installed on the instance to be able to use Operators + +Minikube needs to run on top of a container platform. There are multiple ways to set +that up (see [minikube drivers](https://minikube.sigs.k8s.io/docs/drivers/)). A +recommended approach is to use a docker or podman container runtime running on top of +WSL. There are various way to achieve this, but one way that was found to work is +described below. + +> [!NOTE] +> Note: Installing a fedora distribution to WSL and then setting up an environment +> directly on that distribution is possible. This most likely involves nested +> virtualization and may require additional network configurations to run correctly. + +General steps to get going: + +- Install [the windows binary of minikube](#minikube) +- Install [a container runtime](#container-runtime) (docker or podman) on top of the WSL +- Start/create a [minikube instance](#start-a-minikube-instance) +- [Configure your default WSL](#configure-the-default-wsl) instance to: + - be able to download and run bash scripts + - use the `minikube` installed to windows + - map the `kubectl` command to use the `minikube kubectl --` command. This is needed + to be able to run the normal OLM and Konveyor install scripts. +- Install [OLM](#install-olm-on-minikube) +- Install [Konveyor](#install-konveyor-operator-on-minikube) +- Finally, [access the Konveyor UI](#accessing-the-ui-running-on-minikube) + +## Installing + +### Minikube + +Install page: https://minikube.sigs.k8s.io/docs/start + +- Download the [latest release of the Windows stable .exe download](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fwindows%2Fx86-64%2Fstable%2F.exe+download) +- Run the installer (no changes to the default options are needed) + +Alternatively, Minikube can be installed from podman desktop: https://podman-desktop.io/docs/minikube + +### Container Runtime + +Podman desktop or docker desktop can be used to setup WSL and a base +container runtime environment. Podman desktop allows for easy installation +of minikube from within its GUI. + +Both docker desktop and podman desktop can be installed, but really just pick one. + +#### Podman Desktop + +Install page: https://podman-desktop.io/docs/installation/windows-install + +The install has a few extra options to help setup WSL, the podman runtime[^1], and other +tools that I found more useful than Docker Desktop. + +[^1]: Standard install of podman on windows: https://podman.io/docs/installation#windows + +#### Docker Desktop + +Install page: https://www.docker.com/products/docker-desktop/ + +Note: After installing, you'll either need to sign in to docker or hit skip a +bunch of times to start using docker. If this is annoying, Podman Desktop doesn't +do that. + +## Start a minikube instance + +General configuration and startup of a minikube instance is covered +[local minikube setup](/docs/local-minikube-setup.md#install-and-start-minikube). +However, on windows it is helpful to explicitly configure the driver to use based on what +container runtime you installed. **Assuming you installed the windows binaries for +minikube, these command should be run in a normal windows Command Prompt.** Sample +commands assuming you have podman installed (substitute podman for any other driver, +such as docker, as needed): + +``` +minikube start --addons=dashboard --addons=ingress --driver=podman +``` + +If a minikube instance already exists but doesn't have the needed addons, they can +be enabled individually: + +``` +minikube addons enable dashboard +minikube addons enable ingress +``` + +## Configure the default WSL + +No matter what distribution is setup as default on your WSL environment, it probably +needs additional configurations to be able to run windows binaries, bash scripts, +minikube and kubectl + +### Configuring the Docker Desktop WSL distribution + +Docker desktop's WSL instance appears to use a version of alpine linux, so curl and +bash probably need to be installed manually. To install them, from the WSL prompt +run: + +``` +apk add curl bash +``` + +### Configuring the podman machine WSL distribution + +The podman WSL distribution is based on fedora so curl and bash should already be +available. + +The distribution may need extra configurations to be able to invoke windows binaries. +To verify windows binaries can be called, from the podman WSL instance (which should +be the default if only podman / podman desktop is installed), run the command + +``` +/mnt/c/Windows/System32/notepad.exe +``` + +If the notepad application opens, everything is ok. + +If an error occurs, the distribution needs to be reconfigured[^2]: + +- from the WSL command line run: + + ``` + sudo sh -c 'echo :WSLInterop:M::MZ::/init:PF > /usr/lib/binfmt.d/WSLInterop.conf' + ``` + +- Exit the shell + +- Either reboot or from the windows command prompt run: + + ``` + wsl --shutdown + ``` + +- Open the WSL shell and try running notepad again. It should work this time. + +[^2]: See this github comment: https://github.com/microsoft/WSL/issues/8843#issuecomment-1459120198 + + + +### Setting up the WSL instance to run the windows version of minikube / kubectl + +Installing minikube as a windows binary has advantages, but for the OLM and Konveyor +install scripts to work unmodified, the most reliable way I found is to use a pair +of shell scripts. These scripts will then call the installed windows binary. + +The scripts should be copied into a folder listed in the `$PATH`. Typically +the path `/usr/local/bin` is included and is a good location to put the scripts. + +- Install a [shell script for `minikube`](shim_scripts/minikube.sh) to call the installed + windows binary: + + ``` + curl https://raw.githubusercontent.com/konveyor/tackle2-ui/main/hack/wsl/shim_scripts/minikube.sh + sudo install -m 777 minikube.sh /usr/local/bin/minikube + ``` + +- Install a [shell script for `kubectl`](shim_scripts/kubectl.sh) to use the kubectl + embedded in minikube `minikube kubectl --`: + + ``` + curl https://raw.githubusercontent.com/konveyor/tackle2-ui/main/hack/wsl/shim_scripts/kubectl.sh + sudo install -m 777 kubectl.sh /usr/local/bin/kubectl + ``` + +- Test that minikube and kubectl are working: + ``` + minikube profile list + kubectl cluster-info + ``` + +## Install OLM on minikube + +Follow the normal OLM install process in +[local minikube setup](/docs/local-minikube-setup.md#install-olm) docs, but run the +commands in the WSL shell. + +## Install Konveyor Operator on minikube + +Follow the normal Konveyor operator install process in +[local minikube setup](/docs/local-minikube-setup.md#install-the-konveyor-operator) docs, +but run the commands in the WSL shell. + +## Accessing the UI running on minikube + +Looking at the [Ingress option of the deploy applications](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fwindows%2Fx86-64%2Fstable%2F.exe+download#Ingress) +step in the minikube get started guide, there is a note for Docker Desktop Users: + +> To get ingress to work you'll need to open a new terminal window and run minikube +> tunnel and in the following step use 127.0.0.1 in place of . + +I also found this to be true using podman desktop. + +Using `minikube tunnel` to have the tackle service exposed on localhost should work. +Open a new command prompt window and run (the window will need to remain open for +the tunnel to stay open): + +``` +minikube tunnel +``` + +Once the tunnel is running, Konveyor will be available at `http://127.0.0.1/`. diff --git a/hack/wsl/shim_scripts/kubectl.sh b/hack/wsl/shim_scripts/kubectl.sh new file mode 100644 index 0000000000..1ed2a6604a --- /dev/null +++ b/hack/wsl/shim_scripts/kubectl.sh @@ -0,0 +1,2 @@ +#! /usr/bin/env bash +minikube kubectl -- $@ diff --git a/hack/wsl/shim_scripts/minikube.sh b/hack/wsl/shim_scripts/minikube.sh new file mode 100644 index 0000000000..a5a5b683c6 --- /dev/null +++ b/hack/wsl/shim_scripts/minikube.sh @@ -0,0 +1,25 @@ +#! /usr/bin/env bash +TARGET=/usr/local/bin + +if [ ! -e "$TARGET/minikube.exe" ]; then + [[ $(id -u) -ne 0 ]] && SUDO=sudo || SUDO= + + roots=( + "/mnt/c/Users/*/AppData/Local/Microsoft/WindowsApps" + "/mnt/c/Program Files/Kubernetes/Minikube" + "/mnt/host/c/Users/*/AppData/Local/Microsoft/WindowsApps" + "/mnt/host/c/Program Files/Kubernetes/Minikube" + ) + + shopt -s nullglob + IFS=$'\n' + for root in $roots; do + if [ -e "${root}/minikube.exe" ]; then + echo "linking to ${root}/minikube.exe" + $SUDO ln -s "${root}/minikube.exe" "$TARGET/minikube.exe" + break + fi + done +fi + +minikube.exe $@