Module: keef

The conf package reads configurations options in an overriding fashion from a number of sources. In order of importance:

1. System level overrides
2. Command line arguments
3. Environment variables
4. A configuration file(s)
5. System specified defaults

Overrides

Overrides can not be overriden or changed at any point in time. The are defined in conf/lib/overrides.js and should be reserved for static run time properties. Conf serves as a central place to get that information.

For example, the full path to the packages directory is resolved at run time and loaded in to the conf loader. It won't / can't change during run time, but may change in the future. By getting the information from conf, application logic does not need to change between restarts or releases.

If overrides need to be change or added the overrides.js file must be changed

Command Line Arguments

Command line arguments are the highest level of maliable values. The can be used to set specific and nested values in the configuration JSON document but using a : spearator between keys. For example, using the flag: --foo:bar=1, would create an object like

{
   "foo":{
      "bar": 1
   }
}

Environment Variables

Environment variables work much the same as command line arguments. However, most bash implenetations don't read :'s very well, so the double underscore ( __ ) is used in its place foo__bar=1 npm start

{
   "foo":{
      "bar": 1
   }
}

Conf Options

The conf option can be set to read specific configuration from a file(s). The value should be a full path. If the path points to a directory, the conf loader will read all json files, sort them and load their values in an overriding order. Sorting is done in a descending, lexigraphical order.

└── conf
    ├── 20-keef.json
    ├── 10-keef.json
    └── 30-keef.json

Given the above directory of conf files, the server can be configured by pointing the conf arguments at the directory

node server --conf=$HOME/conf

The configruation would be read in the following priority 10-keef.json < 20-keef.json < 30-keef.json

where 20 overrides 10, and 30 overrides 20.

Static File Defaults

To Simplify configuration for deployments, keef will look for configuration files in fixed locations eliminating the need for run time configuration. File Locations are as follows:

1. a file in the rooot of your project with the name <package.name>.NODE_ENV.json For example, if the name attribute in your package.json is foobar, and the environment var NODE_ENV is set as production, the file look up is foobar.production.json. If NODE_ENV is not set, it would be foobar.development.json
2. A json file named after your project name in the root of your project - foobar.json
3. A json file named after your project in a .config directory in the current users home directory - .config/foobar.json
4. A json file named after your project in the /etc directory - `/etc/foobar.json

ETCD2 Clusters

For distributed deployments, An etcd2 cluster may be used for configuration purposes. To enable etcd2 configuration loading, 2 environment variables should be set:

1. etcd__hosts - A comma separated list of host:port addresses - etcd1.domain.com:4001,etcd2.domain.com:4001.
2. etcd__namespace - a keyspace to keep data separate from everything else.

Any configuration that is stored as object, we be translated into etcd directories automatically

keef.set('a:b:c', 1)

// Object data
{
  "a": {
    "b": {
      "c": 1
    }
  }
}

// etc data
/a/b/c 1

System defaults

defaults are what they sound like. Sane defaults for values that are needed to get the application running. They are located in the Defaults module and are used only as fallback values.

Option Shorthands

Top level options can be aliased. Short hand aliases can be found and defined in the Shorthands module of keef

the following invocations are treated the same

node server --PORT=3001 --logger=stdout --logger=file

PORT=3001 logger=stdout nodeserver -l file

node server -p 3001 -l stdout -l file