Skip to content

Commit

Permalink
📖 Update developer documentation (#1726)
Browse files Browse the repository at this point in the history 
Changes:
1. fix dead links i.e. to PF4 components or refactored code
2.  in README 
     1. OLM addon issue
2. be more general about minikube drivers i.e. rootless or without VMs
3. prefer port forwarding to proxy when accessing dashboard (seems
safer)
3. in INTERNATIONALIZATION - comment that questionnaire is data imported
from YAML files

---------

Signed-off-by: Radoslaw Szwajkowski <[email protected]>
Signed-off-by: Radoslaw Szwajkowski <[email protected]>
Co-authored-by: Ian Bolton <[email protected]>
  • Loading branch information
@rszwajko @ibolton336
rszwajko and ibolton336 authored Mar 11, 2024
1 parent ad90cd5 commit 6b805b5
Show file tree
Hide file tree
Showing 3 changed files with 38 additions and 27 deletions.
8 changes: 4 additions & 4 deletions INTERNATIONALIZATION.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,17 +25,17 @@ locales: ["en", "es", "myLanguageCode"]
npm extract
```

The previous command created a file `public/locales/{myLanguageCode}/translation.json`; the content of this file should be the translated new language. As a reference you can use the english version of the translation located at [public/locales/en/translation.json](https://github.com/konveyor/tackle-ui/blob/main/public/locales/en/translation.json)
The previous command created a file `public/locales/{myLanguageCode}/translation.json`; the content of this file should be the translated new language. As a reference you can use the english version of the translation located at [public/locales/en/translation.json](https://github.com/konveyor/tackle2-ui/blob/main/client/public/locales/en/translation.json)

> As soon as you feel confident, open a new Pull Request with your changes and make it part of the official repository.
## How to see the new translation in action?

To see your changes in action you will need to start Tackle UI in development mode. For starting Tackle UI in development mode follow the instruction at [Starting the UI](https://github.com/konveyor/tackle-ui#starting-the-ui)
To see your changes in action you will need to start Tackle UI in development mode. For starting Tackle UI in development mode follow the instruction at [Development section](https://github.com/konveyor/tackle2-ui/blob/main/README.md#development)

Steps:

- Start Tackle UI in dev mode following [Starting the UI](https://github.com/konveyor/tackle-ui#starting-the-ui) instructions.
- Start Tackle UI in dev mode following the instructions in the [Development section](https://github.com/konveyor/tackle2-ui/blob/main/README.md#development).
- Go to Keycloak http://localhost:8180/auth/admin/ and use `username=admin, password=admin`. Go to `Realm settings > themes > Supported locales` and select the new language you are adding. Finally click on `Save`.
- Go to http://localhost:3000/ and you should be redirected to the Login page where you are able to select your new language.

Expand All @@ -45,4 +45,4 @@ At this point you should be able to see your new language already translated int
## Why the questionnaire (assessment process) is not translated?

The questionnaire is data comming from https://github.com/konveyor/tackle-pathfinder hence the translation to a new language of the questionnaire should be done in that repository.
To accommodate diverse user needs, including internationalization, our custom assessment module supports the uploading of YAML files. This flexibility allows for the easy adaptation of assessments to different languages or specific requirements. If you're looking to offer assessments in a new language, simply create and upload a YAML file tailored to that language.
41 changes: 26 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,13 +49,25 @@ $ minikube config set memory 10240
$ minikube config set cpus 4
```

From a terminal with administrator access (but not logged in as root), run:
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:

```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.27.0` we can use:

```sh
$ minikube start --addons=dashboard --addons=ingress --addons=olm
curl -L https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.27.0/install.sh -o install.sh
chmod +x install.sh
./install.sh v0.27.0
```

Note: We need to enable the dashboard, ingress and olm 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. The olm addon allows us to use an operator to deploy Tackle.
See also official Konveyor instructions for [Provisioning Minikube](https://konveyor.github.io/konveyor/installation/#provisioning-minikube).

### Configuring kubectl for minikube

Expand Down Expand Up @@ -83,7 +95,9 @@ You will need `kubectl` on your PATH and configured to control minikube in order
### Installing the Konveyor operator
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.
Follow the official instructions for [Installing Konveyor Operator](https://konveyor.github.io/konveyor/installation/#installing-konveyor-operator)
Alternatively, 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)
Expand Down Expand Up @@ -126,7 +140,7 @@ $ npm run start:dev
## Understanding the local development environment
Tackle2 runs in a Kubernetes compatible environment (Openshift, Kubernetes or minikube) and is usually deployed with Tackle2 Operator (OLM).
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.
The React and Patternfly based UI is composed of web pages served by an http server with proxy capabilities.
Expand Down Expand Up @@ -182,26 +196,23 @@ port and only show the URL instead of opening the default browser directly:
$ minikube dashboard --port=18080 --url=true
```
Second, we can use the `kubectl proxy` command to enable access to the dashboard. The following
command sets up the proxy to listen on any network interface (useful for remote access), to the
18080/tcp port (easy to remember), and with requests filtering disabled (less secure, but necessary):
Second, we can use the `kubectl port-forward` command to enable access to the dashboard:
```sh
$ kubectl proxy --address=0.0.0.0 --port 18080 --disable-filter=true
$ kubectl port-forward svc/kubernetes-dashboard -n kubernetes-dashboard 30090:80
```
We can now access the minikube dashboard through the proxy. Use the following URL as a template,
replacing the IP address with your workstation IP address:
`http://192.168.0.1:18080/api/v1/namespaces/kubernetes-dashboard/services/http:kubernetes-dashboard:/proxy/#/`
We can now access the minikube dashboard on `http://localhost:30090`
## Troubleshooting
Note - The steps described are executed on a Fedora 35 workstation, but will likely work on any recent Linux distribution.
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.
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 virtual machine created by Minikube.
- 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.
```sh
Expand Down
16 changes: 8 additions & 8 deletions development.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,11 @@ Our project utilizes [Hooks](https://reactjs.org/docs/hooks-intro.html) wherever
## Styling components

For any custom styles, we use standard css with no preprocessors. If a custom style is needed, create a css file and import it within the component.
For handling spacing/layout requirements that do not fit the standard PF mold, we are able to use the [Patternfly spacing utility classes](https://www.patternfly.org/v4/utilities/spacing).
For handling spacing/layout requirements that do not fit the standard PF mold, we are able to use the [Patternfly spacing utility classes](https://www.patternfly.org/utility-classes/spacing/).

## Form development

We are using [react-hook-form](https://react-hook-form.com) in tandem with [patternfly](https://www.patternfly.org/v4/). 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

Expand All @@ -41,22 +41,22 @@ export interface FormValues {

- Note: `watch` will not be needed if you are using least one controlled input field via our controller components below since the presence of a controlled input will cause RHF to auto-watch the form values anyway.

- Write an onSubmit function of type `SubmitHandler<YourValuesInterface>`. Wrap your form fields in a PF `<Form>` component with `onSubmit={handleSubmit(onSubmit)}` where `handleSubmit` came from your `useForm` call. That's where you'll eventually want to do the submit logic, probably using [mutations](https://tanstack.com/query/v4/docs/guides/mutations) from react-query.
- Write an onSubmit function of type `SubmitHandler<YourValuesInterface>`. Wrap your form fields in a PF `<Form>` component with `onSubmit={handleSubmit(onSubmit)}` where `handleSubmit` came from your `useForm` call. That's where you'll eventually want to do the submit logic, probably using [mutations](https://tanstack.com/query/v4/docs/framework/react/guides/mutations) from react-query.

### react-hook-form / wrapper component usage

- Now you can use our new components for the fields themselves. They will take care of rendering the PF FormGroups and properly styled validation errors. Pass them the `control` prop from your `useForm` call and a name string prop matching the field name key from your form values object. TS is smart enough to infer the right field value type from those 2 props.

- If you're rendering a basic text input, you can use `HookFormPFTextInput` ([source](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/shared/components/hook-form-pf-fields/hook-form-pf-text-area.tsx), [example](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/pages/proxies/proxy-form.tsx#L372-L378)). It extends the props of PatternFly's [TextInput](https://www.patternfly.org/v4/components/text-input), so you can pass whatever extra stuff you need directly into it.
- If you're rendering a basic text input, you can use `HookFormPFTextInput` ([source](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/components/HookFormPFFields/HookFormPFTextInput.tsx), [example](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/pages/proxies/proxy-form.tsx)). It extends the props of PatternFly's [TextInput](https://www.patternfly.org/components/forms/text-input/#textinput), so you can pass whatever extra stuff you need directly into it.

- Same for a multi-line textarea, you can use `HookFormPFTextArea` ([source](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/shared/components/hook-form-pf-fields/hook-form-pf-group-controller.tsx), [example](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/pages/proxies/proxy-form.tsx#L257-L282)) which extends the props of PF [TextArea](https://www.patternfly.org/v4/components/text-area).
- Same for a multi-line textarea, you can use `HookFormPFTextArea` ([source](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/components/HookFormPFFields/HookFormPFTextArea.tsx), [example](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/pages/proxies/proxy-form.tsx)) which extends the props of PF [TextArea](https://www.patternfly.org/components/forms/text-area).

- For any other type of field that requires a PF `FormGroup` (label, error messages under the field) you can use the `HookFormPFGroupController` that is used internally by those 2 components, and pass it your own `renderField` function. (source, example). For select dropdowns we have a simplified abstraction called [SimpleSelect](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/shared/components/simple-select/simple-select.tsx).
- For any other type of field that requires a PF `FormGroup` (label, error messages under the field) you can use the `HookFormPFGroupController` that is used internally by those 2 components, and pass it your own `renderField` function. (source, example). For select dropdowns we have a simplified abstraction called [SimpleSelect](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/components/SimpleSelect.tsx).

- These all use the Controller pattern from react-hook-form (docs [here](https://react-hook-form.com/get-started#IntegratingwithUIlibraries) and [here](https://react-hook-form.com/api/usecontroller/controller)). You generally don't want to use the `{...register('fieldName')}` approach that is all over their docs, it is for uncontrolled inputs (we need controlled inputs to render errors on change).
- All of the above components include a formGroupProps prop in case you need to override any of the [props for PF's FormGroup](https://www.patternfly.org/v4/components/form#formgroup) that aren't taken care of for you.
- All of the above components include a formGroupProps prop in case you need to override any of the [props for PF's FormGroup](https://www.patternfly.org/components/forms/form#field-groups) that aren't taken care of for you.

- If you don't need a `FormGroup` around your field (no external label or errors), you can just render a <Controller> for it yourself. That's what we do for [Switch](https://www.patternfly.org/v4/components/switch) fields (because switch has a built in right-aligned label). ([example](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/pages/proxies/proxy-form.tsx#L286-L300))
- If you don't need a `FormGroup` around your field (no external label or errors), you can just render a <Controller> for it yourself. That's what we do for [Switch](https://www.patternfly.org/components/switch) fields (because switch has a built in right-aligned label). ([example](https://github.com/konveyor/tackle2-ui/blob/main/client/src/app/pages/proxies/proxy-form.tsx))

## READMEs

Expand Down

0 comments on commit 6b805b5

Please sign in to comment.