[CORD-732] GUI Documentation
Change-Id: Ib2f86f9b646776868f314373de917ba4955bceea
(cherry picked from commit 896dd8b07378d856cb1bb0a3348980bb13de967e)
diff --git a/.gitignore b/.gitignore
index 9169b51..853a58d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,9 +1,10 @@
.idea/
.tmp/
.gitreview
-docs/
+docs/_book/
+_book/
coverage/
dist/
node_modules/
npm-debug.log
-typings/
+typings/
\ No newline at end of file
diff --git a/README.md b/README.md
index 7b369a6..33e9431 100644
--- a/README.md
+++ b/README.md
@@ -1,71 +1,22 @@
# XOS GUI
-**Experimental Feature**
+Welcome to the XOS GUI.
-This UI is currently hidden behind a flag and at the current state it is guaranteed as working only from the `frontend` config.
-#### Setup the correct environment:
-- Clone `opencord` using `repo`
-```
-repo init -u https://gerrit.opencord.org/manifest
-repo sync
-```
-- Download XOS patch to enable Redis notifications (waiting for the release to merge it)
-```
-cd orchestration/xos
-git review -d 1852
-```
+## Documentation
+You can find the documentation in the `docs` folder. It has been created using `gitbook` and can be consumed as a local website.
+To bring it up, just open a termina pointing to this folder and execute: `npm run docs`, then open a browser at `http://localhost:4000`
-#### Start the system
+## Support
-A vagrant VM is provided to make your life easier, so:
-```
-cd orchestration/service-profile/frontend
-vagrant up frontend
-vagrant ssh frontend # password is vagrant
-cd service-profile/frontend
-make local_containers
-make
-make experimental-ui
-```
-The new UI is now accessible at `http://<your-ip>` on port `80`
+For support please refer to:
-If you want to create some slices to have some data:
-```
-make slices
-```
+**Slack**<br/>
+[slackin.opencord.org](https://slackin.opencord.org/)
+**Mailing List**<br/>
+[CORD Discuss](https://groups.google.com/a/opencord.org/forum/#!forum/cord-discuss)<br/>
+[CORD Developers](https://groups.google.com/a/opencord.org/forum/#!forum/cord-dev)
-# Development
+**Wiki**<br/>
+[wiki.opencord.org](https://wiki.opencord.org/)
-This application can be executed on your system as long as you have `NodeJs` version 4 or higher.
-
-To start de development environment use: `npm start`
-
-## Configuration
-
-There are two configuration file available in the application, and they depend on the environment. You can find the various possibilities in `conf/app`, and they regard application constants, such as `apiEndpoint`, or branding elements, such as `projectName`.
-
-To load a different configration file you can use two environment variables:
-- `NODE_ENV`: to configure the app constants (eg: `dev`, `production`)
-- `BRAND`: to configure style constants (eg: `cord`, `opencloud`)
-
-# Test
-
-To commands come with the project:
-- `npm run test:auto` to watch source files and run test anytime they change, useful for development
-- `npm test` to run test once, this is the command triggered by Jenkins
-
-## Emulate a Synchronizer notification
-
-```
-redis-cli -h xos.dev
-
-# In progress
-PUBLISH Slice "{\"pk\": 19, \"object\": {\"id\": 19,\"name\": \"mysite_test_redis\", \"backend_status\": \"0 - In Progress\"}, \"changed_fields\": [\"updated\", \"backend_status\"]}"
-
-# Succes
-PUBLISH Slice "{\"pk\": 19, \"object\": {\"id\": 19,\"name\": \"mysite_test_redis\", \"backend_status\": \"1 - Success\"}, \"changed_fields\": [\"updated\", \"backend_status\"]}"
-
-# Error
-PUBLISH Slice "{\"pk\": 19, \"object\": {\"id\": 19,\"name\": \"mysite_test_redis\", \"backend_status\": \"2 - Error\"}, \"changed_fields\": [\"updated\", \"backend_status\"]}"
-```
diff --git a/book.json b/book.json
new file mode 100644
index 0000000..be589bb
--- /dev/null
+++ b/book.json
@@ -0,0 +1,4 @@
+{
+ "title": "XOS-GUI User Documentation",
+ "root": "./docs"
+}
\ No newline at end of file
diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md
new file mode 100644
index 0000000..ffadb1b
--- /dev/null
+++ b/docs/GLOSSARY.md
@@ -0,0 +1,5 @@
+## SPA
+A single-page application (SPA) is a web application or web site that fits on a single web page with the goal of providing a user experience similar to that of a desktop application.
+
+## xProto
+That's a modeling language built on top of Google's Protocol Buffer.
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..1391e31
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,18 @@
+# XOS GUI User Manual
+
+Welcome the User Manual for the XOS GUI, your visual interface to operate on XOS.
+
+## Overview
+The XOS User Interfaced is developed as a single page application (from now on referred as SPA)
+and the main tools used are:
+ - [Angular Js](https://angularjs.org/)
+ - [Typescript](https://www.typescriptlang.org/)
+ - [RxJS](http://reactivex.io/rxjs/)
+
+## General information
+
+The XOS GUI is available trough the OpenCORD gerrit at: https://gerrit.opencord.org/#/admin/projects/xos-gui
+
+> For instructions on how to get the code please refer to:
+> - https://wiki.opencord.org/display/CORD/Working+with+Gerrit
+> - https://wiki.opencord.org/display/CORD/Setting+up+and+using+REPO
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
new file mode 100644
index 0000000..83e18cb
--- /dev/null
+++ b/docs/SUMMARY.md
@@ -0,0 +1,12 @@
+# Summary
+
+* [Introduction](README.md)
+
+* [Architectural Overview](architecture/README.md)
+ * [Module Strucure](architecture/gui-modules.md)
+ * [Data Sources](architecture/data-sources.md)
+
+* [Developer Guide](developer/README.md)
+ * [Quickstart](developer/quickstart.md)
+ * [Tests](developer/tests.md)
+ * [GUI Extensions](developer/gui_extensions.md)
\ No newline at end of file
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
new file mode 100644
index 0000000..2ed1154
--- /dev/null
+++ b/docs/architecture/README.md
@@ -0,0 +1,31 @@
+# Architectural Overview
+
+This chapter will guide you trough the general architecture of the XOS User Interfaces
+
+## Ecosystem
+
+The XOS GUI is design to work in the XOS ecosystem, taking advantages of some of the features exposed by it.
+As an example the application is designed to discover the models registered in XOS
+and auto-generate CRUD views for all of them, feature that is available thanks to our xProto modeling language.
+We are also leveraging the XOS-WS component, build on top of our Redis based pub-sub system, to provide a progressive caching mechanism.
+
+The GUI ecosystem in XOS is composed by a pod of 5 Docker containers that comunicate as per the following diagram:
+
+
+
+We'll talk deeper about the data flow in the [Developer Guide](../developer/README.md) but here is the main role of each component:
+
+#### XOS-CORE
+Is hosting the entire data-model and expose a `gRPC` API layer to let other components interact with the data model.
+
+#### CHAMELEON
+Chameleon is reponsible to expose a description of the models stored in `XOS-CORE` and to provide the bindings between `REST` and `gRPC`
+
+#### REDIS
+It is hosting a `redis` server used as primary pub-sub mechanism in the system
+
+#### XOS-WS
+Listen to `redis` events and transform them into `web-sockets` events in order to keep `XOS-GUI` updated
+
+#### XOS-GUI
+Is hosting the GUI SPA and exposing it to the world through a web-server, in this case `nginx`
\ No newline at end of file
diff --git a/docs/architecture/data-sources.md b/docs/architecture/data-sources.md
new file mode 100644
index 0000000..fe60491
--- /dev/null
+++ b/docs/architecture/data-sources.md
@@ -0,0 +1,19 @@
+# The Data Sources module and the observable pattern
+
+The Data Source module is the actual glue between the Single Page Application and XOS and is responsible to keep data up to date in the UI. It use a combination of REST APIs (used to fetch the initial data) and Websocket events (used to incrementally extend those data) and create a set of Observables.
+
+An observable is basically a sequence of ongoing events ordered in time, to know more about this topics you can start here: [The introduction to Reactive Programming you've been missing](https://gist.github.com/staltz/868e7e9bc2a7b8c1f754)
+
+The way synchronization is achieved follow this pattern:
+- When the application is loaded we read all the core model definition from the backend
+- For each Core Model
+ - we read the existing data
+ - we store them in an Observable
+ - we generate a configuration for tables and forms
+- Any view that need those data require the Model Observable and the Model Configuration
+- For any Websocket event we trigger a new event in the related Observable
+
+
+
+You can see an example of this behavior in `/src/app/views/crud/crud.ts`.
+This view is responsible to auto-generate a CRUD interface for each model in the system.
\ No newline at end of file
diff --git a/docs/architecture/gui-modules.md b/docs/architecture/gui-modules.md
new file mode 100644
index 0000000..badb066
--- /dev/null
+++ b/docs/architecture/gui-modules.md
@@ -0,0 +1,13 @@
+# GUI Modules
+
+The application is divided into Modules, each one responsible for a different topic, here is a short list of the modules and their area of focus:
+
+
+| Module | Topic |
+|--------|-------|
+| Template | Manage all the features related to the visualization of the template|
+| Views | Holds core custom views and the template for the auto-generated CRUD views for models |
+| Core | Formerly called xosNgLib, contains a set of UI components to render table, forms, ... |
+| [DataSources](./data-sources.md) | Is the actual glue between the UI and the data model. It use a combination of REST API and Websocket to return data as Observables. |
+| Extender | It is responsible to extend the application with custom extension provided by services |
+| Service Graph | It's job is to read the service definition from the backend and represent it in a visual form, both at system and subscriber level |
\ No newline at end of file
diff --git a/docs/architecture/images/data-source-flow.png b/docs/architecture/images/data-source-flow.png
new file mode 100644
index 0000000..b3b94c7
--- /dev/null
+++ b/docs/architecture/images/data-source-flow.png
Binary files differ
diff --git a/docs/architecture/images/xos-gui-ecosystem.png b/docs/architecture/images/xos-gui-ecosystem.png
new file mode 100644
index 0000000..7947311
--- /dev/null
+++ b/docs/architecture/images/xos-gui-ecosystem.png
Binary files differ
diff --git a/docs/developer/README.md b/docs/developer/README.md
new file mode 100644
index 0000000..c4b57de
--- /dev/null
+++ b/docs/developer/README.md
@@ -0,0 +1,6 @@
+# Developer Guide
+
+In order to contribute to the XOS-GUI you'll need to have few tools installed:
+- [Vagrant](https://www.vagrantup.com/)
+- [NodeJs](https://nodejs.org/en/)
+- [repo](https://code.google.com/p/git-repo/) You can find instructions on the [wiki](https://wiki.opencord.org/display/CORD/Getting+the+Source+Code)
\ No newline at end of file
diff --git a/docs/developer/gui_extensions.md b/docs/developer/gui_extensions.md
new file mode 100644
index 0000000..b299283
--- /dev/null
+++ b/docs/developer/gui_extensions.md
@@ -0,0 +1,56 @@
+# Create a custom GUI Extension
+
+The CORD GUI is designed to be extensible. There are two cases in which we envision an extension to be needed:
+- Provide a different view over data
+- Create custom interfaces for services
+
+The development process for the two cases it's absolutely the same.
+
+We suggest to get started by duplicating [xos-sample-gui-extension](https://github.com/opencord/xos-sample-gui-extension)
+
+## Development
+
+The development environment is the same as `xos-gui` so you can use the `npm start` command and augment it with the same sets fo environment variables.
+The dev server is going to proxy your requests to the appropriate backend and load the base application from it.
+
+## Add an extension to a profile
+
+To deploy your GUI extension with a cord profile you'll need to reference it in `platform-install`.
+
+Open the `profile-manifest` you're working on (eg: profile_manifests/frontend.yml) and locate `enabled_gui_extensions`.
+It may appear in two forms, depending whether or not there are others loaded extensions:
+```yaml
+enabled_gui_extensions:
+ - name: sample
+ path: orchestration/xos-sample-gui-extension
+```
+or:
+```yaml
+enabled_gui_extensions: []
+```
+_NOTE: if it is not there, just create it_
+
+To add your extension, just add it to the list:
+```yaml
+enabled_gui_extensions:
+ - name: sample
+ path: orchestration/xos-sample-gui-extension
+ - name: myextension
+ path: orchestration/myextension
+```
+_NOTE: if it was defined as an empty array you'll need to remove the square brackets (`[]`)_
+
+The `name` field must match the directory in which the GUI Extension is built. You can update it in `conf/gulp.conf.js`, just locate:
+```js
+exports.paths = {
+ src: 'src',
+ dist: 'dist/extensions/sample', // NOTE that 'sample' have to match the extension name provided in platform install
+ appConfig: 'conf/app',
+ tmp: '.tmp',
+ e2e: 'e2e',
+ tasks: 'gulp_tasks'
+};
+```
+and replace `sample` with the appropriate name.
+
+The `path` field identify the directory (starting from the `repo` root), in which your extension is stored. As now is not supported the loading from external sources.
\ No newline at end of file
diff --git a/docs/developer/quickstart.md b/docs/developer/quickstart.md
new file mode 100644
index 0000000..c82dfe7
--- /dev/null
+++ b/docs/developer/quickstart.md
@@ -0,0 +1,60 @@
+# GUI Quickstart
+
+_We assume that you already have the code downloaded with `repo`_
+
+## Setting up the `frontend` configuration
+
+The easiest to work on the XOS GUI is to create a local deployment of the `frontend` configuration of CORD.
+
+You can find detailed instructions in the `platform-install` documentation, but for all that we need you can:
+
+```
+cd opencord/build/platform-install
+vagrant up head-node
+vagrant ssh
+// you're now inside the vagrant VM
+cd cord/buid/platform-install
+ansible-playbook -i inventory/frontend deploy-xos-playbook.yml
+```
+
+
+> This commands will spin up a local vm and deploy the minimal configuration of CORD in it. <br/>
+> _NOTE the first you'll execute this commands they may take a long time (~20 min)_
+
+#### Retrieve the password to access XOS
+```
+cat ~/cord/buid/platform-install/credentials/xosadmin@opencord.org
+// save the output somewhere
+```
+
+## Serving the GUI in development mode
+
+Once your basic CORD config is up and running you should be able to access the GUI at `http://192.168.46.100/xos/`
+but that's not your development copy, it is the one deployed inside a container in XOS.
+
+To launch a development copy:
+```
+// back to your local system
+cd opencord/orchestration/xos-gui
+npm install
+npm start
+```
+
+It will open your default browser at `localhost:3000`, proxy your API request to the local environment and watch for file changes.
+
+**Now you're ready to start working on it!**
+
+To get start, login using username `xosadmin@opencord.org` and the password you previously saved,
+then pick any file and make a change, you'll see the GUI reload.
+
+### Configuring the `dev` GUI
+
+There are two configuration file available in the application, and they depend on the environment. You can find the various possibilities in `conf/app`, and they regard application constants, such as `apiEndpoint`, or branding elements, such as `projectName`.
+
+To load a different configration file you can use two environment variables:
+- `NODE_ENV`: to configure the app constants (eg: `dev`, `production`)
+- `BRAND`: to configure style constants (eg: `cord`, `opencloud`)
+
+You can also specify a different installation of XOS as backend by using the `PROXY` environment variable.
+For example you can connect to a remote CORD-in-a-box installation for debugging purposes with:
+`PROXY=ms1106.utah.cloudlab.us:8080 npm start`
diff --git a/docs/developer/tests.md b/docs/developer/tests.md
new file mode 100644
index 0000000..9e4ffa1
--- /dev/null
+++ b/docs/developer/tests.md
@@ -0,0 +1,51 @@
+# Test
+
+## Unit Tests
+
+There is a quite extensive suite of Unit Tests that are provided along with the code to help your development.
+
+These tests are defined using [Karma](https://karma-runner.github.io/1.0/index.html) as test runner and [Jasmine](https://jasmine.github.io/) as assertion library. Test are defied along with the code, you can look for any `.spec.ts` file in the source tree.
+
+You can execute them in two flavors:
+- Single run (this is the same flavor that is used on Jenkins): `npm test`
+- Watch mode: `npm run test:auto`
+
+While developing the GUI we'll suggest you to run the test in watch mode, and they'll be executed anytime a file changes. It will help you in catchings bugs immediately. It also provide more information on which tests are executed.
+
+## End to End Tests
+
+There is a suite of basic end to test that are defined using [protractor](http://www.protractortest.org/#/), an AngularJs oriented version of Selenium.
+
+These tests can be found in the `e2e` folder.
+
+_NOTE: Require protractor to be installed as a global module._
+
+### Setup
+```
+webdriver-manager update
+webdriver-manager start
+```
+
+### Run the tests
+
+_Note that this tests are designed to work with the Mock R-CORD config_
+
+```
+protractor conf/protractor.conf.js
+```
+
+Other paramenters you can pass are:
+
+| Variable Name | Description |
+|---------------|--------------------------------------------------------------|
+| UI_URL | Address of the GUI (deaults to `http://192.168.46.100/spa/#` |
+| UI_PWD | Password to login (needed only for remote connections) |
+| TIMEOUT | Time allowed for each test |
+
+ #### Test suites
+
+ If you need to run test for only a particural suite you can use:
+
+ `protractor conf/protractor.conf.js --suite login`
+
+ Suites are defined in `cong/protractor.conf.js`
\ No newline at end of file
diff --git a/e2e/README.md b/e2e/README.md
index a578c20..daa5607 100644
--- a/e2e/README.md
+++ b/e2e/README.md
@@ -1,33 +1 @@
-# End to end test
-
-NOTE: Require protractor to be installed as a global module.
-
-## Setup
-```
-webdriver-manager update
-webdriver-manager start
-```
-
-## Run tests
-
-_Note that this tests are designed to work with the Mock R-CORD config_
-
-```
-protractor conf/protractor.conf.js
-```
-
-Other paramenters you can pass are:
-
-| Variable Name | Description |
-|---------------|--------------------------------------------------------------|
-| UI_URL | Address of the GUI (deaults to `http://192.168.46.100/spa/#` |
-| UI_PWD | Password to login (needed only for remote connections) |
-| TIMEOUT | Time allowed for each test |
-
- ### Test suites
-
- If you need to run test for only a particural suite you can use:
-
- `protractor conf/protractor.conf.js --suite login`
-
- Suites are defined in `cong/protractor.conf.js`
\ No newline at end of file
+Look at `docs/developer/tests.md` for usage instructions
\ No newline at end of file
diff --git a/package.json b/package.json
index 2307f81..de96c72 100644
--- a/package.json
+++ b/package.json
@@ -41,6 +41,7 @@
"eslint-plugin-babel": "3.3.0",
"extract-text-webpack-plugin": "2.0.0-beta.3",
"file-loader": "0.9.0",
+ "gitbook-cli": "^2.3.0",
"gulp": "gulpjs/gulp#4ed9a4a3275559c73a396eff7e1fde3824951ebb",
"gulp-angular-filesort": "1.1.1",
"gulp-angular-templatecache": "1.9.1",
@@ -100,7 +101,8 @@
"test:auto": "gulp test:auto",
"test:e2e": "protractor conf/protractor.conf.js",
"config": "gulp config",
- "lint": "tslint -c ./tslint.json 'src/**/*.ts'"
+ "lint": "tslint -c ./tslint.json 'src/**/*.ts'",
+ "docs": "gitbook serve"
},
"eslintConfig": {
"globals": {
