Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consolidate UI developer docs (#258) #323

Closed
wants to merge 7 commits into from
Closed

Consolidate UI developer docs (#258) #323

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e4207d0
Consolidated UI Developer Docs
RRM123 Mar 29, 2022
484be2b
Merge branch 'machine-learning-exchange:main' into main
RRM123 Mar 29, 2022
e2c76cd
Made README.md point to developer-guide.md.
RRM123 Mar 29, 2022
3feed5b
Merge remote-tracking branch 'origin/main' into main
RRM123 Mar 29, 2022
2cd7708
Update README.md
RRM123 Apr 4, 2022
5edd3e8
Update README.md
RRM123 Apr 21, 2022
921536b
Update developer-guide.md
RRM123 Apr 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 18 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 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%">


## 1. Deployment
<img src="docs/images/mlx-architecture-4.png" height="40%" width="40%">

Expand Down Expand Up @@ -66,13 +67,21 @@ 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

Contributions can be made to either the UI or API.

For information about adding new features, bug fixing, communication
or UI and API setup, please refer to this [document](CONTRIBUTING.md).


## 6. Troubleshooting

[MLX Troubleshooting Instructions](/docs/troubleshooting.md)

Expand Down
8 changes: 0 additions & 8 deletions dashboard/origin-mlx/OLD_README.md
View file
Open in desktop

This file was deleted.

34 changes: 33 additions & 1 deletion dashboard/origin-mlx/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

This repo contains the code for the front end UI of the Machine Learning Exchange project.

### Starting the MLX UI locally

To run this app, you'll need a current version of Node.js installed.

1. First, clone this repo:
Expand Down Expand Up @@ -72,15 +74,42 @@ 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 clusters have been deployed, they will need to be redeployed for UI work.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this may be slightly misleading. A more precise phrasing would be:

Once the cluster has been deployed, the MLX UI will need to be redeployed after changes to the UI code have been made.


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:

```Bash
kubectl delete -f ./dashboard/origin-mlx/mlx-ui.yml
kubectl apply -f ./dashboard/origin-mlx/mlx-ui.yml
```
Change the image in /manifests/base/mlx-deployments/mlx-ui.yaml under the container with the name mlx-ui at spec.template.spec.containers
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

did you try this out? should this be either or? ... either

  • ./dashboard/origin-mlx/mlx-ui.yml or
  • /manifests/base/mlx-deployments/mlx-ui.yaml

```
kubectl delete -f /manifests/base/mlx-deployments/mlx-ui.yaml
kubectl apply -f /manifests/base/mlx-deployments/mlx-ui.yaml
```

## UI Development with Docker Compose
For information on how to get started with Docker Compose, and it's appropriate setup, check out the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good bit of information :-) I would change it slightly to:

For information on how to get started with Docker Compose before making any changes to the UI code, check out the Quick Start Guide and take a look at the docker-compose.yaml file to understand how the individual services like mysql, minio, mlx-api, mlx-ui, etc. are working together.

[Quick Start Guide](../../quickstart/README.md).

To bring up the Docker Compose stack run:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would remove the 2 commands here as they are duplicated from in the Quickstart guide, or, point out how they are different (i.e. using the --project-name ... flag)

```Bash
docker compose --project-name mlx up
```
Don't forget to bring the stack down with:
```Bash
docker compose --project-name mlx down
```
To bring up the stack without the UI run:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these 2 commands are described already in context of the next passage

```Bash
docker compose --project-name mlx_no_ui up minio miniosetup mysql mlx-api catalog
```
Once finished, run:
```Bash
docker compose --project-name mlx_no_ui down
```


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
Expand Down Expand Up @@ -116,7 +145,7 @@ docker compose rm -v -f
docker volume prune -f
```

### Terminal 2 - Start the UI server
### Terminal 2 - Start the MLX UI locally with Docker API
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is no Docker involved in this second terminal


Navigate to the UI source folder:

Expand Down Expand Up @@ -185,6 +214,9 @@ 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 Guidlines:
For information on UI code structure, design principles, etc. check out the [MLX Developer Guide](developer-guide.md).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"MLX UI Developer Guide" ... the API has a separate one


# Project Overview:

![MLX Overview](src/images/image1.png)
58 changes: 2 additions & 56 deletions dashboard/origin-mlx/developer-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,62 +23,6 @@ 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

Expand Down Expand Up @@ -133,3 +77,5 @@ src/styles/ contains most (>90%) of the page styling in css. If the style needs


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 Development Setup go [here](README.md)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if we have two files

  • the /dashboard/origin-mlx/README.md and
  • the /dashboard/origin-mlx/developer-guide.md

then we should make a clear separation of content:

  • all the parts in the README.md that talk about development should be in the developer-guide,
  • and the README only has information about how to use (and deploy) the MLX UI

Although the developer guide also needs to inform about how to redeploy the MLX UI. So I am not convinced we need two documents if the README can contain all of it. If we have one README, then it should flow from overview, architecture diagram, how to deploy (point to general deployment docs) to running locally to development with docker compose, rebuild Docker image, push it, redeploy just the new MLX UI image to existing cluster, ...