github/kubernetes
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clean up ui build and generated files.

Browse Source
This commit is contained in:
jackgr
2015-05-29 03:35:27 -07:00
parent 5ac1151c5d
commit cff5bed70d
45 changed files with 1055 additions and 4007 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
www/README.md
View File

@@ -1,32 +1,35 @@
### Install dependencies
### 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.
We have two kinds of dependencies in this project: tools and angular framework code. The tools help
us manage and test the application.
* We get the tools via `npm`, the [node package manager](https://www.npmjs.com/).
* We get the frameworks via `bower`, a [client-side package manager](http://bower.io/).
* We get the tools we depend upon via `npm`, the [node package manager](https://www.npmjs.com/).
* We get the angular code via `bower`, a [client-side code package manager](http://bower.io/).
`npm` is configured to automatically run `bower install` and `gulp`. Before you run the application for the first time, simply run this command from the `www/master` directory:
Before you build the application for the first time, run this command from the `www/master` directory:
```
npm install
```
To start the application, run this command from the `www/master` directory:
It creates a new directory, `www/master/node_modules`, which contains the tool dependencies.
### Building the app for development
To build the application for development, run this command from the `www/master` directory:
```
npm start
```
The `gulp` command will start a file watcher which will update the generated `app` code after any changes are saved. Note: gulp file watcher does not currently support adding or deleting files, this will require a restart of gulp). Two new directories will also be created in the project.
It runs `bower install` to install and/or update the framework dependencies, and then `gulp`, a [JavaScript build system](http://gulpjs.com/), to generate a development version of the application.
* `master/node_modules` - contains npm dependencies
* `master/bower_components` - contains the angular framework files and any custom dependencies
Bower creates a new directory, `third_party/ui/bower_components`, which contains the framework dependencies. Each of them should be referenced in one of the `vendor.json` files below:
Bower components should be referenced in one of the `vendor.json` files below:
* `www/master/vendor.base.json` - 3rd party vendor javascript files required to start the app. All of the dependencies referenced by this file are compiled into `base.js` and loaded before `app.js`.
* `www/master/vendor.json` - 3rd party vendor js or css files required to make the app work, usually by lazy loading. All of the dependencies referenced by this file are compiled into `www/app/vendor`. (Note: some framework dependencies have been hand edited and checked into source control under `www/master/shared/vendor`.)
* `master/vendor.base.json` - 3rd party vendor javascript required to start the app. JS is compiled to `base.js` and loaded before `app.js`
* `master/vendor.json` - 3rd party vendor scripts to make the app work, usually lazy loaded. Can be js or css. Copied to `vendor/*`.
The default `gulp` target builds the application for development (e.g., without uglification of js files or minification of css files), and then starts a file watcher that rebuilds the generated files every time the source files are updated. (Note: the file watcher does not support adding or deleting files. It must be stopped and restarted to pick up additions or deletions).
The `www/app` directory and its contents are generated by the build. All of the other files under `www` are source or project files, such as tests, scripts, documentation and package manifests. (Note: the build output checked into source control is the production version, built with uglification and minification, as described below, so expect the build output to change if you build for development.)
### Serving the app during development
@@ -36,25 +39,54 @@ For development you can serve the files locally by installing a webserver as fol
sudo npm install -g http-server
```
The server can then be launched:
The server can then be launched from the `app` directory as follows:
```
cd app
cd www/app
http-server -a localhost -p 8000
```
### Building the app for production
To build the application for production, run this command from the `www/master` directory:
```
npm run build
```
Like `npm start`, it runs `bower install` to install and/or update the framework dependencies, but then it runs `gulp build` to generate a production version of the application. The `build` target builds the application for production (e.g., with uglification of js files and minification of css files), and does not run a file watcher, so that it can be used in automated build environments.
To make the production code available to the Kubernetes api server, run this command from the top level directory:
```
hack/build-ui.sh
```
It runs the `go-bindata` tool to package the generated `app` directory and other user interface content, such as the Swagger documentation, into `pkg/ui/datafile.go`. Note: go-bindata can be installed with `go get github.com/jteeuwen/go-bindata/...`.
Then, run one of the go build scripts, such as `hack/build-go.sh`, to build a new `kube-apiserver` binary that includes the updated `pkg/ui/datafile.go`.
### Serving the app in production
The app is served in production by `kube-apiserver` at:
```
https://<kubernetes-master>/static/app/
```
### 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``` or ```www/master/shared/config/production.json``` can be created from the ```www/master/shared/config/development.example.json``` file.
* ```development.example.json``` should be kept up to date with default values, since ```development.json``` is not under source control.
* Component configuration can be added to ```www/master/components/<component name>/config/development.json``` and it will be combined with the main app config files and compiled into the intermediary ```www/master/shared/config/generated-config.js``` file.
* All ```generated-config.js``` is compiled into ```app.js```
* Production config can be generated using ```gulp config --env production``` or ```gulp --env production```
* The generated angular constant is named ```ENV``` with the shared root and each component having their own child configuration. For example,
`www/master/shared/config/development.json` and `www/master/shared/config/production.json` are used for application wide configuration in development and production, respectively.
* `www/master/shared/config/production.json` is kept under source control with default values for production.
* `www/master/shared/config/development.json` is not kept under source control. Each developer can create a local version of the file by copy, paste and rename from `www/master/shared/config/development.example.json`, which is kept under source control with default values for development.
The configuration files for the current build environment are compiled into the intermediary `www/master/shared/config/generated-config.js`, which is then compiled into `app.js`.
* Component configuration added to `www/master/components/<component name>/config/<environment>.json` is combined with the application wide configuration during the build.
The generated angular constant is named `ENV`. The shared configuration and component configurations each generate a nested object within it. For example:
```
www/master
├── shared/config/development.json
@@ -62,7 +94,8 @@ www/master
├── dashboard/config/development.json
└── my_component/config/development.json
```
produces ```www/master/shared/config/generated-config.js```:
generates the following in `www/master/shared/config/generated-config.js`:
```
angular.module('kubernetesApp.config', [])
.constant('ENV', {
@@ -73,56 +106,64 @@ angular.module('kubernetesApp.config', [])
```
#### 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=.*`.
You'll need to run ```hack/build-ui.sh``` to create a new ```pkg/ui/datafile.go``` file.
This is the file that is built-in to the kube-apiserver.
**RECOMMENDED**: When working in development mode the Kubernetes api server does not support CORS,
so the `kube-apiserver.service` must be started with
`--cors_allowed_origins=.*` or `--cors_allowed_origins=http://<your
host here>`
**HACKS**: If you don't want to/cannot restart the Kubernetes api server:
* Or you can start your browser with web security disabled. For
Chrome, you can [launch](http://www.chromium.org/developers/how-tos/run-chromium-with-flags) it with flag ```--disable-web-security```.
**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
See [master/components/README.md](master/components/README.md).
### Testing
Currently kubernetes/www includes both unit-testing (run via [Karma](http://karma-runner.github.io/0.12/index.html)) and
end-to-end testing (run via
[Protractor](http://angular.github.io/protractor/#/)).
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/#/).
#### Unittests via Karma
#### Unit testing with Karma
To run the existing Karma tests:
* Install the Karma CLI: `sudo npm install -g karma-cli` (it needs to
be installed globally, hence the `sudo` may be needed). Note that
the other Karma packages (such as `karma`, `karma-jasmine`, and
`karma-chrome-launcher` should be automatically installed when
running `npm start`).
* Go to the `www/master` directory, and run `karma start
karma.conf.js`. The Karma configuration is defined in `karma.config.js`. The console should show the test results.
To write new Karma tests:
* For testing each components, write test files (`*.spec.js`) under the
corresponding `www/master/components/**/test/modules/` directory.
* For testing the chrome and the framework, write test files
(*.spec.js) under the `www/master/test/modules/*` directory.
* 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).
```
sudo npm install -g karma-cli
```
#### End-to-end testing via Protractor
* Edit the Karma configuration in `www/master/karma.config.js`, if necessary.
* Run the tests. The console should show the test results.
```
cd www/master
karma start karma.conf.js
```
To run new Karma tests for a component, put new `*.spec.js` files under the appropriate `www/master/components/**/test/modules/*` directories.
To test the chrome, put new `*.spec.js` files under the appropriate `www/master/test/modules/*` directories.
#### End-to-end testing with Protractor
To run the existing Protractor tests:
* Install the CLIs: `sudo npm install -g protractor`.
* Start the webdriver server: `sudo webdriver-manager start`
* Start the kubernetes-ui app (see instructions above), assuming
running at port 8000.
* Go to the `www/master/protractor` directory and run `protractor
conf.js`. The protractor configuration is in `conf.js`. The console
should show the test results.
To write new protractor tests, put the test files (`*.spec.js`) in the
corresponding `www/master/components/**/protractor/` directory.
* Install the CLIs.
```
sudo npm install -g protractor
```
* Edit the test configuration in `www/master/protractor/conf.js`, if necessary.
* Start the webdriver server.
```
sudo webdriver-manager start
```
* Start the application (see instructions above), running at port 8000.
* Run the tests. The console should show the test results.
```
cd www/master/protractor
protractor conf.js
```
To run new protractor tests for a component, put new `*.spec.js` files in the appropriate `www/master/components/**/protractor/*` directories.
To test the chrome, put new `*.spec.js` files under the `www/master/protractor/chrome` directory.
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/www/README.md?pixel)]()