|
1 | | -# Kubeflow Landing-Page |
| 1 | +# deployKF Dashboard |
2 | 2 |
|
3 | | -This component serves as the landing page and central dashboard for Kubeflow |
4 | | -deployments. It provides a jump-off point to all other facets of the platform. |
| 3 | +This component serves as the landing page and central dashboard for deployKF. |
| 4 | +It provides a jump-off point to all other tool Web UIs. |
5 | 5 |
|
6 | | -## Building and Deploying |
7 | | - |
8 | | -The build artifact of this folder is a Docker container image that hosts the |
9 | | -Express webserver that serves the API endpoints and front-end application code. |
10 | | - |
11 | | -To build a new container image, run `make` from within this directory. To push |
12 | | -it to the kubeflow-images-public repository, run `make push`. |
13 | | - |
14 | | -### Testing a build in an existing Kubeflow deployment |
| 6 | +## Development |
15 | 7 |
|
16 | | -After running `make push`, make note of the tag created. |
| 8 | +### Getting Started |
17 | 9 |
|
18 | | -``` |
19 | | -Pushed gcr.io/kubeflow-images-public/centraldashboard with :v20190328-v0.4.0-rc.1-280-g8563142d-dirty-319cfe tags |
20 | | -``` |
| 10 | +Make sure you have installed node 12 or 14. |
21 | 11 |
|
22 | | -Then, use **kubectl** to update the image on the existing Central Dashboard |
23 | | -deployment, specifying the image name and tag that was output in the step above. |
| 12 | +1. Run `cd dashboard` |
| 13 | +2. Run `make build-local` to install npm dependencies |
| 14 | +3. Run `npm run dev` to start the development server |
| 15 | + - This runs [webpack](https://webpack.js.org/) over the front-end code in the [public](./public) folder. |
| 16 | + It also starts the [webpack-dev-server](https://webpack.js.org/configuration/dev-server/) at http://localhost:8081. |
| 17 | + - It also starts the Express API server at http://localhost:8082. |
| 18 | + Requests from the front-end starting with `/api` are proxied to the Express server. |
| 19 | + All other requests are handled by the front-end server which mirrors the production configuration. |
24 | 20 |
|
25 | | -``` |
26 | | -kubectl --record deployment.apps/centraldashboard \ |
27 | | - set image deployment.v1.apps/centraldashboard \ |
28 | | - centraldashboard=gcr.io/kubeflow-images-public/centraldashboard:v20190328-v0.4.0-rc.1-280-g8563142d-dirty-319cfe |
29 | | -``` |
| 21 | +### Server Components |
30 | 22 |
|
31 | | -## Development |
| 23 | +Server side code resides in the [app](./app) directory. |
32 | 24 |
|
33 | | -### Getting Started |
34 | | -Make sure you have the latest LTS version of `node` installed along with `npm`. |
35 | | - |
36 | | -1. Clone the repository and change directories to `components/centraldashboard` |
37 | | -2. Run `make build-local`. This will install all of the project dependencies and |
38 | | - prepare your system for development. |
39 | | -3. To start a development environment, run `npm run dev`. |
40 | | - - This runs [webpack](https://webpack.js.org/) over the front-end code in |
41 | | - the [public](./public) folder and starts the |
42 | | - [webpack-dev-server](https://webpack.js.org/configuration/dev-server/) at |
43 | | - http://localhost:8081. |
44 | | - - It also starts the Express API server at http://localhost:8082. Requests |
45 | | - from the front-end starting with `/api` are proxied to the Express |
46 | | - server. All other requests are handled by the front-end server which |
47 | | - mirrors the production configuration. |
48 | | -4. - To access the Jupyter Web App run: `kubectl port-forward -n kubeflow svc/jupyter-web-app-service 8085:80`. |
49 | | - - To access Pipeline Web App run: `kubectl port-forward -n kubeflow svc/ml-pipeline-ui 8087:80`.` |
50 | | - |
51 | | - This forwards requests to Kubernetes services from `http://localhost:service-proxy-port`. See the [webpack config file](https://github.com/kubeflow/kubeflow/blob/master/components/centraldashboard/webpack.config.js) for more details. |
| 25 | +The server uses [Express](https://expressjs.com/) and is written in [Typescript](https://www.typescriptlang.org/docs/home.html). |
52 | 26 |
|
53 | | -### Server Components |
| 27 | +### Front-End Components |
54 | 28 |
|
55 | | -Server side code resides in the [app](./app) directory. The server uses |
56 | | -[Express](https://expressjs.com/) and is written in [Typescript](https://www.typescriptlang.org/docs/home.html). |
| 29 | +Client side code resides in the [public](./public) directory. |
| 30 | +Client components are written using the [Polymer 3](https://polymer-library.polymer-project.org/3.0/docs/about_30) web components library. |
| 31 | +All Polymer components should be written under the [public/components](./public/components) directory. |
57 | 32 |
|
58 | | -### Front-End Components |
| 33 | +You may use the [inline style](https://polymer-library.polymer-project.org/3.0/docs/first-element/step-2) for creating your Shadow DOM, |
| 34 | +or separate your CSS and HTML in separate files. |
59 | 35 |
|
60 | | -Client side code resides in the [public](./public) directory. Client components |
61 | | -are written using the [Polymer 3](https://polymer-library.polymer-project.org/3.0/docs/about_30) |
62 | | -web components library. All Polymer components should be written under the |
63 | | -[public/components](./public/components) directory. You may use the [inline style](https://polymer-library.polymer-project.org/3.0/docs/first-element/step-2) for creating your Shadow DOM, or seperate your |
64 | | -CSS and HTML in seperate files. We currently support [Pug](https://pugjs.org/api/getting-started.html) |
65 | | -templating for external markup. See [main-page.js](public/components/main-page.js) |
66 | | -for an example. |
| 36 | +We currently support [Pug](https://pugjs.org/api/getting-started.html) templating for external markup. |
| 37 | +See [main-page.js](public/components/main-page.js) for an example. |
67 | 38 |
|
68 | 39 | ### Testing |
69 | 40 |
|
70 | | -When introducing new changes, you should ensure that your code is tested. By |
71 | | -convention, tests should reside in the same directory as the code under test and |
72 | | -be named with the suffix `_test.(js|ts)`. For a module named |
73 | | -`new-fancy-component.js`, its test should be in a file named `new-fancy-component_test.js`. |
| 41 | +When introducing new changes, you should ensure that your code is tested. |
| 42 | +By convention, tests should reside in the same directory as the code under test and be named with the suffix `_test.(js|ts)`. |
| 43 | +For a module named `new-fancy-component.js`, its test should be in a file named `new-fancy-component_test.js`. |
74 | 44 |
|
75 | 45 | Both server and client-side unit tests are written using [Jasmine](https://jasmine.github.io/api/3.3/global). |
76 | 46 | Client-side tests are run with Karma using headless Chrome by default. |
77 | 47 |
|
78 | 48 | #### Code Coverage |
79 | 49 |
|
80 | | -To run unit tests and collect coverage, run `npm run coverage`. This will output |
81 | | -coverage statistics on the console and also create subfolders for `app` and |
82 | | -`public` inside of the `coverage` folder with interactive displays of the code |
83 | | -coverage. Please try to strive for high levels of coverage for sections of your |
84 | | -code with business logic. |
85 | | - |
86 | | ---- |
87 | | - |
88 | | -## Style-Guide |
89 | | -Kubeflow central dashboard is a visualization and networking platform that links |
90 | | -fellow sub-apps within the Kubeflow Ecosystem together. As a result we have |
91 | | -various web-apps that are iframed within the app. To keep this experience |
92 | | - uniform, we have a style guide for all Kubeflow Integrators to follow / use. |
93 | | - |
94 | | -### Approach |
95 | | -The CSS palette is found at [_public/kubeflow-palette.css_](public/kubeflow-palette.css). |
96 | | -When deployed to a cluster, it can be imported from `cluster-host/kubeflow-palette.css` |
97 | | - |
98 | | -Name | Value | Usage |
99 | | ---- | --- | --- |
100 | | -`--accent-color` | #007dfc | Should be used to highlight Action Buttons, borders, FABs |
101 | | -`-kubeflow-color` | #003c75 | The primary background color for Kubeflow CentralDashboard |
102 | | -`--primary-background-color` | #2196f3 | Used as the background color for all navigation elements (Toolbars, FOBs) |
103 | | -`--sidebar-color` | #f8fafb | Background Color for Sub-App Sidebar |
104 | | -`--border-color` | #f4f4f6 | All borders on the page |
105 | | - |
106 | | -_**Note:** This style-guide is subject to change, and will eventually be served as a CDN, so eventually manual updates will not be required._ |
107 | | - |
108 | | -### General Principles |
109 | | -- Follow the Material Design 2 Spec, when possible |
110 | | -- Elevations should match the [_**MD2 Elevation Spec**_](https://material.io/design/environment/elevation.html) |
111 | | -- The subapp should not mention namespaces, and should use the value provided by the Central Dashboard. |
112 | | - |
113 | | -### Usage |
114 | | -Download the [_**styleguide**_](public/kubeflow-palette.css). And then in your html, import it like: |
115 | | - |
116 | | -```html |
117 | | -<head> |
118 | | - <!-- Meta tags / etc --> |
119 | | - <link rel='stylesheet' href='kubeflow-palette.css'> |
120 | | -``` |
121 | | - |
122 | | -And then in your stylesheets you can use your palette variables like: |
123 | | - |
124 | | -```css |
125 | | -body > .Main-Toolbar {background-color: var(--primary-background-color)} |
126 | | -.List > .item:not(:first-of-type) {border-top: 1px solid var(--border-color)} |
127 | | -/* etc */ |
128 | | -``` |
129 | | - |
130 | | -## Client-Side Library |
131 | | -Since the Central Dashboard wraps other Kubeflow components in an iframe, a |
132 | | -standalone Javascript library is exposed to make it possible to communicate |
133 | | -between the child pages and the dashboard. |
134 | | - |
135 | | -The library is available for import from `/dashboard_lib.bundle.js` within the |
136 | | -cluster. When imported in this manner, a `centraldashboard` module is created in |
137 | | -the global scope. To establish a channel for communication between the iframed |
138 | | -page and the Dashboard, use the following example which would disable a |
139 | | -`<select>` element and assign the value from the Dashboard's Namespace selector |
140 | | -when it changes: |
141 | | - |
142 | | -```js |
143 | | -window.addEventListener('DOMContentLoaded', function (event) { |
144 | | - if (window.centraldashboard.CentralDashboardEventHandler) { |
145 | | - // Init method will invoke the callback with the event handler instance |
146 | | - // and a boolean indicating whether the page is iframed or not |
147 | | - window.centraldashboard.CentralDashboardEventHandler |
148 | | - .init(function (cdeh, isIframed) { |
149 | | - var namespaceSelector = document.getElementById('ns-select'); |
150 | | - namespaceSelector.disabled = isIframed; |
151 | | - // Binds a callback that gets invoked anytime the Dashboard's |
152 | | - // namespace is changed |
153 | | - cdeh.onNamespaceSelected = function (namespace) { |
154 | | - namespaceSelector.value = namespace; |
155 | | - }; |
156 | | - }); |
157 | | - } |
158 | | -}); |
159 | | -``` |
| 50 | +To run unit tests and collect coverage, run `npm run coverage`. |
| 51 | +This will output coverage statistics on the console and also create subfolders for `app` and `public` inside of |
| 52 | +the `coverage` folder with interactive displays of the code coverage. |
| 53 | + |
| 54 | +Please try to strive for high levels of coverage for sections of your code with business logic. |
0 commit comments