microservice-bootstrap v1.0.8

Micro Service Bootstrap for NodeJS

Microservice Bootstrap as a commandline tool (alternatively, you can also clone from https://github.com/coreorm/node-micro-service-bootstrap and add your own service manually).

It takes all the boring chores away, while leaving the fun part to you: the very service / API you wanted.

Heroku App Example: https://glacial-mountain-78419.herokuapp.com/.

Example APIs:

• ping
• example: foo
• example: bar

Quick start

Install from NPM

First, install the command

npm install -g microservice-bootstrap

Then create your web service by running

microservice-bootstrap create -t path-to-myservice

Then wait patiently, it will install the service and all dependencies (Yes, you don't need to run npm install').

Create your own service.

Simply run

microservice-bootstrap add-service my-service

If you want to add more than one, just separate the names with comma (,).

microservice-bootstrap add-service service-name1,service-name2...

By default, it will expose GET /my-service api.

For more details, run microservice-bootstrap add-service -h.

Start the server

microservice-bootstrap run [options]

e.g.

microservice-bootstrap run -e local -s my-service -v

Or run microservice-bootstrap run -h to see the man page for more details on the allowed options.

How-to

Service How-to

The server is already setup with global APP variable, simply do your routes (APP is an instance of express) e.g.

APP.get('/', function(req, res) {
    res.send('hello world!');
});

If you have added services using the CLI tool, a default GET /service name is already added for you.

For more details, check express website.

JSON API response maker.

This bootstrap includes a very easy to use JSON response maker, the output format is:

{
  "data": <Object or string>,
  "message": <String message>,
  "success": <Boolean true|false>,
  "code": <INT 200-500>,
  "size": <INT size of data in bytes>,
  "time": <TIMESTAMP milliseconds>
}

To use it, simple use the two apis:

• for successful JSON output: _LIB.util.response.success(data, message, code)
• for erroneous JSON output: _LIB.util.response.error(error, code).

Details see ./services/default/index.js.

Environment How-to

Configuration

Configurations are environment specific, the are located inside ./config folder, the structure is as follows:

config
├── local
│   ├── app.js
│   └── lib.js
├── production
│   ├── app.js
│   └── lib.js
└── uat
    ├── app.js
    └── lib.js

These 3 environments are pre-installed, if you need to add more environment, just follow the same structure. [environment name as folder name]/[config file]

• app.js is the application config;
• lib.js is the library registry;

Config inheritance: production -> uat -> local;

Library

Library files should be placed inside ./lib, following the structure:

lib
├── README.md
├── package-name         // package
│   ├── file1.js
│   └── file2.js
├── package-name.js      // package header - use it to include package files

Unit Tests

Simple run npm run test. All tests are under ./tests folder. Follow exampleTest.js to write your own tests.

Appendix

Globals

Logging

Use _log(section, data, level = INFO|ERROR|SUCCESS|...) to log (this will format it into logstash friendly message structure)

• section is where your code runs (e.g. 'service:foo', or a filename)
• data can be a simple string, or a complex javascript object.
• level: text value for level of the log

Log format is a custom pattern for logstash, feel free to change it by overriding the custom global._log function, or directly update lib/util/log.js.

Default GROK syntax:

\[(?<datetime>.+)\] (?<level>[\w]+) "(?<section>[^"]+)" DATA<(?<data>.+)>$

Verbose output

Simply use _v(section, data) to log out the verbose output. This will remain hidden unless the app is run with -v or --verbose.

Built-in Debug tool

NOTE: only supported when _CONF.debug = true;

• _dump(name, object) to record objects in the debug information (returned from api)
• _debug(message) to record debug messages (returned from api)
• Pass x-debug-enabled=1 in the header or add ?x-debug-enabled=1 in the query string to enable debug output (NOT supported in production mode).