Improve awx/ui/README.md

2026-01-11 01:57:35 -03:30 · 2017-01-25 18:42:46 -05:00 · 2017-01-25 18:42:46 -05:00 · dfd7b5ca62
commit dfd7b5ca62
parent 35deb0be37
1 changed files with 68 additions and 51 deletions
--- a/awx/ui/README.md
+++ b/awx/ui/README.md
@ -1,68 +1,81 @@
-### Table of Contents
+# Ansible Tower UI

-1. [Requirements](#requirements)
-2. [Usage](#usage)
-3. [Testing](#testing)
-4. [Adding new dependencies](#deps)
-5. [Using libraries without modular exports/depedency management](#polyfill)
-6. [Environment configuration](#environment)
-7. [NPM scripts](#scripts)
+## Requirements

-### <a name="requirements">Requirements</a>
+### Node / NPM
+
+Tower currently requires the 6.x LTS version of Node and NPM.
+
+macOS installer: [https://nodejs.org/dist/latest-v6.x/node-v6.9.4.pkg](https://nodejs.org/dist/latest-v6.x/node-v6.9.4.pkg)
+
+RHEL / CentOS / Fedora:

-* A supported version of node + npm, constrained in `package.json`.
-```json
-"engines": {
-  "node": "^6.3.1",
-  "npm": "^3.10.3"
-}
 ```
-* C/C++ compiler tools, like GCC. Bundled in [Command Line Tools for Xcode](https://developer.apple.com/xcode/)
-* [node-gyp](https://github.com/nodejs/node-gyp)
-```
-npm install -g node-gyp
+$ curl --silent --location https://rpm.nodesource.com/setup_6.x | bash -
+$ yum install nodejs
 ```

-### <a name="usage">Usage</a>
+### Other Dependencies

-The following Makefile targets are available from the root dir of `ansible-tower`
+On macOS, install the Command Line Tools:

-**Native Docker**
-Specify the container ID of a `tools_tower` instance.
-`DOCKER_CID=containerID make ui-docker-cid`
+```
+$ xcode-select --install
+```

-**Docker Machine**
-Specify the name of a docker-machine.
-`DOCKER_MACHINE_NAME=default make ui-docker-machine`
+RHEL / CentOS / Fedora:

-Build a minified/uglified **release candidate**
-`make ui-release`
+```
+$ yum install bzip2 gcc-c++ git make
+```

-### <a name="testing">Testing</a>
+## Usage
+
+### Starting the UI
+
+First, the Tower API will need to be running. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+When using Docker for Mac or native Docker on Linux:
+
+```
+$ make ui-docker
+```
+
+When using Docker Machine:
+
+```
+$ DOCKER_MACHINE_NAME=default make ui-docker-machine
+```
+
+### Running Tests

 Run unit tests locally, poll for changes to both source and test files, launch tests in supported browser engines:
-`make ui-test`
+
+```
+$ make ui-test
+```

 Run unit tests in a CI environment (Jenkins)
-`make ui-test-ci`

-Run Protractor (E2E) tests in Saucelabs:
-`make ui-test-saucelabs`
+```
+$ make ui-test-ci
+```

-### <a name="deps">Adding new dependencies</a>
+### Adding new dependencies

-From the root dir of `ansible-tower`:

-#### Add/update a bundled vendor dependency
+#### Add / update a bundled vendor dependency
+
 1. `npm install --prefix awx/ui --save some-frontend-package@1.2.3`
 2. Add `'some-package'` to `var vendorFiles` in `./grunt-tasks/webpack.js`
 3. `npm  --prefix awx/ui shrinkwrap` to freeze current dependency resolution

-#### Add/update a dependecy in the build/test pipeline:
+#### Add / update a dependecy in the build/test pipeline
+
 1. `npm install --prefix awx/ui --save-dev some-toolchain-package@1.2.3`
 2. `npm  --prefix awx/ui shrinkwrap` to freeze current dependency resolution

-### <a name="polyfill">Polyfills, shims, patches</a>
+### Polyfills, shims, patches

 The Webpack pipeline will prefer module patterns in this order: CommonJS, AMD, UMD. For a comparison of supported patterns, refer to [https://webpack.github.io/docs/comparison.html](Webpack's docs).

@ -74,6 +87,7 @@ Some javascript libraries do not export their contents as a module, or depend on
 // Tower source code depends on the lodash library being available as _
 _.uniq([1,2,3,1]) // will throw error undefined
 ```
+
 ```js
 // webpack.config.js
 plugins: [
@ -82,6 +96,7 @@ plugins: [
  })
 ]
 ```
+
 ```js
 // the following requirement is inserted by webpack at build time
 var _ = require('lodash');
@ -89,12 +104,12 @@ _.uniq([1,2,3,1])
 ```

 2. Use [`imports-loader`](https://webpack.github.io/docs/shimming-modules.html#importing) to inject requirements into the namespace of vendor code at import time. Use [`exports-loader`](https://webpack.github.io/docs/shimming-modules.html#exporting) to conventionally export vendor code lacking a conventional export pattern.
-3.  [Apply a functional patch](https://gist.github.com/leigh-johnson/070159d3fd780d6d8da6e13625234bb3). A webpack plugin is the correct choice for a functional patch if your patch needs to access events in a build's lifecycle. A webpack loader is preferable if you need to compile and export a custom pattern of library modules.
-4.  [Submit patches to libraries without modular exports](https://github.com/leigh-johnson/ngToast/commit/fea95bb34d27687e414619b4f72c11735d909f93) - the internet will thank you
+3. [Apply a functional patch](https://gist.github.com/leigh-johnson/070159d3fd780d6d8da6e13625234bb3). A webpack plugin is the correct choice for a functional patch if your patch needs to access events in a build's lifecycle. A webpack loader is preferable if you need to compile and export a custom pattern of library modules.
+4. [Submit patches to libraries without modular exports](https://github.com/leigh-johnson/ngToast/commit/fea95bb34d27687e414619b4f72c11735d909f93) - the internet will thank you

 Some javascript libraries might only get one module pattern right.

-### <a name="environment">Environment configuration</a> - used in development/test builds
+### Environment configuration - used in development / test builds

 Build tasks are parameterized with environment variables.

@ -113,28 +128,30 @@ Environment variables can accessed in a Javascript via `PROCESS.env`.
 Example usage in `npm run build-docker-machine`:

 ```bash
-docker-machine ssh $DOCKER_MACHINE_NAME -f -N -L ${npm_package_config_websocket_port}:localhost:${npm_package_config_websocket_port}; ip=$(docker-machine ip $DOCKER_MACHINE_NAME); echo npm set ansible-tower:django_host ${ip}; grunt dev
+$ docker-machine ssh $DOCKER_MACHINE_NAME -f -N -L ${npm_package_config_websocket_port}:localhost:${npm_package_config_websocket_port}; ip=$(docker-machine ip $DOCKER_MACHINE_NAME); echo npm set ansible-tower:django_host ${ip}; $ grunt dev
 ```

 Example usage in an `npm test` script target:

-```bash
+```
 npm_package_config_websocket_port=mock_websocket_port npm_package_config_django_port=mock_api_port npm_package_config_django_host=mock_api_host npm run test:someMockIntegration
 ```

 You'll usually want to pipe and set vars prior to running a script target:
-```bash
-npm set ansible-tower:websocket_host ${mock_host}; npm run script-name
+```
+$ npm set ansible-tower:websocket_host ${mock_host}; npm run script-name
 ```

-### <a name="scripts">NPM Scripts</a>
+### NPM Scripts

 Examples:
 ```json
-  "scripts": {
-    "pretest": "echo I run immediately before 'npm test' executes",
-    "posttest": "echo I run immediately after 'npm test' exits",
-    "test": "karma start karma.conf.js"
+  {
+    "scripts": {
+      "pretest": "echo I run immediately before 'npm test' executes",
+      "posttest": "echo I run immediately after 'npm test' exits",
+      "test": "karma start karma.conf.js"
+    }
  }
 ```