[CE-145] Fix documentation structure and links

* Re-struct the documentation * Add necessary links to help explore quickly * Fix several places of documentation content Change-Id: I7eaeecc823d6949218a9b1b7652c37705d2a5849 Signed-off-by: Baohua Yang <yangbaohua@gmail.com>
hyperledger · Sep 23, 2017 · 93429cd · 93429cd
1 parent a552dd2
commit 93429cd
Show file tree

Hide file tree

Showing 13 changed files with 159 additions and 87 deletions.
diff --git a/docs/dashboard.md b/docs/dashboard.md
@@ -1,6 +1,6 @@
 # Dashboard
 
-By default, the dashboard will listen on port `8080` at the Master Node.
+By default, the dashboard will listen on port `8080` at the Master Node, and operators can login in with default `admin:pass` credential.
 
 The left panel gives quick link to various functions, including `overview`, `system status`, `Hosts`, `Active Clusters`, `Inused Clusters`, `Release History` and `About`.
 
@@ -71,5 +71,4 @@ Filter out those running chains that are occupied by users.
 
 Record all the user releasing chain history.
 
-
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
diff --git a/docs/imgs/deploy_arch.png b/docs/imgs/deploy_arch.png
diff --git a/docs/index.md b/docs/index.md
@@ -3,44 +3,52 @@ Welcome to Hyperledger Cello
 
 Hyperledger Cello is a blockchain provision and operation system, which helps manage blockchain networks.
 
