luxolus
/
open-nomad
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-nomad/ui/README.md

103 lines
5.1 KiB
Markdown
Raw Normal View History

sync
2017-09-19 14:47:10 +00:00
# Nomad UI
The official Nomad UI.
## Prerequisites
This is an [ember.js](https://emberjs.com/) project, and you will need the following tools installed on your computer.
add some ui development tips
2019-09-17 12:38:11 +00:00
* [Node.js v10](https://nodejs.org/)
sync
2017-09-19 14:47:10 +00:00
* [Yarn](https://yarnpkg.com)
* [Ember CLI](https://ember-cli.com/)
## Installation
The Nomad UI gets cloned along with the rest of Nomad. To install dependencies, do the following from the root of the Nomad project:
```
$ cd ui
$ yarn
```
## Running / Development
add some ui development tips
2019-09-17 12:38:11 +00:00
UI in development mode defaults to using fake generated data, but you can configure it to proxy a live running nomad process by setting `USE_MIRAGE` environment variable to `false`. First, make sure nomad is running. The UI, in development mode, runs independently from Nomad, so this could be an official release or a dev branch. Likewise, Nomad can be running in server mode or dev mode. As long as the API is accessible, the UI will work as expected.
sync
2017-09-19 14:47:10 +00:00
add some ui development tips
2019-09-17 12:38:11 +00:00
* `USE_MIRAGE=false ember serve`
sync
2017-09-19 14:47:10 +00:00
* Visit your app at [http://localhost:4200](http://localhost:4200).
add some ui development tips
2019-09-17 12:38:11 +00:00
You may need to reference the direct path to `ember`, typically in `./node_modules/.bin/ember`.
UI: Change Mirage data to be stable in development (#6389) This sets a default-but-query-configurable Faker seed in development, via faker-seed. It also changes uses of Math.random to use Faker’s randomness so auto-generated data remains stable in development.
2019-10-03 14:13:08 +00:00
The fake data in development is generated from a stable seed of 1. To generate different data, you can include a query parameter of `?faker-seed=2` or any other number in the URL. To turn off the seed and get different data with every load, use `?faker=seed=0`.
Add query parameter to override Mirage scenario (#9380)
2020-11-30 14:12:15 +00:00
When running with Mirage, the default scenario is set in `config/environment.js` but can be overridden with a query parameter to any of the scenarios named in `mirage/scenarios/default.js` with something like `?mirage-scenario=emptyCluster`.
sync
2017-09-19 14:47:10 +00:00
## Running / Development with Vagrant
All necessary tools for UI development are installed as part of the Vagrantfile. This is primarily to make it easy to build the UI from source while working on Nomad. Due to the filesystem requirements of [Broccoli](http://broccolijs.com/) (which powers Ember CLI), it is strongly discouraged to use Vagrant for developing changes to the UI.
That said, development with Vagrant is still possible, but the `ember serve` command requires two modifications:
* `--watch polling`: This allows the vm to notice file changes made in the host environment.
* `--port 4201`: The default port 4200 is not forwarded, since local development is recommended.
This makes the full command for running the UI in development mode in Vagrant:
```
$ ember serve --watch polling --port 4201
```
### Running Tests
Nomad UI tests can be run independently of Nomad golang tests.
* `ember test` (single run, headless browser)
* `ember test --server` (watches for changes, runs in a full browser)
add some ui development tips
2019-09-17 12:38:11 +00:00
You can use `--filter <test name>` to run a targetted set of tests, e.g. `ember test --filter 'allocation detail'`.
Upgrade to Ember 3.4
2019-03-15 20:26:18 +00:00
UI: Change Mirage data to be stable in development (#6389) This sets a default-but-query-configurable Faker seed in development, via faker-seed. It also changes uses of Math.random to use Faker’s randomness so auto-generated data remains stable in development.
2019-10-03 14:13:08 +00:00
In the test environment, the fake data is generated with a random seed. If you want stable data, you can set a seed while running the test server by appending `&faker-seed=1` (or any other non-zero number) to the URL.
Upgrade to Ember 3.4
2019-03-15 20:26:18 +00:00
### Linting
Linting should happen automatically in your editor and when committing changes, but it can also be invoked manually.
* `npm run lint:hbs`
* `npm run lint:js`
* `npm run lint:js -- --fix`
sync
2017-09-19 14:47:10 +00:00
### Building
Typically `make release` or `make dev-ui` will be the desired build workflow, but in the event that build artifacts need to be inspected, `ember build` will output compiled files in `ui/dist`.
* `ember build` (development)
* `ember build --environment production` (production)
### Releasing
Nomad UI releases are in lockstep with Nomad releases and are integrated into the `make release` toolchain.
add some ui development tips
2019-09-17 12:38:11 +00:00
### Conventions
* UI branches should be prefix with `f-ui-` for feature work and `b-ui-` for bug fixes. This instructs CI to skip running nomad backend tests.
UI: Migrate to Storybook (#6507) I originally planned to add component documentation, but as this dragged on and I found that JSDoc-to-Markdown sometimes needed hand-tuning, I decided to skip it and focus on replicating what was already present in Freestyle. Adding documentation is a finite task that can be revisited in the future. My goal was to migrate everything from Freestyle with as few changes as possible. Some adaptations that I found necessary: • the DelayedArray and DelayedTruth utilities that delay component rendering until slightly after initial render because without them: ◦ charts were rendering with zero width ◦ the JSON viewer was rendering with empty content • Storybook in Ember renders components in a routerless/controllerless context by default, so some component stories needed changes: ◦ table pagination/sorting stories access to query params, which necessitates some reaching into Ember internals to start routing and dynamically generate a Storybook route/controller to render components into ◦ some stories have a faux controller as part of their Storybook context that hosts setInterval-linked dynamic computed properties • some jiggery-pokery with anchor tags ◦ inert href='#' had to become href='javascript:; ◦ links that are actually meant to navigate need target='_parent' so they don’t navigate inside the Storybook iframe Maybe some of these could be addressed by fixes in ember-cli-storybook but I’m wary of digging around in there any more than I already have, as I’ve lost a lot of time to Storybook confusion and frustrations already 😞 The STORYBOOK=true environment variable tweaks some environment settings to get things working as expected in the Storybook context. I chose to: • use angle bracket invocation within stories rather than have to migrate them soon after having moved to Storybook • keep Freestyle around for now for its palette and typeface components
2020-01-21 21:46:32 +00:00
### Storybook UI Library
Migrate preview deployments from Netlify to Vercel (#9471) This adds: * a script for building and deploying the Ember UI and Storybook to Vercel * configuration for that deployment * a header link to the UI to link to Storybook when built with STORYBOOK_LINK=true It also removes a file used to configure Netlify redirects. The Netlify setup had two “sites”: nomad-storybook and nomad-ui. I attempted to replicate that here but ran into some platform limitations with Vercel: two “projects” cannot share the same root directory without also sharing the same vercel.json that lets us specify configuration such as the rewrite needed to handle deep linking into the Ember UI. I tried having Storybook use /ui/storybook as the root directory (and adding a symbolically-linked package.json to bypass Vercel’s refusal to build without it) but that produced broken Storybook deployments. This instead combines the two projects into one (nomad-storybook-and-ui), defaults to forwarding / to /ui/, and adds the header link to the UI to navigate to Storybook. Rather than have a complex build script in the Vercel configuration UI, this delegates to a script in the repository.
2020-12-07 14:33:49 +00:00
The Storybook project provides a browser to see what components and patterns are present in the application and how to use them. You can run it locally with `yarn storybook` after you have `ember serve` running. The latest version from the `master` branch is at [`nomad-storybook-and-ui.vercel.app/storybook/`](https://nomad-storybook-and-ui.vercel.app/storybook/).
UI: Migrate to Storybook (#6507) I originally planned to add component documentation, but as this dragged on and I found that JSDoc-to-Markdown sometimes needed hand-tuning, I decided to skip it and focus on replicating what was already present in Freestyle. Adding documentation is a finite task that can be revisited in the future. My goal was to migrate everything from Freestyle with as few changes as possible. Some adaptations that I found necessary: • the DelayedArray and DelayedTruth utilities that delay component rendering until slightly after initial render because without them: ◦ charts were rendering with zero width ◦ the JSON viewer was rendering with empty content • Storybook in Ember renders components in a routerless/controllerless context by default, so some component stories needed changes: ◦ table pagination/sorting stories access to query params, which necessitates some reaching into Ember internals to start routing and dynamically generate a Storybook route/controller to render components into ◦ some stories have a faux controller as part of their Storybook context that hosts setInterval-linked dynamic computed properties • some jiggery-pokery with anchor tags ◦ inert href='#' had to become href='javascript:; ◦ links that are actually meant to navigate need target='_parent' so they don’t navigate inside the Storybook iframe Maybe some of these could be addressed by fixes in ember-cli-storybook but I’m wary of digging around in there any more than I already have, as I’ve lost a lot of time to Storybook confusion and frustrations already 😞 The STORYBOOK=true environment variable tweaks some environment settings to get things working as expected in the Storybook context. I chose to: • use angle bracket invocation within stories rather than have to migrate them soon after having moved to Storybook • keep Freestyle around for now for its palette and typeface components
2020-01-21 21:46:32 +00:00
To generate a new story for a component, run `ember generate story component-name`. You can use the existing stories as a guide.
sync
2017-09-19 14:47:10 +00:00
### Troubleshooting
#### The UI is running, but none of the API requests are working
add some ui development tips
2019-09-17 12:38:11 +00:00
By default (according to the `.ember-cli` file), a proxy address of `http://localhost:4646` is used. If you are running Nomad at a different address, you will need to override this setting when running ember serve: `ember serve --proxy http://newlocation:1111`.
Also, ensure that `USE_MIRAGE` environment variable is set to false, so the UI proxy requests to Nomad process instead of using autogenerated test data.
sync
2017-09-19 14:47:10 +00:00
#### Nomad is running in Vagrant, but I can't access the API from my host machine
Nomad binds to `127.0.0.1:4646` by default, which is the loopback address. Try running nomad bound to `0.0.0.0`: `bin/nomad -bind 0.0.0.0`.
Ports also need to be forwarded in the Vagrantfile. 4646 is already forwarded, but if a port other than the default is being used, that port needs to be added to the Vagrantfile and `vagrant reload` needs to be run.