/
index.html
298 lines (270 loc) · 12.7 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html xmlns:yui="http://yuilibrary.com/rdf/1.0/yui.rdf#">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<title> </title>
<link rel="stylesheet" type="text/css" href="assets/reset-fonts-grids-min.css?stamp=1338535502.79" />
<link rel="stylesheet" type="text/css" href="assets/api.css?stamp=1338535502.79" />
<script type="text/javascript" src="assets/api-js?stamp=1338535502.79"></script>
<script type="text/javascript" src="assets/ac-js?stamp=1338535502.79"></script>
</head>
<body id="node-monitor">
<div id="doc3" class="yui-t2">
<div id="hd">
<h1><a href="https://github.com/lorenwest/node-config" title="Node.js Configuration">Node.js Configuration</a></h1>
<a href="./index.html" title="Node.js Configuration">Node.js Configuration</a>
<form onsubmit="return false">
<div id="propertysearch">
Search: <input autocomplete="off" id="searchinput" />
<div id="searchresults">
</div>
</div>
</form>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<form action="#" name="yui-classopts-form" method="get" id="yui-classopts-form">
<fieldset>
<legend>Filters</legend>
<span class="classopts" style="display:none;"><input type="checkbox" name="show_private" id="show_private" /> <label for="show_private">Show Private</label></span>
<span id="showProtected" class="classopts" style="display:none'"><input type="checkbox" name="show_protected" id="show_protected" /> <label for="show_protected">Show Protected</label></span>
<span class="classopts" style="display:none;"><input type="checkbox" name="show_deprecated" id="show_deprecated" /> <label for="show_deprecated">Show Deprecated</label></span>
</fieldset>
</form>
<h2><b>Online Documentation</b> </h2>
<div id="overview" class="summary description">
<h2>Introduction</h2>
<p>
Node-config is a configuration system for Node.js application server
deployments. It lets you define a default set of application parameters,
and tune them for different runtime environments (development, qa,
staging, production, etc.).
</p>
<p>
Parameters defined by node-config can be monitored and tuned at runtime
without bouncing your production servers.
</p>
<h2>Project Guidelines</h2>
<ul>
<li>Simple - Get started fast</li>
<li>Predictable - Well tested and stable</li>
<li>Flexible - Reasonable defaults & hackable</li>
<li>Powerful - For multi-node enterprise deployment</li>
<li>Easy Integration - For module developers</li>
</ul>
<h2>Getting Started</h2>
<p>
See the quick-start guide hosted on <a href="https://github.com/lorenwest/node-config">github</a>
</p>
<h2>Configuration Files</h2>
<p>
Node-config reads configuration files stored in the directory specified by
the <i>NODE_CONFIG_DIR</i> environment variable, which defaults to the <i>config</i>
directory within your top-level application directory. Configuration files can be
in .js format, .json format, .coffee format, or .yaml format - whichever you prefer.
</p>
<p>
Configuration files in the config directory are loaded in the following order:
</p>
<pre>
default.EXT
<i>hostname</i>.EXT
<i>deployment</i>.EXT
<i>hostname</i>-<i>deployment</i>.EXT
runtime.json
</pre>
<p>
Where EXT can be .yaml, .coffee, .json, or .js depending on the format you prefer.
NOTE: If you use .yaml or .coffee file extensions, the 'yaml' or 'coffee-script'
modules must be available. These external dependencies are not included from
this package.
</p>
<p>
<i>hostname</i> is the $HOST environment variable if set, otherwise the
hostname found from require('os').hostname()
</p>
<p>
<i>deployment</i> is the deployment type, found in the $NODE_ENV environment
variable. Defaults to 'development'.
</p>
<p>
The runtime.json file contains configuration changes made at runtime either
manually, or by the application setting a configuration value. Node-config
monitors this file and loads any new configurations it detects.
</p>
<p>
In the running application, each configuration parameter is internally
monitored for changes, and persisted to runtime.json upon change.
This keeps configurations in sync in a mutli-node deployment.
</p>
<h2>File Comments</h2>
<p>
Javascript-style comments are stripped out of files before parsing,
regardless of the file format type.
</p>
<h2>File Formats</h2>
<p>
JSON files (.json) expose configuration parameters as a JSON object.
Example:
</p>
<pre>
/* Customer parameters
*
* This controls database access and legacy system synchronization
*/
{
"Customer": {
"dbName": "customers",
"dbHost": "localhost",
"dbPort": 5984
// Database synchronization frequency
"syncFrequency": 60
}
}
</pre>
<p>
</p>
<p>
JavaScript files (.js) expose configuration parameters as module.exports. Example:
</p>
<pre>
module.exports = {
Customer: {
dbName: "customers",
dbHost: "localhost",
dbPort: 5984,
creditLimit: 600 // Default initial credit limit
}
}
</pre>
<p>
YAML files (.yaml) expose configuration parameters in YAML format. Example:
</p>
<pre>
Customer:
dbName: customers
dbHost: localhost
dbPort: 5984
creditLimit: 600
</pre>
<p>
Coffee-script files (.coffee) expose configuration parameters in coffee-script format. Example:
</p>
<pre>
module.exports =
Customer:
dbName: "customers"
dbHost: "localhost"
dbPort: 5984
creditLimit: 600
</pre>
<h2>Monitoring Changes</h2>
<p>
One important attribute of node-config is the ability to tune configuration
parameters at runtime. Configuration parameters fall into one of the
following categories:
</p>
<ul>
<li>
<strong>OK to change</strong> - This parameter type can change without
adverse effect. Most parameters fall into this category, where the
parameter value is read every time it's used.
</li>
<li>
<strong>Monitored</strong> - Some parameters are read infrequently
(usually at the start of the application), and need to be monitored for
change. The CONFIG.watch() function is available to watch these
parameters, and run a function when the value changes. See the
<a href="Config.html#method_watch">watch</a> method definition for more
information.
</li>
<li>
<strong>Not OK to change</strong> - Some parameters must be fixed at
runtime and remain stable throughout the lifecycle of the application.
For these parameters, the
<a href="Config.html#method_makeImmutable">makeImmutable</a> method is
offered to guarantee the parameter cannot be changed.
</li>
</ul>
<h2>Production Deployments</h2>
<p>
Node-config is designed to run in a multi-node deployment, where a few
instances of your application are running on a production server (usually
one per core processor).
</p>
<p>
If configuration values change at runtime, these changes are persisted
into the runtime.json file within the config directory. Multi-node
application instances keep in synch by watching for and loading changes
in this file when detected.
</p>
<p>
This paradigm does not extend beyond a single machine.
</p>
<h2>For Module Developers</h2>
<p>
Module developers can use node-config to define module specific
configuration parameters, and offer the same runtime tuning and multiple
deployment capability as the local application.
</p>
<p>
Node.js modules don't live in the same directory as the application, so
a different mechanism is offered to specify your default configuration.
</p>
<p>
The <a href="Config.html#method_setModuleDefaults">setModuleDefaults</a>
method creates an object (named after the module) within the CONFIG object
containing all module configuration parameters, and their defaults.
</p>
<p>
Users of your module may override your defaults in their config/defaults
file, or any of their deployment-specific configuration files.
</p>
<p style="text-align:right; padding-bottom:0; font-size:93%;">
Online docs built by <a href="http://developer.yahoo.com/yui/yuidoc/">yui-doc</a> and hosted by <a href="http://lorenwest.github.com">github</a>.
</p>
</div>
</div>
</div>
<div class="yui-b">
<div class="nav">
<div id="moduleList" class="module">
<h4>Modules</h4>
<ul class="content">
<li class=""><a href="module_config.html" title="config">config</a></li>
<li class=""><a href="module_test.html" title="test">test</a></li>
</ul>
</div>
<div id="classList" class="module">
<h4>Classes</h4>
<ul class="content">
<li class=""><a href="Config.html" title="Config">Config</a></li>
<li class=""><a href="ConfigTest.html" title="ConfigTest">ConfigTest</a></li>
<li class=""><a href="ProtectedTest.html" title="ProtectedTest">ProtectedTest</a></li>
</ul>
</div>
<div id="fileList" class="module">
<h4>Files</h4>
<ul class="content">
<li class=""><a href="1-protected-test.js.html" title="1-protected-test.js">1-protected-test.js</a></li>
<li class=""><a href="2-config-test.js.html" title="2-config-test.js">2-config-test.js</a></li>
<li class=""><a href="config.js.html" title="config.js">config.js</a></li>
<li class=""><a href="default.js.html" title="default.js">default.js</a></li>
</ul>
</div>
</div>
</div>
</div>
<div id="ft">
<hr />
Released on <a href="https://github.com/lorenwest/node-config">github</a> under the <a href="https://github.com/lorenwest/node-config/blob/master/LICENSE">Apache License 2.0</a>
<span class="subtitle">version 0.4.13</span>
</div>
</div>
<script type="text/javascript">
ALL_YUI_PROPS = [{"url": "Config.html#method__attachProtoDeep", "access": "protected", "host": "Config", "type": "method", "name": "_attachProtoDeep"}, {"url": "Config.html#method__cloneDeep", "access": "protected", "host": "Config", "type": "method", "name": "_cloneDeep"}, {"url": "Config.html#method_constructor", "access": "", "host": "Config", "type": "method", "name": "constructor"}, {"url": "Config.html#method__diffDeep", "access": "protected", "host": "Config", "type": "method", "name": "_diffDeep"}, {"url": "Config.html#method__equalsDeep", "access": "protected", "host": "Config", "type": "method", "name": "_equalsDeep"}, {"url": "Config.html#method__extendDeep", "access": "protected", "host": "Config", "type": "method", "name": "_extendDeep"}, {"url": "Config.html#method__isObject", "access": "protected", "host": "Config", "type": "method", "name": "_isObject"}, {"url": "Config.html#method__loadFileConfigs", "access": "protected", "host": "Config", "type": "method", "name": "_loadFileConfigs"}, {"url": "Config.html#method_makeHidden", "access": "", "host": "Config", "type": "method", "name": "makeHidden"}, {"url": "Config.html#method_makeImmutable", "access": "", "host": "Config", "type": "method", "name": "makeImmutable"}, {"url": "Config.html#method__parseFile", "access": "protected", "host": "Config", "type": "method", "name": "_parseFile"}, {"url": "Config.html#method__persistConfigsOnChange", "access": "protected", "host": "Config", "type": "method", "name": "_persistConfigsOnChange"}, {"url": "Config.html#method_setModuleDefaults", "access": "", "host": "Config", "type": "method", "name": "setModuleDefaults"}, {"url": "Config.html#method__stripComments", "access": "protected", "host": "Config", "type": "method", "name": "_stripComments"}, {"url": "Config.html#method__stripYamlComments", "access": "protected", "host": "Config", "type": "method", "name": "_stripYamlComments"}, {"url": "Config.html#method_watch", "access": "", "host": "Config", "type": "method", "name": "watch"}, {"url": "Config.html#method_watchForConfigFileChanges", "access": "", "host": "Config", "type": "method", "name": "watchForConfigFileChanges"}];
</script>
</body>
</html>