readme0

Author: rjrodger

README.md

@@ -1,21 +1,86 @@
-# The nodezoo microservice demonstration architecture
+# nodezoo-info
 
 This is a repository in the microservice demonstration system for
 the [Tao of Microservices](//bit.ly/rmtaomicro) book (chapter 9). This
-code is live at [nodezoo.com](//nodezoo.com).
+code is live at [nodezoo.com](http://nodezoo.com). To get started,
+visit the [nodezoo/tao](//github.com/nodezoo/tao) repository.
 
-This system shows you how to construct a full microservice
-architecture. It is MIT licensed so that you can cut-and-paste to
-build your own system with minimal effort. The system consists of
-multiple repositories, and runs ten or so microservices in production
-([Kubernetes](//kubernetes.io)), staging ([Docker](//docker.com)), and
-development ([fuge](//github.com/apparatus/fuge)) modes.
+__This microservice provides the module information page functionality.__
 
-The best place to get started is
-the [nodezoo/tao](//github.com/nodezoo/tao) repository, which links to
-everything else, and has the _Getting Started_ guide.
 
-## nodezoo-info
+## Running
 
-_TODO_
+To run this microservice normally, use the tooling describing in
+the [nodezoo/tao](/nodezoo/tao) repository, which shows you how to run
+the entire system of microservices (of which this is only one of many) in
+production ([Kubernetes](//kubernetes.io)), staging
+([Docker](//docker.com)), and development
+([fuge](//github.com/apparatus/fuge)) modes.
 
+To run from the terminal for testing and debugging, see
+the [Running from the terminal](#running-from-the-terminal) section
+below.
+
+
+## Message flows
+
+The table shows how this microservice acts on the `Accepted` message
+patterns and performs appropriate business `Actions`, as a result of
+which, new messages are possibly `Sent`.
+
+|Accepted |Actions |Sent
+|--|--|--
+|`role:info,cmd:get (SC)` |Provide module information by asking other microservices for data. |`role:info,need:part (AO)`
+|`role:info,collect:part (AO)` |Collect partial module information|
+
+(KEY: A: asynchronous, S: synchronous, O: observed, C: consumed)
+
+
+## Running from the terminal
+
+This microservice is written in [node.js](//nodejs.org), which you
+will need to download and install. Fork and checkout this repository,
+and then run `npm` inside the repository folder to install its dependencies:
+
+```sh
+$ npm install
+```
+
+To run this microservice separately, for development, debug, or
+testing purposes, use the service scripts in the [`srv`](srv) folder:
+
+* [`info-dev.js`](srv/info-dev.js) : run the development configuration 
+  with hard-coded network ports.
+
+  ```sh
+  $ node srv/info-dev.js
+  ```
+
+  This script listens for messages on port 9030 and provides a REPL on
+  port 10030 (try `$ telnet localhost 10030`).
+
+  A [seneca-mesh](//github.com/senecajs/seneca-mesh) version, for
+  testing purposes, is also shown in the
+  script [`info-dev-mesh.js`](srv/info-dev-mesh.js). For more on
+  this, see the [nodezoo-repl](//github.com/nodezoo/nodezoo-repl)
+  repository.
+
+* [`info-stage.js`](srv/info-stage.js) : run the staging
+  configuration. This configuration is intended to run in a Docker
+  container so listens on port 9000 by default, but you can change
+  that by providing an optional argument to the script.
+
+  ```sh
+  $ node srv/info-stage.js [PORT]
+  ```
+
+* [`info-prod.js`](srv/info-prod.js) : run the production
+  configuration. This configuration is intended to run under
+  Kubernetes in a [seneca-mesh](//github.com/senecajs/seneca-mesh)
+  network. If running in a terminal (only do this for testing), you'll
+  need to provide the mesh base nodes in the `BASES` environment
+  variable.
+
+  ```sh
+  $ BASES=x.x.x.x:port node srv/info-prod.js
+  ```