+![Typical Scenario](imgs/scenario.png)
+
 Hyperledger Cello is designed with the following features:
 
 * Manage the lifecycle of blockchains, e.g., create/start/stop/delete/keep health automatically.
 * Support customized (e.g., size, consensus) blockchains request, currently we mainly support [Hyperledger fabric](https://github.com/hyperledger/fabric).
-* Support native Docker host, swarm or Kubernetes as the worker nodes. More supports on the way.
+* Support bare-metal, virtual machine, native [Docker](https://www.docker.com/) host, swarm or [Kubernetes](https://kubernetes.io/) as the worker nodes. More supports on the way.
 * Support heterogeneous architecture, e.g., X86, POWER and Z, from bare-metal servers to virtual machine clouds.
 * Extend with monitor, log, health and analytics features by employing additional components.
 
-Using Cello, every Blockchain application developer can:
+Using Cello, Blockchain application developers can:
 
 * Build up a Blockchain as a Service (BaaS) platform quickly from the scratch.
 * Provision customizable Blockchains instantly, e.g., a Hyperledger fabric network v1.0.
-* Maintain a pool of running blockchain networks on top of baremetals, Virtual Clouds (e.g., virtual machines, vsphere Clouds), Container clusters (e.g., Docker, Swarm, Kubernetes).
+* Maintain a pool of running blockchain networks on top of baremetals, virtual clouds (e.g., virtual machines, vsphere Clouds), container clusters (e.g., Docker, Swarm, Kubernetes).
 * Check the system status, adjust the chain numbers, scale resources... through dashboards.
 
-A typical usage scenario is illustrated as:
-
-![Typical Scenario](imgs/scenario.png)
+## [Getting Started](tutorial)
 
-## Getting Started
+For new users, it is highly recommended to read the [Tutorial for Beginners](tutorial) first.
 
-For new users, it is highly recommended to read the [tutorial](tutorial) first.
-
-## Operational Guideline
-* [New User Tutorial](tutorial)
-* [Installation Steps](installation)
-* [Terminologies List](terminology)
+## Operation Guideline
+* [Terminology and Concept](terminology)
+* [Installation](installation)
 * [Adoption Scenarios](scenario)
-* [Production Configuration](production_config)
+* [Configuration for Production](production_config)
+* [Manage Cello services](service_management)
 
-## Development Guideline
-* [How to contribute](CONTRIBUTING)
+## Contribute to the Project
+* [How to Contribute](CONTRIBUTING)
+* [Coding Style](code_style)
+* [PEP8 Style Guide](https://www.python.org/dev/peps/pep-0008/)
+* [Develop react js](reactjs)
+
+## Design Documentation
 * [Architecture Design](arch)
 * [Database Model](db)
 * [API Design](api/restserver_v2)
-* [Wikipage](https://wiki.hyperledger.org/projects/cello)
-* [Develop react js](reactjs)
-* [Coding Style](code_style)
-* [Pep8 style guide](https://www.python.org/dev/peps/pep-0008/)
+
+## Communication Channels
+
+For additional helps, feel free to take the following channels:
+
+* [Wikipage](https://wiki.hyperledger.org/projects/cello): Lots of information and documentation about the project.
+* [Jira Board](https://jira.hyperledger.org/projects/CE/issues): Find development status, report bug, or help contribute code.
+* [Mail List](mailto:hyperledger-cello@lists.hyperledger.org): General discussions with Cello project.
+* [Rocket.Chat channels](https://chat.hyperledger.org/channel/cello): Real-time technical conversations.
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
diff --git a/docs/installation.md b/docs/installation.md
@@ -1,35 +1,27 @@
 # Installation
 
-*Here we describe the setups for development usage. If you want to deploy Cello for production, please also refer to the [Production Configuration](production_config.md).*
+Cello follows a typical Master-Worker architecture. There are two types of Nodes in the cluster.
 
-Cello follows a typical Master-Worker architecture. Hence there will be two types of Nodes.
+* Master Node: Holds [Cello services](service_management.md) to manage (e.g., create/delete) the chains inside Work Nodes. Usually, Master Node will provide Web dashboard (port `8080`) and RESTful api (port `80`). It is recommended to use Linux (e.g., Ubuntu 14.04+) or MacOS;
+* Worker Node: Nodes to hold blockchains. Take Docker Host or Swarm Cluster for example, the Docker daemon should be accessible (typically at port `2375`) from the Master Node.
 
-* Master Node: Manage (e.g., create/delete) the chains inside Work Nodes, with Web dashboard listening on port `8080` and RESTful api on port `80`;
-* Worker Node: Chain providers, now support Docker Host or Swarm Cluster. The Docker service should be accessible from port `2375` from the Master Node.
+![Deployment topology](imgs/deploy_arch.png)
 
-![Deployment topology](imgs/deployment_topo.png)
+## Master Node
 
-For each Node, it is suggested as a Linux-based (e.g., Ubuntu 14.04+) server/vm:
+See [Installation on Master Node](installation_master.md).
 
 ## Worker Node
 
 Currently we support Docker Host or Swarm Cluster as Worker Node. More types will be added soon.
 
-`Docker Host`: See [Installation on Worker Docker Node](installation_worker_docker.md).
-`Docker Swarm `: TODO.
-`Kubernetes`: TODO.
-`vSphere`: TODO.
-
-## Master Node
-
-See [Installation on Master Node](installation_master.md).
-
-### Make Command
-
-A Makefile is provided to help setup the master node, please refer [make_support](/make_support.md) page.
+* `Docker Host`: See [Installation on Worker Docker Node](installation_worker_docker.md).
+* `Docker Swarm `: See [Create a Docker Swarm](https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/).
+* `Kubernetes`: See [Kubernetes Setup](https://kubernetes.io/docs/setup/).
+* `vSphere`: TODO.
 
+## Special Configuration for Production
 
-*Licensed under Creative Commons Attribution 4.0 International License
-   https://creativecommons.org/licenses/by/4.0/*
+Here we describe the setups for development usage. If you want to deploy Cello for production, please also refer to the [Production Configuration](production_config.md).
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
diff --git a/docs/installation_master.md b/docs/installation_master.md
@@ -81,3 +81,5 @@ By default, it also loads the `config.py` file as the configurations.
 The mongo container will use local `/opt/cello/mongo` directory for persistent storage.
 
 Please keep it safe by backups or using more high-available solutions.
+
+<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
diff --git a/docs/installation_worker_docker.md b/docs/installation_worker_docker.md
@@ -74,4 +74,6 @@ Make sure ip forward is enabled, you can simply run the follow command.
 ```sh
 $ sysctl -w net.ipv4.ip_forward=1
 ```
-And check the os iptables config, to make sure host ports are open (e.g., 2375, 7050~10000)
+And check the os iptables config, to make sure host ports are open (e.g., 2375, 7050~10000)
+
+<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
diff --git a/docs/make_support.md b/docs/make_support.md
@@ -1,18 +1,18 @@
-## Operations Supported
-### make
+## Supported Make Commands
 
-The following opperations are supported by make command. Prepend the following commands with make.
+The following opperations are supported by [Make](https://en.wikipedia.org/wiki/Makefile) command. Prepend the following commands with make.
 
 These commands should be run in `cello` directory, for example: `/cello$ make all`.
 
 ### all
-Default to run check. Runs check.
+Default to run the testing cases.
 
 ### build-js
 Builds js files for react.
 
 ### check
 CI checking. Runs the following commands. This runs the following commands for you.
+
 ```sh
 $ tox
 $ make start && sleep 10 && make stop
@@ -21,13 +21,15 @@ $ make start && sleep 10 && make stop
 ### clean
 Cleans up the environment and removes temp files like .cache, .tox, .pyc.
 It runs the following commands for you.
+
 ```sh
 $ rm -rf .tox .cache *.egg-info
 $ find . -name "*.pyc" -o -name "__pycache__" -exec rm -rf "{}" \;
 ```
 
 ### doc
 Starts a doc server locally. It runs the following commands for you.
+
 ```sh
 $ pip install mkdocs
 $ mkdocs serve
@@ -38,6 +40,7 @@ Show help.
 
 ### image-clean
 Cleans up all cello related docker images. It runs the following commands for you.
+
 ```sh
 $ docker images | grep "cello-" | awk '{print $1}' | xargs docker rmi -f
 $ docker rmi $(docker images -f dangling=true -q)
@@ -51,12 +54,14 @@ Shows logs of all services.
 
 ### setup-master
 Sets up the master node. Run on Master node. It runs the following command for you.
+
 ```sh
 $ cd scripts/master_node && bash setup.sh
 ```
 
 ### setup-worker
 Sets up the worker node. Run on Worker node. It runs the following commands for you.
+
 ```sh
 $ cd scripts/worker_node && bash setup.sh
 ```
@@ -66,6 +71,7 @@ Redeploys specified service(s). To redeploy `Dashboard` service, use: `make rede
 
 ### start
 Starts all services. Runs following command for you.
+
 ```sh
 $ docker-compose up -d --no-recreate
 ```

diff --git a/docs/monitoring.md b/docs/monitoring.md
@@ -1,17 +1,24 @@
 #Monitoring services
-The monitoring services build in real time an archive of observations obtained from the analisys of the communication flows of the CELL application services.
+
+The monitoring services build in real time an archive of observations obtained from the analisys of the communication flows of the Cello application services.
+
 The observations could be checked in real time (directly in memory) against attacks, anomalies or errors.
+
 The observations, once processed in real time, are stored into a persistent archive for statistic analisys and reports generation.
 
 ### Config the port to be monitored
 Admin can configure the tcp ports to be monitored by the monitoring services, by adding the following two lines:
-* # the monitoring services will have to monitor the following ports
-* PORTS_TO_BE_MONITORED = list(PEER_SERVICE_PORTS.items()) + list(CA_SERVICE_PORTS.items())
+
+```bash
+# the monitoring services will have to monitor the following ports
+PORTS_TO_BE_MONITORED = list(PEER_SERVICE_PORTS.items()) + list(CA_SERVICE_PORTS.items())
 to the configuration file: /src/common/utils.py
+```
 
 ### Config the monitoring level
 Admin can add to the file /src/monitoring/config.py the following flags:
-* MONITOR_DB=<file name or network path where to store the persistent archive>
+
+* MONITOR_DB=[file name or network path where to store the persistent archive]
 * MONITOR_LEVEL=FULL | SIMPLE | NONE
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
diff --git a/docs/production_config.md b/docs/production_config.md
@@ -1,5 +1,6 @@
 # Production Configurations
-Reference system configuration in production environment.
+
+In order to optimize the system performance in production environment, these system configurations can be set.
 
 ## `/etc/sysctl.conf`
 
@@ -31,9 +32,8 @@ Then, need to run `sysctl -p` for enabling.
 * soft stack 32768
 * hard stack 32768
 ```
-Log
 
-## Other Consideration
+## Other Configurations
 
 * Use the code from `release` branch.
 * Configuration: Set all parameters to production, including image, compose, and application.

diff --git a/docs/scenario.md b/docs/scenario.md
@@ -1,6 +1,6 @@
 # Scenarios
 
-## Admin
+## Admin Scenario
 After start up, Cello provides a dashboar for administrators, which listens on localhost:8080.
 
 The default login user name and password are `admin:pass`, you can modify this by changing the variables `USERNAME` and `PASSWORD` in the `nginx` section of the [docker-compose file](../docker-compose.yml).
@@ -16,19 +16,19 @@ Admin can also delete a host from the resource pool if it has no running chains.
 ### Config a host
 Admin can manually update the host configuration, including:
 
-* name: Human readable name alias.
-* capacity: Maximum chain number on that host.
-* schedulable: Whether to distribute chains on that host to users.
-* autofill: Whether to keep host with running chains to its capacity.
-* log_type: local or syslog.
+* `name`: Human readable name alias.
+* `capacity`: Maximum chain number on that host.
+* `schedulable`: Whether to distribute chains on that host to users.
+* `autofill`: Whether to keep host with running chains to its capacity.
+* `log_type`: local or syslog.
 
 ### Operate a host
 
 Admin can run several operations on a host, including:
 
-* fill: Fill the host with chains to its capacity.
-* clean: Clean up the free chains on that host.
-* reset: Re-setup a host, e.g., cleaning useless docker containers.
+* `fill`: Fill the host with chains to its capacity.
+* `clean`: Clean up the free chains on that host.
+* `reset`: Re-setup a host, e.g., cleaning useless docker containers.
 
 ### Add/Delete chains
 Admin can also manually add some specific chain to a host, or delete one.
@@ -39,7 +39,7 @@ When the autofill box is checked on a host, then watchdog will automatically kee
 
 e.g., if the capacity of one host is set to 10, then the host will be filled with 10 chains quickly. When 2 chains are broken, they will be replaced by healthy ones soon.
 
-## Chain users
+## Users Scenario
 
 ### apply a cluster
 

diff --git a/docs/service_management.md b/docs/service_management.md
@@ -0,0 +1,29 @@
+# Service Management
+
+Main Cello services are running in the Master Node.
+
+## Services
+
+After starting cello services using `make start`, there will generate several service containers as the following:
+
+```bash
+$ docker ps
+CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                                                 NAMES
+fdf4b8465d14        yeasy/nginx         "/bin/bash /tmp/do..."   12 seconds ago      Up 11 seconds       0.0.0.0:80->80/tcp, 0.0.0.0:8080->8080/tcp, 443/tcp   nginx
+80c3962867ff        mongo:3.2           "docker-entrypoint..."   12 seconds ago      Up 11 seconds       127.0.0.1:27017-27018->27017-27018/tcp                mongo
+91df95a11229        cello-dashboard     "python dashboard.py"    12 seconds ago      Up 11 seconds       8080/tcp                                              dashboard
+051efd511066        cello-watchdog      "python watchdog.py"     12 seconds ago      Up 11 seconds                                                             watchdog
+a66bb112a21f        cello-restserver    "python restserver.py"   12 seconds ago      Up 12 seconds       80/tcp                                                restserver
+```
+
+* `nginx`: [Nginx](https://nginx.org) is used as a reverse proxy to improve web performance.
+* `mongo`: [MongoDB](https://www.mongodb.com) is used as the backend database.
+* `dashboard`: Provides the admin dashboard using [Flask](http://flask.pocoo.org/).
+* `watchdog`: Monitors the status of the system (e.g., chains' health).
+* `restserver`: Core engine to do the provision, orchestration and management tasks.
+
+## Make Command
+
+A [Makefile](https://en.wikipedia.org/wiki/Makefile) is provided to help setup and manage the master node, please refer to the [make_support](make_support.md) page.
+
+<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.