Skip to content
This repository has been archived by the owner on Aug 5, 2018. It is now read-only.

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@yllierop
yllierop committed Jul 1, 2015
1 parent 83a51fc commit 201a855
Showing 1 changed file with 29 additions and 39 deletions.
68 changes: 29 additions & 39 deletions README.md
View file
Expand Up @@ -8,18 +8,18 @@ us manage and test the application. They are not part of the application. The fr
* 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/).

Before you build the application for the first time, run this command from the `www/master` directory:
Before you build the application for the first time, run this command from the `master` directory:

```
npm install
```

It creates a new directory, `www/master/node_modules`, which contains the tool dependencies.
It creates a new directory, `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:
To build the application for development, run this command from the `master` directory:

```
npm start
Expand All @@ -29,12 +29,12 @@ It runs `bower install` to install and/or update the framework dependencies, and

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:

* `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 files required to start the app. All of the dependencies referenced by this file are compiled into `base.js` and loaded before `app.js`.
* `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 `app/vendor`. (Note: some framework dependencies have been hand edited and checked into source control under `master/shared/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.)
The `app` directory and its contents are generated by the build. All of the other files 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

Expand All @@ -44,40 +44,30 @@ For development you can serve the files locally by installing a web server as fo
sudo npm install -g http-server
```

The server can then be launched from the `www/app` directory as follows:
The server can then be launched from the `app` directory as follows:

```
cd www/app
cd app
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.
`http-server` is convenient, since we're already using `npm`, but any web server hosting the `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:
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 `master/shared/config/development.json` and then rebuilding the application. For example, for a cluster running locally at `localhost:8080`, as described [here](https://github.com/GoogleCloudPlatform/kubernetes/tree/master/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
To build the application for production, run this command from the `www/master` directory:
To build the application for production, run this command from the `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:

Expand All @@ -95,32 +85,32 @@ https://<kubernetes-master>/static/app/
### 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.
`master/shared/config/development.json` and `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.
* `master/shared/config/production.json` is kept under source control with default values for production.
* `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 `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`.
The configuration files for the current build environment are compiled into the intermediary `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.
* Component configuration added to `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
master
├── shared/config/development.json
└── components
├── dashboard/config/development.json
└── my_component/config/development.json
```
generates the following in `www/master/shared/config/generated-config.js`:
generates the following in `master/shared/config/generated-config.js`:

```
angular.module('kubernetesApp.config', [])
.constant('ENV', {
'/': <www/master/shared/config/development.json>,
'dashboard': <www/master/components/dashboard/config/development.json>,
'my_component': <www/master/components/my_component/config/development.json>
'/': <master/shared/config/development.json>,
'dashboard': <master/components/dashboard/config/development.json>,
'my_component': <master/components/my_component/config/development.json>
});
```

Expand All @@ -145,17 +135,17 @@ To run the existing Karma tests:
sudo npm install -g karma-cli
```

* Edit the Karma configuration in `www/master/karma.config.js`, if necessary.
* Edit the Karma configuration in `master/karma.config.js`, if necessary.
* Run the tests. The console should show the test results.

```
cd www/master
cd 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 run new Karma tests for a component, put new `*.spec.js` files under the appropriate `master/components/**/test/modules/*` directories.

To test the chrome, put new `*.spec.js` files under the appropriate `www/master/test/modules/*` directories.
To test the chrome, put new `*.spec.js` files under the appropriate `master/test/modules/*` directories.

### End-to-end testing with Protractor
To run the existing Protractor tests:
Expand All @@ -166,7 +156,7 @@ To run the existing Protractor tests:
sudo npm install -g protractor
```

* Edit the test configuration in `www/master/protractor/conf.js`, if necessary.
* Edit the test configuration in `master/protractor/conf.js`, if necessary.
* Start the webdriver server.

```
Expand All @@ -177,12 +167,12 @@ sudo webdriver-manager start
* Run the tests. The console should show the test results.

```
cd www/master/protractor
cd 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 run new protractor tests for a component, put new `*.spec.js` files in the appropriate `master/components/**/protractor/*` directories.

To test the chrome, put new `*.spec.js` files under the `www/master/protractor/chrome` directory.
To test the chrome, put new `*.spec.js` files under the `master/protractor/chrome` directory.

[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/www/README.md?pixel)]()

0 comments on commit 201a855

Please sign in to comment.