Merge pull request #6 from konveyor/add-initial-documentation

Add initial documentation

README.md

@@ -1,3 +1,78 @@
 <img src="icons/forklift-logo-lightbg.svg" alt="Logo" width="100" />
 
 # OpenShift Console Plugin For Forklift
+
+[![Operator Repository on Quay](https://quay.io/repository/kubevirt-ui/forklift-console-plugin/status "Plugin Repository on Quay")](https://quay.io/repository/kubevirt-ui/forklift-console-plugin)
+
+Forklift is a suite of migration tools that facilitate the migration of VM workloads to [OpenShift Virtualization](https://cloud.redhat.com/learn/topics/virtualization/).
+
+## Prerequisites
+
+* [__Forklift Operator__](https://https://github.com/konveyor/forklift-operator/)
+* [__OpenShift Console 4.12+__](https://www.openshift.com/)
+
+## Development
+
+### Start the UI:
+
+Using forklift console plugin code.
+
+In one terminal window, run:
+
+1. `yarn install`
+2. `yarn start`
+
+| Enviorment varialbles | Description |
+| --------------------|-------------|
+| DATA_SOURCE         | 'mock' or 'remote', when set to 'mock', the plugin will show recorded data, (default 'remote') |
+| BRAND_TYPE          | 'RedHat' or 'Konveyor', when set to 'RedHat' some strings will change to reflect downstream product names, (default 'Konveyor') |
+
+In another terminal window, run:
+
+1. `oc login # if not loggedin` (requires [oc](https://console.redhat.com/openshift/downloads) and an [OpenShift cluster](https://console.redhat.com/openshift/create))
+2. `yarn run start:console` (requires [docker](https://www.docker.com) or [podman 3.2.0+](https://podman.io))
+
+| Enviorment varialbles | Description  |
+| -------|--------------|
+| CONSOLE_IMAGE | The console image to run ( default `quay.io/openshift/origin-console:latest` )|
+| CONSOLE_PORT | Expose the console web application on port ( default `9000` )|
+| INVENTORY_SERVER_HOST | URL of Forklift inventory server ( default `http://localhost:8080` )|
+| MUST_GATHER_API_SERVER_HOST | URL of Forklift must gather server ( default `http://localhost:9200` )|
+| BRIDGE_K8S_AUTH_BEARER_TOKEN | Bearer token of user account ( on openshift token default to `$(oc whoami -t)` )|
+
+This will run the OpenShift console in a container connected to the cluster
+you've logged into. The plugin HTTP server runs on port 9001 with CORS enabled.
+
+## Deployment on cluster
+
+See: [docs/helm](/docs/helm.md) for details.
+
+After pushing an image with your changes to a registry, you can deploy the
+plugin to a cluster by using [helm](https://helm.sh/).
+
+```bash
+# Add the forklift helm repo
+helm repo add forklift https://konveyor.github.io/forklift-console-plugin
+
+# Install the forklift console plugin using current namespace
+helm install forklift-console-plugin forklift/forklift-console-plugin
+```
+
+### Helm templates optional values:
+
+```bash
+# for example, if forklift-operator is not installed in konveyor-forklift namespace,
+# set "forkliftNamespace" value to the currect namespace:
+helm install forklift-console-plugin \
+   forklift/forklift-console-plugin \
+   --set forkliftNamespace=openshift-mtv 
+```
+
+Once deployed on the cluster, our plugin must be enabled before it can be loaded by Console.
+
+To enable the plugin manually, edit Console operator config and make sure the plugin's name is listed in the spec.plugins sequence (add one if missing):
+
+```bash
+oc patch consoles.operator.openshift.io cluster \
+  --patch '{ "spec": { "plugins": ["forklift-console-plugin"] } }' --type=merge
+```

docs/README.md

@@ -0,0 +1,7 @@
+# Development documentation
+
+  - [helm](helm.md) - building and deploying the helm repository.
+  - [podman](podman.md) - building and depoying the container image.
+  - [i18n](i18n.md) - i18n development docs.
+  - [linting](linting.md) - discusing eslint and stylelint rules.
+  - [console](console.md) - compiling and running the latest development version of Openshift console with the plugin.

docs/console.md

@@ -0,0 +1,27 @@
+# Compiling and running Openshift console
+
+When running the console please use `--plugin` and `--plugin-proxy` CLI flags to enable forklift plugin:
+
+`--plugin` sets the URL of the static plugin servier, for example if the `forklift-console-plugin` plugin is served on`http://localhost:9001`, use `--plugins="forklift-console-plugin=http://localhost:9001"`
+
+`--plugin-proxy` is a json struct that sets proxy servers needed by the plugin, for example a json struct representing the forklift inventory server, looks like:
+
+``` json
+{
+    "services":[
+        {
+            "consoleAPIPath":"/api/proxy/plugin/forklift-console-plugin/forklift-inventory/providers",
+            "endpoint":"https:///<forklift-inventory-konveyor-server>/providers",
+            "authorize":true
+        }
+    ]
+}
+```
+
+## Example
+
+RUnning the bridge with forklift plugin on a development setup, may look like that:
+
+``` bash
+./bin/bridge --plugins="forklift-console-plugin=http://localhost:9001" --plugin-proxy='{"services":[{"consoleAPIPath":"/api/proxy/plugin/hello-console-plugin/forklift-inventory/providers","endpoint":"https:///<forklift-inventory-konveyor-server>/providers","authorize":true}]}'
+ ```

docs/helm.md

@@ -0,0 +1,77 @@
+# Helm repository
+
+[Helm](https://helm.sh/) is the best way to find, share, and use software built for Kubernetes.
+
+## Forklift console plugin helm repository
+
+(see forklift console plugin [helm repository code](/deployment/forklift-console-plugin))
+
+| Template | Description |
+|-----------|-------------|
+| configmap | Includes the `nginx.conf` file. |
+| deployment | Deploys the `nginx` server, serving static files. |
+| service | Defines the ports exposed to outside by our deployment. |
+| consoleplugin | Define who the Openshift console consume and use our plugin. |
+
+| Parameter | Description | Default value |
+|-----------|-------------|---------------|
+| plugin | name of "app" label used for objects |  forklift-console-plugin
+| name | the deployment name | forklift-console-plugin
+| image | the plugin container image | quay.io/kubevirt-ui/forklift-console-plugin:latest
+| forkliftNamespace | forklift-operator namespace | konveyor-forklift
+
+## Running the helm chart locally
+
+Running helm requires to be looged into the cluster, and using the namespace for the instalation:
+
+```bash
+# login into the cluster
+oc login ... 
+
+# choose a project
+oc project forklift-console-plugin
+```
+
+When you are logged in, and using the instalation project, you can use the local helm chart:
+
+```bash
+# install local
+helm install forklift ./deployment/forklift-console-plugin
+
+# install using custom values
+helm install forklift ./deployment/forklift-console-plugin --set forkliftNamespace=openshift-mtv
+
+# list all installed helm charts
+helm list
+
+# uninstall a helm chart
+helm uninstall forklift
+```
+
+## Building the repository package
+
+Sharing `forklift-console-plugin` helm chart is done by serving the helm package on github-pages.
+
+We serve github pages using `gh-pages` branch, the repository include a `forklift-console-plugin-*.tgz` file that includes that helm repository templates, and an `index.yaml` metadata file.
+
+``` bash
+# creating a package file and pushing it into a local `tmp` directory
+# once the package files are ready in the tmp direcoty, you can copy them to the gh-pages branch
+# and publish the package using githup pages.
+yarn helm:build
+```
+
+## Using the public repository
+
+[ Running helm requires to be looged into the cluster, and using the namespace for the instalation ]
+
+```bash
+# add the forklift helm repo
+helm repo add forklift https://konveyor.github.io/forklift-console-plugin
+
+# install the chart using the repository package
+helm install forklift forklift/forklift-console-plugin
+
+# use optional vaiables
+helm install forklift-console-plugin forklift/forklift-console-plugin --set forkliftNamespace=openshift-mtv
+```

docs/i18n.md

@@ -0,0 +1,49 @@
+# i18n
+
+See: [openshift console dynamic plugin i18n doc](https://github.com/openshift/console/tree/master/dynamic-demo-plugin#i18n).
+
+You can translate messages in a forklift console plugin with react-i18next. The i18n namespace must match the name of the `ConsolePlugin` resource with the `plugin__` prefix to avoid naming conflicts. For example, the plugin uses the `plugin__forklift-console-plugin` namespace. You can use the `useTranslation` hook with this namespace as follows:
+
+``` ts
+conster Header: React.FC = () => {
+  const { t } = useTranslation('plugin__forklift-console-plugin');
+  return <h1>{t('Hello, World!')}</h1>;
+};
+```
+
+We use a customized version of `useTranslation` that specifiy the plugin namespace:
+
+```ts
+// component file
+import { useTranslation } from '@internal/utils/i18n';
+
+// customized method using 'plugin__forklift-console-plugin' namespace.
+const { t } = useTranslation();
+t('Providers')
+
+```
+
+The plugin contains `console.openshift.io/use-i18n` annotation, which indicates whether the `ConsolePlugin` contains localization resources. If the annotation is set to "true", the localization resources from the i18n namespace named after the dynamic plugin, in this case `plugin__forklift-console-plugin`, are loaded. If the annotation is set to any other value or is missing on the `ConsolePlugin` resource, localization resources are not loaded.
+
+For labels in `console-extensions.json`, you can use the format `%plugin__forklift-console-plugin~My Label%`. Console will replace the value with the message for the current language from the `plugin__forklift-console-plugin` namespace. For example:
+
+``` json
+  {
+    "type": "console.navigation/section",
+    "properties": {
+      "id": "admin-demo-section",
+      "perspective": "admin",
+      "name": "%plugin__forklift-console-plugin~Forklift Plugin%"
+    }
+  }
+```
+
+Note that you will need to include a comment in a TypeScript file like the following for `i18next-parser` to add the message from `console-extensions.json` to your message catalog.
+
+``` ts
+// t('plugin__forklift-console-plugin~Demo Plugin')
+```
+
+See [/src/i18n/i18n.ts](/src/i18n/i18n.ts) for this comments.
+
+Running `yarn i18n` updates the JSON files in the locales folder of the dynamic plugin when adding or changing messages.

docs/linting.md

@@ -0,0 +1,16 @@
+## Linting
+
+This project adds prettier, eslint, and stylelint. Linting can be run with
+`yarn run lint`.
+
+The stylelint config disallows hex colors since these cause problems with dark
+mode (starting in OpenShift console 4.11). You should use the
+[PatternFly global CSS variables](https://patternfly-react-main.surge.sh/developer-resources/global-css-variables#global-css-variables)
+for colors instead.
+
+The stylelint config also disallows naked element selectors like `table` and
+`.pf-` or `.co-` prefixed classes. This prevents plugins from accidentally
+overwriting default console styles, breaking the layout of existing pages. The
+best practice is to prefix your CSS classnames with your plugin name to avoid
+conflicts. Please don't disable these rules without understanding how they can
+break console styles!

docs/podman.md

@@ -0,0 +1,35 @@
+# Creating and publishing images
+
+## Build an image
+
+Before you can deploy your plugin on a cluster, you must build an image and
+push it to an image registry.
+
+### Build the image
+
+```sh
+# build the image and tag it
+podman build -t quay.io/kubevirt-ui/forklift-console-plugin:latest .
+```
+
+### Push the image
+
+```sh
+# login to a container repository
+podman login quay.io
+
+# push the image 
+podman push quay.io/kubevirt-ui/forklift-console-plugin:latest
+```
+
+NOTE: If you have a Mac with Apple silicon, you will need to add the flag
+`--platform=linux/amd64` when building the image to target the correct platform
+to run in-cluster.
+
+### Run the image
+
+Run the local image, expose and proxy the server to port 9001 (nginx default port is 8080).
+
+```sh
+podman run -it --rm -p 9001:8080 quay.io/kubevirt-ui/forklift-console-plugin:latest
+```