Align docs/ui.md with www/README.md

lavalamp · Jun 9, 2015 · 5d666db · 5d666db
1 parent b68e08f
commit 5d666db
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 45 deletions.
diff --git a/docs/ui.md b/docs/ui.md
@@ -1,46 +1,20 @@
-# Kubernetes UI instructions
+# Kubernetes UI Instructions
 
 ## Kubernetes User Interface
-Kubernetes currently supports a simple web user interface.
+Kubernetes has an extensible user interface with default functionality that describes the current cluster. See the [README](../www/README.md) in the www directory for more information.
 
 ### Running locally
-Start the server:
+Assuming that you have a cluster running locally at `localhost:8080`, as described [here](getting-started-guides/locally.md), you can run the UI against it with kubectl:
 
 ```sh
-cluster/kubectl.sh proxy --www=$PWD/www
+cluster/kubectl.sh proxy --www=www/app --www-prefix=/
 ```
 
-The UI should now be running on [localhost](http://localhost:8001/static/index.html#/groups//selector)
+You should now be able to access it by visiting [localhost:8001](http://localhost:8001/).
 
-### Running remotely
-When Kubernetes is deployed, the server deploys the UI, you can visit ```/static/index.html#/groups//selector``` on your master server.
-
-
-### Interacting with the user interface.
-
-The Kubernetes user interface is a query-based visualization of the Kubernetes API.  The user interface is defined by two functional primitives:
-
-#### GroupBy
-_GroupBy_ takes a label ```key``` as a parameter, places all objects with the same value for that key within a single group. For example ```/groups/host/selector``` groups pods by host.  ```/groups/name/selector``` groups pods by name.  Groups are hierarchical, for example ```/groups/name/host/selector``` first groups by pod name, and then by host.
-
-#### Select
-Select takes a [label selector](./labels.md) and uses it to filter, so only resources which match that label selector are displayed.  For example, ```/groups/host/selector/name=frontend```, shows pods, grouped by host, which have a label with the name `frontend`.
-
-
-## Rebuilding the UI
-The UI relies on [go-bindata](https://github.com/jteeuwen/go-bindata)
-
-To install go-bindata:
-
-```sh
-go get github.com/jteeuwen/go-bindata/...
-```
-
-To rebuild the UI, run the following:
-
-```sh
-hack/build-ui.sh
-```
+You can also use other web servers to serve the contents of the www/app directory, as described [here](../www/README.md#serving-the-app-during-development). 
 
+### Running remotely
+When Kubernetes is deployed remotely, the api server deploys the UI. To access it, visit `/static/app/` or `/ui`, which redirects to `/static/app/`, on your master server.
 
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/ui.md?pixel)]()
diff --git a/www/README.md b/www/README.md
@@ -1,4 +1,7 @@
-### Installing dependencies
+# Working with the Kubernetes UI
+This document explains how to work with the Kubernetes UI. For information on how to access and use it, see [docs/ui.md](../docs/ui.md).
+
+## Installing dependencies
 There are two kinds of dependencies in the UI project: tools and frameworks. The tools help
 us manage and test the application. They are not part of the application. The frameworks, on the other hand, become part of the application, as described below.
 
@@ -13,6 +16,8 @@ npm install
 
 It creates a new directory, `www/master/node_modules`, which contains the tool dependencies.
 
+## Building and serving the app
+
 ### Building the app for development
 To build the application for development, run this command from the `www/master` directory:
 
@@ -33,17 +38,25 @@ The `www/app` directory and its contents are generated by the build. All of the
 
 ### Serving the app during development
 
-For development you can serve the files locally by installing a webserver as follows:
+For development you can serve the files locally by installing a web server as follows:
 
 ```
 sudo npm install -g http-server
 ```
 
-The server can then be launched from the `app` directory as follows:
+The server can then be launched from the `www/app` directory as follows:
 
 ```
 cd www/app
-http-server -a localhost -p 8000
+http-server -a localhost -p 8001
+```
+
+`http-server` is convenient, since we're already using `npm`, but any web server hosting the `www/app` directory should work.
+
+Note that you'll need to tell the application where to find the api server by setting the value of the `k8sApiServer` configuration parameter in `www/master/shared/config/development.json` and then rebuilding the application. For example, for a cluster running locally at `localhost:8080`, as described [here](../docs/getting-started-guides/locally.md), you'll want to set it as follows:
+
+```
+"k8sApiServer": "http://localhost:8080/api/v1beta3"
 ```
 
 ### Building the app for production
@@ -68,12 +81,18 @@ Then, run one of the go build scripts, such as `hack/build-go.sh`, to build a ne
 ### Serving the app in production
 The app is served in production by `kube-apiserver` at:
 
+```
+https://<kubernetes-master>/ui/
+```
+
+which redirects to:
+
 ```
 https://<kubernetes-master>/static/app/
 ```
 
-### Configuration
-#### Configuration settings
+## Configuration
+### Configuration settings
 A json file can be used by `gulp` to automatically create angular constants. This is useful for setting per environment variables such as api endpoints.
 
 `www/master/shared/config/development.json` and `www/master/shared/config/production.json` are used for application wide  configuration in development and production, respectively.
@@ -105,19 +124,19 @@ angular.module('kubernetesApp.config', [])
 });
 ```
 
-#### Kubernetes server configuration
+### Kubernetes server configuration
 **RECOMMENDED**: The Kubernetes api server does not enable CORS by default, so `kube-apiserver` must be started with `--cors_allowed_origins=http://<your
   host here>` or `--cors_allowed_origins=.*`.
 
 **NOT RECOMMENDED**: If you don't want to/cannot restart the Kubernetes api server, you can start your browser with web security disabled. For example, you can [launch Chrome](http://www.chromium.org/developers/how-tos/run-chromium-with-flags) with flag `--disable-web-security`. Be careful not to visit untrusted web sites when running your browser in this mode.
 
-### Building a new visualizer or component
+## Building a new visualizer or component
 See [master/components/README.md](master/components/README.md).
 
-### Testing
+## Testing
 Currently, the UI project includes both unit-testing with [Karma](http://karma-runner.github.io/0.12/index.html) and end-to-end testing with [Protractor](http://angular.github.io/protractor/#/).
 
-#### Unit testing with Karma
+### Unit testing with Karma
 To run the existing Karma tests:
 
 * Install the Karma CLI (Note: it needs to be installed globally, so the `sudo` below may be needed. The other Karma packages, such as `karma`, `karma-jasmine`, and `karma-chrome-launcher,` should be installed automatically by the build). 
@@ -138,7 +157,7 @@ To run new Karma tests for a component, put new `*.spec.js` files under the appr
 
 To test the chrome, put new `*.spec.js` files under the appropriate `www/master/test/modules/*` directories.
 
-#### End-to-end testing with Protractor
+### End-to-end testing with Protractor
 To run the existing Protractor tests:
 
 * Install the CLIs.