CC Configuration

[TOC]

Intro

This library is designed to standardize the way Concorde deals with configurations in Node releases. This library does not implement or enforce a particular configuration for any system. What it does is standardize where the config is found and how it is populated. It is intended to capture some practices from others, but it does not require you only use those practices. Instead it says if you do it this way, it will make your results predictable.

There are three ways to get configuration: command line, configuration file, and environment. 12 Factor apps specifies only using the environemnt as a configuration store. This is a handy idea, but doesn't scale to complex configurations (12 Factor says that that means the library is too complex - I doubt they are right). But, but, but for the things that differ from dev to production and the environments in between, the environment is ideal for configuration as a docker-compose file can pull those values in easily. So the only difference from one environment to another is which docker-compose file you use.

Configuration files should be used for defaults that rarely change. We use YAML files over JSON because they are easier to edit, support comments and are just less idiosyncratic. Command line (CLI) options should handle things that may change from run to run. They are also handy for quickly and easily changing logging metric options on the fly while debugging.

This library supports all three types, but won't enforce semantic meaning to where you get your configuration from. This is based on the confab configuration tool and yargs command line interpreter and inspired by this blog article.

The order in which things are loaded are config files -> enviroment variables -> CLI. Subsequent values with the same name are overwritten left to right.

#Installation

npm install @concorde2k/ccconfig

#Usage Well, first you have to load it up. Then use it. Duh.

Let's assume you want to load environment variables that determine what database server to use, call them CC_SERVER and CC_PORT. We also have a rarely changed set of values that we want to store in a config file called ./config.yml (note that ./ is the main module's path) and it looks like this:

   alertColor: yellow
   clientName: Bob's House of Pandas

This is how it would work:

const {config, environment, configFiles, defaults} = require("@concorde2k/ccconfig");

// This says we map the environment variable CC_SERVER to a configurgation
// value called `dbServer`
environment.CC_SERVER = "dbServer";
environment.CC_PORT = "dbPort";

// We can give them default values, too
defaults.dbServer = "CC-DEV-DB";
defaults.dbPort = 3363;

// We'll specify the config files here to show how it works, but this value
// is one of the defaults
configFiles.push("./config/index.yml");

// referencing `config` the first time collapses all of options and resolves
// them. Subsequent references across alll modules use the cached version
console.log(config.dbPort); // 3363
console.log(config.alertColor); // "yellow"

What if I want to add a configuration option after I have loaded the config?

const {config, load} = require("@concorde2k/ccconfig");
//.
// do something interesting
//.
console.log(config.alertColor); // "yellow"

load({someNewOption: "red", alertColor: "purple:"});
console.log(config.alertColor); // "purple"
console.log(config.someNewOption); // "red"

Command line options are handled pretty much the same way, except that all of yargs syntax is supported.

const {config, cli} = require("@concorde2k/ccconfig");

cli.option(
		"t",
		{
			alias       : "target",
			demandOption: true,
			default     : "AssetTracker",
			describe    : "The database on the target server that will be transferred",
			type        : "string"
		}).option(
		"s",
		{
			alias       : "source",
			demandOption: true,
			default     : "AssetTracker",
			describe    : "The database on the source server that will be transferred",
			type        : "string"
		})

	);

console.log(config.t) // AssetTracker

And calling the program from the command line:

node myapp -t Terry  # Terry
node myapp --target Terry  # Terry

#Building ccconfig is built in Typescript and uses good ol' make to build. You will need these tools:

npm install --global typescript # with admin rights # with admin rights
npm install --global typedoc typedoc-plugin-markdown
npm install --global typedoc-plugin-external-module-name

You will, of course, also need make. Please use the Cygwin or Swan versions and make sure that the tools are in your PATH.

# build the library
make build

# to clean up the current build
make clean

# to blow away the entire build and start over
make dist-clean

# to build the documentation
make techdocs

# to clean up and build everything again
make build-all

# to create a new patch version - make sure you
# are fully checkin first
make patch-up

# to create a new minor version - make sure you
# are fully checkin first
make minor-up

# to build and publish to npm.org
make publish