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
fuge-config provides configuration file parsing for fuge. To install fuge use npm:
$ npm install -g fugeThe 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.
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 allA 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.
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 27017Fuge 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=DEVFuge 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.
Valid global settings are as follows:
| 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 | [] |
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 | [] |
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
Copyright Peter Elger 2016 & Contributors, Licensed under [MIT][].