fuge - 'rails for microservices'

Fuge provides a generation and execution environment for microservice development on node.js.

Full documentation is available here.

If you're using this module, and need help, you can:

Post a github issue,
Ask on the Gitter.

Overview

Fuge aims to help developers working on microservice systems in several ways:

By providing a microservice scaffold generator
By providing a service execution environment
By reducing the friction between processes and containers during development

Install

To install, use npm to install globally.

npm install -g fuge

Scaffold Generator

The scaffold generator creates a fully functional microservice system that is ready to run. Once generated you can add additional services manually or by using the service generator.

By default, fuge generates services in node.js using the Seneca microservices framework and the hapi web framework for the API layer.

To generate a fuge microservice system scaffold run:

mkdir mysystem
cd mysystem
fuge generate system

Fuge will ask you for some simple questions and then generate a system for you. The generated system looks as follows:

├── fuge
│   ├── compose-dev.yml
│   ├── docker-compose.yml
│   └── fuge-config.json
├── service1
│	└── Dockerfile
├── service2
│	└── Dockerfile
└── site
	├── Dockerfile
    ├── api
    └── public

The structure has the following key files:

fuge - This directory contains two files
- compose-dev.yml - a docker-compose yaml file that serves as the main configuration reference for the system
- docker-compose.yml - a docker-compose yaml file that has a pre-configured fuge environment
- fuge-config.json - contains fuge specific settings and overrides not supported by docker-compose
service1 - contains a basic http point to point microservice using the Seneca framework
service2 - contains a basic http point to point microservice using the Seneca framework
site - contains a frontend site for the system. This is comprised of an api and a public site using the hapi framework

To start the generated system execute:

fuge run ./fuge/compose-dev.yml

This will spin up the site and the two related microservices. Point your browser to http://localhost:10000/ to open the front end and exercise the microservices.

Fuge watches your code for changes and will automatically restart the front end and services as you make changes, providing a rapid development environment for integration testing and debugging.

To generate a new service you can run:

fuge generate service

Fuge will create a new service for you and will optionally add it into your compose-dev.yml.

Execution Environment

Fuge provides a simple shell to manage microservice execution. To start the shell run:

fuge shell ./fuge/compose-dev.yml

The fuge shell supports the following commands:

help - display a list of supported commands
ps - list status of managed processes and containers
proxy - list proxy and port forwarding status
info [process name] - show information on a specific process
stop [process] - stop a process and any associated watcher
stop all - stop all processes and watchers
start [process] - start a process
start all - start all stopped processes
debug [process] - start a process in debug mode and launch node-debug (experimental)
watch [process] | all - turn on watching for a process or for all processes
unwatch [process] | all - turn off watching for a process or for all processes
tail [process] | all - tail output for a process or for all processes
untail [process] | all - end tail output for a specific processes or for all processes
grep 'search string' [process] - searches a process' log or all processes' logs
exit - terminate all managed processes and exit

Mixed Containers and Processes

If you are familiar with Docker, you will notice that fuge generates a Dockerfile for each system component and ties the system together with a docker-compose yaml file. In fact, the system generated by fuge can be run entirely using docker-compose. If you have Docker installed you can try this out by running:

cd ./fuge
docker-compose up

Docker will build a set of containers and start them up for you using the generated installed docker-compose.yml file.

Adding Infrastructure

Let's say that we want one of our services to connect a redis server. We could go ahead and install redis to our development system. Another approach however is to use Docker. If you have Docker installed then try the following:

Edit compose-dev.yml and add the following:

redis:
  image: redis
  ports:
    - 6379:6379

Ensure that the redis container is on your system by running:

docker pull redis

Start the system up in the fuge shell again by running:

fuge shell ./fuge/compose-dev.yml

Starting fuge will now start the redis container as well as your micro-services.

Proxy

In addition to running Docker containers, Fuge will proxy connections to the Docker virtual machine on a mac and windows environment. Running the proxy command will show you how fuge is proxying connections to the Docker containers running as part of your system

Contributing

The apparatus team encourage open participation. If you feel you can help in any way, be it with documentation, examples, extra testing, or new features please get in touch.

dberesford/fuge