Update UI developer docs (#323)

RRM123 · ckadner · commit 605fe331d863 · 2022-04-22T12:43:32.000-07:00
Closes #323 Signed-off-by: RRM123 <rithikmamidi@gmail.com>
diff --git a/README.md b/README.md
@@ -13,11 +13,6 @@ Allows upload, registration, execution, and deployment of:
  - Datasets
  - Notebooks
 
-For more details about the project please follow this [announcement blog post](https://lfaidata.foundation/blog/2021/09/28/machine-learning-exchange-mlx/). 
-
-
-<img src="docs/images/mlx.png" height="90%" width="90%">
-
 Additionally it provides:
 
  - Automated sample pipeline code generation to execute registered models, datasets and notebooks
@@ -28,6 +23,12 @@ Additionally it provides:
  - Serving engine by [KFServing](https://github.com/kubeflow/kfserving)
  - Model Metadata schemas
 
+For more details about the project check out this [announcement blog post](https://lfaidata.foundation/blog/2021/09/28/machine-learning-exchange-mlx/). 
+
+
+<img src="docs/images/mlx.png" height="90%" width="90%">
+
+
 ## 1. Deployment
 <img src="docs/images/mlx-architecture-4.png" height="40%" width="40%">
 
@@ -66,13 +67,19 @@ oc get route -n istio-system
 
 ## 3. Import Data and AI Assets in MLX Catalog
 
-[Import data and AI assets using MLX's catalog importer](/docs/import-assets.md)
+For information on how to import data and AI assets using MLX's catalog importer, use this [guide](/docs/import-assets.md).
 
 ## 4. Use MLX
 
-[MLX Usage Instructions](/docs/usage-steps.md)
-	
-## 5. Troubleshooting
+For information on how to use MLX and create assets check out this [guide](/docs/usage-steps.md).
+
+## 5. How to Contribute
+
+For information about adding new features, bug fixing, communication
+or UI and API setup, refer to this [document](CONTRIBUTING.md).
+
+
+## 6. Troubleshooting
 
 [MLX Troubleshooting Instructions](/docs/troubleshooting.md)
 	
diff --git a/dashboard/origin-mlx/OLD_README.md b/dashboard/origin-mlx/OLD_README.md
diff --git a/dashboard/origin-mlx/README.md b/dashboard/origin-mlx/README.md
@@ -1,10 +1,17 @@
 # Machine Learning Exchange - Web UI
 
-## Setup
+This README contains information about the front end of the Machine Learning Exchange project.
 
-This repo contains the code for the front end UI of the Machine Learning Exchange project.
+## Prerequisites
 
-To run this app, you'll need a current version of Node.js installed.
+- [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+  to build and run the MLX UI code locally
+- [Docker](https://docs.docker.com/get-docker/) to rebuild the MLX UI image
+- [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) to redeploy 
+  the `mlx-ui` service to Kubernetes
+
+
+## Starting the MLX UI locally
 
 1. First, clone this repo:
 ```Bash
@@ -43,55 +50,80 @@ npm start
 http://localhost:3000/settings
 ```
 
-## Deploy MLX UI to Kubernetes
+# Development Setup
+
+## Build a Docker Image for MLX UI
+
+```Bash
+cd dashboard/origin-mlx
+docker build -t <your docker user-id>/<repo name>:<tag name> -f Dockerfile .
+docker push <your docker user-id>/<repo name>:<tag name>
+```
+
+## (Re-)Deploy to Kubernetes Cluster
+
+For information on how to deploy MLX on a Kubernetes Cluster or OpenShift on IBM
+Cloud, check out the guide [here](/docs/mlx-setup.md).
+Once the cluster has been deployed, the new `mlx-ui` container image will need to
+be redeployed after changes to the UI code have been made.
+
+Change the container image in the deployment spec
+[/manifests/base/mlx-deployments/mlx-ui.yaml](/manifests/base/mlx-deployments/mlx-ui.yaml)
+under `spec.template.spec.containers` with `name: mlx-ui`
+from `image: mlexchange/mlx-ui:nightly`
+to `image: <your_docker_user_id>/<repo_name>:<tag_name>`
+and then run:
 
-First deploy the MLX UI.
 ```Bash
-kubectl apply -f ./dashboard/origin-mlx/mlx-ui.yml
+# navigate to the MLX root directory
+# cd ../..
+kubectl delete -f manifests/base/mlx-deployments/mlx-ui.yaml
+kubectl apply -f manifests/base/mlx-deployments/mlx-ui.yaml
 ```
 
 Find the UI Host and Port. It may take some time before the MLX UI becomes available.
+
 ```Bash
 export UI_HOST=$(kubectl get nodes -o jsonpath='{.items[].status.addresses[?(@.type=="ExternalIP")].address}')
 export UI_PORT=$(kubectl get service mlx-ui -n kubeflow -o jsonpath='{.spec.ports[0].nodePort}')
 ```
+
 Open the webpage in a browser:
 
 ```Bash
 open "http://${UI_HOST}:${UI_PORT}"
 ```
 
-# Development Setup
-
-## Build a Docker Image for MLX UI
-
-```Bash
-cd dashboard/origin-mlx
-docker build -t <your docker user-id>/<repo name>:<tag name> -f Dockerfile .
-docker push <your docker user-id>/<repo name>:<tag name>
-```
+## UI Development with Docker Compose
 
-## (Re-)Deploy to Kubernetes Cluster
+For information on how to get started with Docker Compose before making any changes
+to the UI code, check out the [Quick Start Guide](/quickstart/README.md) and
+take a look at the [docker-compose.yaml](/quickstart/docker-compose.yaml) file
+to understand how the individual services like `mysql`, `minio`, `mlx-api`, `mlx-ui`,
+etc. are working together.
 
-Change the Docker image tag in the deployment spec server/mlx-ui.yml from image: ibmandrewbutler/open-ui:add-homepage to image: <your_docker_user_id>/<repo name>:<tag name> and then run:
+The Docker Compose stack can be brought up and taken down by running the following
+commands. The `--project-name` tag keeps the docker compose network and the volumes
+(stored assets) separate from the quickstart for development. Each docker compose
+project has separate network and volumes which can be viewed using
+[Docker Desktop](https://www.docker.com/products/docker-desktop/):
 
 ```Bash
-kubectl delete -f ./dashboard/origin-mlx/mlx-ui.yml
-kubectl apply -f ./dashboard/origin-mlx/mlx-ui.yml
+docker compose --project-name  mlx  up
+docker compose --project-name  mlx  down
 ```
 
-## UI Development with Docker Compose
-
 You can test most code changes without a Kubernetes cluster. A K8s cluster is only
 required to `run` the generated sample pipeline code. Running the Quickstart with
 Docker Compose is sufficient to test any `katalog` related API endpoints.
 
 A development setup that works very well requires to 2 shell terminals:
 
-### Terminal 1 - Quickstart without `mlx-ui` service
+### Terminal 1 - Quickstart without the `mlx-ui` service
 
 Bring up the Quickstart without the `mlx-ui` service, since we will run the MLX UI
-from our local source code, instead of using the pre-built Docker image `mlexchange/mlx-ui:nightly-origin-main`.
+from our local source code, instead of using the pre-built Docker image
+`mlexchange/mlx-ui:nightly-origin-main`.
 
 ```Bash
 # cd <mlx_root_directory>
@@ -116,7 +148,7 @@ docker compose rm -v -f
 docker volume prune -f
 ```
 
-### Terminal 2 - Start the UI server
+### Terminal 2 - Start the MLX UI locally
 
 Navigate to the UI source folder:
 
@@ -185,6 +217,10 @@ which matches a previous request and the difference of the time between the two
 
 To invalidate or hard reset the cache, navigate to the settings page (clicking the three dots at the bottom of the sidebar) and click on the `Reset Cache` button.
 
+# Development Guidelines:
+
+For information on UI code structure, design principles, etc. check out the [MLX UI Developer Guide](developer-guide.md).
+
 # Project Overview:
 
 ![MLX Overview](src/images/image1.png)
diff --git a/dashboard/origin-mlx/developer-guide.md b/dashboard/origin-mlx/developer-guide.md
@@ -1,6 +1,7 @@
 # MLX UI (w/ React)
 
 ## React Design Principles
+
 The key feature of React is composition of components. React works by having pages use components to add functionality which themselves use components to add functionality.
 
 ![LandingPage](/docs/images/LandingPage.png)
@@ -11,107 +12,45 @@ Image 1: The Landing Page divided into some of its components.
 
 Image 2: MLX UI structure
 
-
-React Props vs. State:
+### React Props vs. State:
 
 A components props and state are variables which dictate the changeable content of a component. For example, take a parent component that is a webpage and take a child component which represents a Button. The parent could ask for two Buttons with the text="Press" on one and text="Click" on the other. "Press" and "Click" would be the value of the variable props.text and should not be changed inside of the Button component. The state of these Buttons could be something like "clickNum" which defines how many times the button has been clicked. 
 Props - Parameters passed from the parent component. Props should not be changed inside the child component. If a prop is changed in a parent component then the child component will be recreated.
 State - Variables that dictate the current condition of the component. State can be changed inside the component. If a state variable is changed in a component then the component will be recreated.
 
-
-Lifecycle Methods:
+### Lifecycle Methods:
 
 Each component has several “lifecycle methods” that you can override to run code at particular times in the process. Putting functions in different lifecycle methods will cause the function to be run at a specific point in a component's lifecycle. An example of this is running a function after a component is being unmounted (removed or refreshed).
 
-## Startup
-
-General Startup Instructions: https://github.com/machine-learning-exchange/mlx/tree/main/dashboard/origin-mlx
-
-### Starting the MLX UI locally
-
-To run this app, you'll need a current version of Node.js installed.
-
-1. First, clone this repo:
-```Bash
-git clone https://github.com/machine-learning-exchange/mlx.git
-```
-
-2. Next, install the dependencies by running this command from within the newly created directory:
-```Bash
-npm install
-```
-
-3. Start the app with the following command:
-```Bash
-npm start
-```
-
-4. The app should now be accessible in your web browser at:
-```
-http://localhost:3000
-```
-
-### Starting the MLX UI locally with Docker API
-```
-git clone https://github.com/machine-learning-exchange/mlx.git
-cd mlx/
-cd dashboard/origin-mlx/
-rm -rf package-lock.json 
-npm install
-export REACT_APP_API="localhost:8080"
-export REACT_APP_RUN="false"
-export REACT_APP_UPLOAD="true"
-export REACT_APP_DISABLE_LOGIN="true"
-npm start
-```
-
-### Building an MLX UI Image
-
-```
-cd dashboard/origin-mlx
-docker build -t <your docker user-id>/<repo name>:<tag name> -f Dockerfile .
-docker push <your docker user-id>/<repo name>:<tag name>
-```
-
-### Change the UI image on a cluster deployment
-Change the image in /manifests/base/mlx-deployments/mlx-ui.yaml under the container with the name mlx-ui at spec.template.spec.containers
-```
-kubectl delete -f /manifests/base/mlx-deployments/mlx-ui.yaml
-kubectl apply -f /manifests/base/mlx-deployments/mlx-ui.yaml
-```
 
 ## UI File Structure
  
 The folders which contain the pieces of the MLX UI:
 
 ![LandingPage](/docs/images/ui-folder-tree.png)
 
-
-
-- **components/** - Small items which get used inside of pages. For example, the sidebar is used in all the pages, but is not a page itself. The major components are listed below.
+  - **components/** - Small items which get used inside of pages. For example, the sidebar is used in all the pages, but is not a page itself. The major components are listed below.
   - **Button/**
   - **Detail/** - The Detail folder contains the specific implementations of each asset type for the MetaDetailPage. The ComponentDetail, for example, has a MetadataView, RunView, and two SourceCodeDisplays. The ComponentDetail file represents the content of the MetaDetailPage for the Component assets.
   - **RunView/** - Contains the displays which dictate what parameters the user must fill out when attempting to run any of the assets
   - **Sidebar/**
   - **Tooltip/**
 
-
   - There are other components other than those which make up their own folder. Some of the important ones are listed below.
   - Hero - The “Hero Bar” is the bar at the top of the page with mostly navigational items.
   - MarkdownViewer - A display which shows the contents of a markdown file
   - PageFooter - The content that gets displayed at the bottom of every page
   - SecretMenu - The menu which is only available for admins that provides admin’s with extra functionality
 
 - **icons/**
-Icons are typically an .svg wrapped in a react component.
+Icons are typically an `.svg` wrapped in a React component.
 
 - **images/**
-.png files used in UI
+`.png` files used in UI
 
-- **lib/**
-lib/ is divided into two folders api/ and stores/
-api/ - Contains all the functions which calls to the MLX API.
-stores/ - Contains all the functions which add to and view the MLX UI data store 
+- **lib/** `lib/` is divided into two folders `api/` and `stores/`
+  - `api/` - Contains all the functions which calls to the MLX API
+  - `stores/` - Contains all the functions which add to and view the MLX UI data store
 
 - **mock/**
 Some mock assets for each asset type (no longer in use).
@@ -124,12 +63,12 @@ Most (>90%) of styling is contained in css files in styles/
 
 ## Developing for the MLX UI
 
+### MLX UI Starting Points
 
-MLX UI Starting Points
-src/App.tsx controls all the routing inside the react application. If a new route needs to be added it will be added here. If it is not clear what file represents the page at a given url, trace the routes in App.tsx to find the route associated with that url and that route will show the component that is being used.
-
+- `src/App.tsx`: controls all the routing inside the react application. If a new route needs to be added it will be added here. If it is not clear what file represents the page at a given url, trace the routes in App.tsx to find the route associated with that url and that route will show the component that is being used.
 
-src/styles/ contains most (>90%) of the page styling in css. If the style needs to be changed first check the component file for styling and if the css is not inline then check in src/styles/.
+- `src/styles/`: contains most (>90%) of the page styling in css. If the style needs to be changed first check the component file for styling and if the css is not inline then check in src/styles/.
 
+- `src/lib/api/`: contains all the calls to the MLX API. If some API call is going wrong, it will likely be an issue in this folder.
 
-src/lib/api/ contains all of the calls to the MLX API. If some API call is going wrong, it will likely be an issue in this folder.
+For more information on UI Setup and Deployment go [here](README.md)
diff --git a/dashboard/origin-mlx/mlx-ui.yaml b/dashboard/origin-mlx/mlx-ui.yaml
@@ -1,5 +1,5 @@
 # Copyright 2021 The MLX Contributors
-# 
+#
 # SPDX-License-Identifier: Apache-2.0
 apiVersion: v1
 kind: ServiceAccount
@@ -28,11 +28,11 @@ spec:
       containers:
       - name: mlx-ui
         # You can use your own webapp image below
-        image: aipipeline/mlx-ui:nightly-origin-master
+        image: mlexchange/mlx-ui:nightly-origin-main
         imagePullPolicy: Always
         env:
         - name: REACT_APP_BRAND
-          value: MLX
+          value: "Machine Learning eXchange"
         - name: REACT_APP_RUN
           value: "true"
         - name: REACT_APP_UPLOAD
