Fuge-Config

Configuration file parser for fuge.

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

• Post a [github issue][https://github.com/apparatus/fuge/issues],
• Reach out on twitter to @pelger

Install

fuge-config provides configuration file parsing for fuge. To install fuge use npm:

$ npm install -g fuge

Format

The fuge config file format is yaml based and is structured as follows:

fuge_global:
  .
  .
  <global settings>
  .
  .
<service1 settings>:
  .
  .
<service2 settings>:
  .
  .
include:
  - <docker-compose-file>

Settings are provided at a global and per service level. Generally, any global settings may be overridden at the container / service level. Global settings are applied to all containers.

You may optionally include a list of docker-compose formatted files through the use of the include setting. Fuge supports V1, V2 and V3 docker-compose syntax.

Examples

A simple example is provided below:

fuge_global:
  run_containers: true
  monitor_excludes:
    - '**/node_modules/**'
    - '**/.git/**'
    - '*.log'
  environment:
    - NODE_ENV=DEV
frontend:
  type: process
  path: ./frontend
  run: 'npm start'
  ports:
    - http=3000
mongo:
  type: container
  image: mongodb
  ports:
    - tcp=27017:27017

In the simple example fuge will run a frontend process (called frontend) and a mongodb container. This might be the configuration for a monolithic MEAN stack application. The application can be started through the Fuge shell:

$ fuge shell <path to config file>
fuge> start all

A more complicated example follows:

fuge_global:
  run_containers: true
  host: 127.0.0.1
  monitor_excludes:
    - '**/node_modules/**'
    - '**/.git/**'
    - '*.log'
  dns_enabled: true
  dns_namespace: testns
  dns_suffix: svc.cluster.local
  dns_external:
    - "mydatabse.mydomain.internal.com IN A 192.0.2.1"
    - "_main._tcp.mydatabse.mydomain.internal.com IN SRV 0 5 5060 mydatabase.mydomain.internal.com"
  auto_generate_environment: true
  auto_port_start: 20000
  environment:
    - NODE_ENV=DEV
frontend:
  delay_start: 5
  type: process
  path: ./frontend
  run: 'npm start'
  ports:
    - http=3000
service_one:
  type: process
  path: ./service_one
  run: 'npm start'
service_two:
  type: process
  path: ./service_two
  run: 'npm start'
mongo:
  type: container
  image: mongodb
  ports:
    - tcp=27017:27017

In the above example fuge will generate environment variables and dns entries for frontend, service_one, service_two and mongodb. Again the entire system can be started using the fuge shell.

Emulating production environments

Fuge will emulate your production environment allowing you to run code with the same configuration in development as would run in production. In the example above fuge has been configured to emulate Kubernetes for local development. Fuge will generate Kubernetes style dns entries and and environment variables. The DNS entries generated are as follows:

type  domain                                            address                                port
A     frontend.testns.svc.cluster.local                 127.0.0.1                              -
A     service_one.testns.svc.cluster.local              127.0.0.1                              -
A     service_two.testns.svc.cluster.local              127.0.0.1                              -
A     mongo.testns.svc.cluster.local                    127.0.0.1                              -
SRV   _http._tcp.frontend.testns.svc.cluster.local      frontend.testns.svc.cluster.local      3000
SRV   _main._tcp.service_one.testns.svc.cluster.local   service_one.testns.svc.cluster.local   20000
SRV   _main._tcp.service_two.testns.svc.cluster.local   service_one.testns.svc.cluster.local   20001
SRV   _tcp._tcp.mongo.testns.svc.cluster.local          mongo.testns.svc.cluster.local         27017

Fuge will also generate Kubernetes style environment variables as follows from the above example:

FRONTEND_SERVICE_HOST=127.0.0.1
FRONTEND_SERVICE_PORT=3000
FRONTEND_PORT=tcp://127.0.0.1:3000
FRONTEND_PORT_3000_TCP=tcp://127.0.0.1:3000
FRONTEND_PORT_3000_TCP_PROTO=tcp
FRONTEND_PORT_3000_TCP_PORT=3000
FRONTEND_PORT_3000_TCP_ADDR=127.0.0.1
DNS_HOST=0.0.0.0
DNS_PORT=53053
DNS_NAMESPACE=testns
DNS_SUFFIX=svc.cluster.local
SERVICE_ONE_SERVICE_HOST=127.0.0.1
SERVICE_ONE_SERVICE_PORT=20000
SERVICE_ONE_PORT=tcp://127.0.0.1:20000
SERVICE_ONE_PORT_20000_TCP=tcp://127.0.0.1:20000
SERVICE_ONE_PORT_20000_TCP_PROTO=tcp
SERVICE_ONE_PORT_20000_TCP_PORT=20000
SERVICE_ONE_PORT_20000_TCP_ADDR=127.0.0.t
SERVICE_TWO_SERVICE_HOST=127.0.0.1
SERVICE_TWO_SERVICE_PORT=20001
SERVICE_TWO_PORT=tcp://127.0.0.1:20001
SERVICE_TWO_PORT_20001_TCP=tcp://127.0.0.1:20000
SERVICE_TWO_PORT_20001_TCP_PROTO=tcp
SERVICE_TWO_PORT_20001_TCP_PORT=20001
SERVICE_TWO_PORT_20001_TCP_ADDR=127.0.0.1
MONGO_SERVICE_HOST=127.0.0.1
MONGO_SERVICE_PORT=27017
MONGO_PORT=tcp://127.0.0.1:27017
MONGO_PORT_27017_TCP=tcp://127.0.0.1:27017
MONGO_PORT_27017_TCP_PROTO=tcp
MONGO_PORT_27017_TCP_PORT=27017
MONGO_PORT_27017_TCP_ADDR=127.0.0.1
NODE_ENV=DEV

Environment Handling

Fuge supports loading of environment files both at the global and service scope. It also supports environment variable interpolation in the fuge config file and and included docker compose files.

Detail

Global Settings

Valid global settings are as follows:

Global Settings

name	type	effect	default
run_containers	boolean	when enabled fuge will run docker containers using the local docker api. A container is specified as having type 'container'	true
container_engine_url	url	The url to used to connect to the Docker container engine (e.g. /var/run/docker.sock). If not set this will be picked up from the environment.	''
host	string	Host name or IP address to use for this host when starting Docker containers	127.0.0.1
tail	boolean	toggles tail behavior, when enabled at global level all container and process logs will be tailed	true
monitor	boolean	toggles monitor behavior, when enabled at global level all processes will be watched for changes and restarted	true
monitor_excludes	array of regex	Array of [anymatch](https://github.com/es128/anymatch) compatible path expressions that should be excluded from monitoring typically this should be set to ['**/node_modules/**', '**/.git/**', '*.log' or similar	[]
dns_enabled	boolean	when enabled will start the internal fuge DNS sever and generate A and SRV records for each service.	false
dns_host	string	host ip address for dns server to bind to.	0.0.0.0
dns_port	integer	port for dns server	53053
dns_namespace	string	Used as a global namespace during dns name generation	''
dns_suffix	string	Used as a global suffix during dns name generation	''
dns_external	array of string	inject addtional dns records into the fuge dns server. Can be used to connect to external databases during development	''
auto_generate_environment	boolean	When enabled fuge will generate an environment variable block for each service	true
auto_port_start	integer	Provide a base port number to use during environment generation	10000
environment	array of string	Provide global environment variables to each service	[]
env_file	array of string	Specifiy a list of environment files to load into the global environment	[]
host	string	provide a global host name or ip address	localhost
delay_start	integer	delay this many seconds when starting processes	0
restart_on_error	boolean	attempt to restart crashed service processes	false
max_restarts	integer	maximum number of times to attempt service restart after crash	5
include	Array of string	List of docker compose files to include in this fuge system	[]

Service Settings

Most of the global settings documented above may be specified at the service level. When specified at the service level, settings override the global options. In addition at the service level the following settings are required/allowed:

name	type	effect	default
type	string	one of 'process' or 'container', tells fuge how to execute this service	none - required
path	string	If type 'process' path is required. Relative path to the process executable	none - required if process
image	string	If type 'container' image is requried. Name of the docker container to execute	none - required if container
build	string	build script for the process, relative to the path setting	''
test	string	test script for the process, relative to the path setting	''
run	string	run script for the process, relative to the path setting	none - required for processes
environment	array of string	Provide environment variables specific to this process or container. Will be merged with the global environment	[]
ports	array of string	Provide port name value pairs specific to this process / container	[]

What's not supported

Fuge does not support container volumes from docker files or container linking. If you need these features then docker-compose is going to work better for you. Note however it is possible to run a portion of your system under compose (the bits that don't change much) and a portion under fuge (the bits that are under development) by setting run_containers to false and importing your docker-compose file. For an example of this see services-and-infrastructure sample in this repo: https://github.com/apparatus/fuge-examples

License

Copyright Peter Elger 2016 & Contributors, Licensed under [MIT][].