| 1 | Project configuration, dataflows-style
|
| 2 | ==========
|
| 3 |
|
| 4 | Goals
|
| 5 | ----------
|
| 6 |
|
| 7 | 1. Easy to use
|
| 8 | Common format, you can set up a location of configuration files. If you already have one, you do not need to change files location for each project, you can just point this location (set up environment) for all needed projects.
|
| 9 |
|
| 10 | 2. Scalable
|
| 11 | Hierarchical, any section can live in a separate file, easy access to frequently changing sections.
|
| 12 |
|
| 13 | 3. Easy deployment
|
| 14 | Configuration actually is splitted to the project configuration and instance fixup. You can have as many fixups as you want, not only development and production.
|
| 15 |
|
| 16 | 4. Persistent
|
| 17 | Current configuration snapshot is always on disk and in vcs. No code allowed within configuration. Tools never change project config, only fixup allowed to change.
|
| 18 |
|
| 19 | Those is not acceptable:
|
| 20 |
|
| 21 | 1. `require ('config.json')` — 1, 2, 3;
|
| 22 | 2. nconf - 4 (require code to load includes)
|
| 23 | 3. node-convict - 2 (no access to frequently chnging sections), 3 (no separation beween project config and instance fixup)
|
| 24 | 4. dotenv - 2, 4 (recommended not to commit config)
|
| 25 | 5. node-config - 1 (cannot change location), 4 (instance name not stored on disk)
|
| 26 |
|
| 27 | Implementation
|
| 28 | ---------------
|
| 29 |
|
| 30 | dataflows configuration is located within `.dataflows` directory in project root. Main configuration file named `project`, fixup directories located at same level as the `project` file.
|
| 31 |
|
| 32 | 1. `project` file is loaded and parsed. For now, only `json` format supported;
|
| 33 | 2. `project` contents is scanned against includes in form `"<include-file-name>"`;
|
| 34 | 3. when all includes is loaded, config tree is scanned for variables (`"<$config.path.variable>"`) and placeholders (`"<#please fix me>"`, `"<#optional:please fix me>"`, `"<#default:127.0.0.1>"`);
|
| 35 | 4. `fixup` file loaded and checked, whether all variables and placeholders fulfilled;
|
| 36 | 5. if resulting config is fulfilled, project emits `ready` event; otherwise, `error` event emitted.
|
| 37 |
|
| 38 | Caveats
|
| 39 | -----------
|
| 40 |
|
| 41 | 1. config format is guessed at launch
|
| 42 | most popular config formats (json and xml) can be parsed automatically (json can be detected by first chars - `{[`, xml must contains `<?xml version encoding?>`), another formats can have comment with format description on first line ("; ini")
|
| 43 |
|
| 44 | 2. Configuration must be separated from dataflows project and have no external dependencies.
|
| 45 |
|
| 46 | Environment variables to drive config (don't like it at all)
|
| 47 | ------------
|
| 48 | PROJECT_ROOT absolute path
|
| 49 | PROJECT_CONF (relative to project root, dir name to search for "project" file)
|
| 50 | PROJECT_VAR (relative to project root, dir name to search for "instance" file)
|
| 51 | PROJECT_INSTANCE string
|
| 52 | techdebt: if PROJECT_ROOT is file path, then assume to load `project` config from that file and treat parent directory as project root.
|
| 53 | techdebt: if PROJECT_INSTANCE is file path, then assume to load `fixup` contents from that file.
|
| 54 |
|
| 55 |
|
| 56 | Links
|
| 57 | ---------------
|
| 58 | http://thejeffchao.com/blog/2013/09/26/an-alternative-node-dot-js-configuration-management-pattern/
|
| 59 | http://metaduck.com/03-konphyg.html
|
| 60 | https://github.com/mozilla/node-convict
|
| 61 | https://github.com/scottmotte/dotenv
|