envigor
v0.10.0
Published
Env-var-to-config-object generator
Downloads
12
Maintainers
Readme
envigor
envigor is a module that creates configuration objects for several modules and backing services based on what environment variables are available.
This is useful for automatically deciding configuration options for
twelve-factor apps that run in environments like
Heroku, where several different choices of addon can be provisioned to provide
the same service: calling envigor
will check the environment variables for
all known service providers (and a general set of variables for any services
that may be set up manually / in-house), then create a config object that will
connect to that service regardless of provider (envigor objects can usually be
passed directly to the setup function of multiple drivers).
Usage
The constructor returned by require('envigor')
takes an object of environment
variables (using process.env
by default), then returns a uniform object
containing the configuration properties specified by that environment.
Say you're making an Express app with MongoDB, that you're writing for a platform like Heroku, with addons like MongoLab to provide your more general services like MongoDB. By using envigor, you can set your app up to find a configured MongoDB service with complete provider agnosticism:
npm install --save envigor mongodb
heroku addons:add mongolab
server.js:
var http = require('http')
var cfg = require('envigor')();
var app = require('./app.js')(cfg);
http.createServer(app).listen(cfg.port || 5000, function() {
console.log("Listening on " + port);
});
app.js:
var express = require('express');
module.exports = function(cfg){
var app = express();
mongodb.MongoClient.connect(cfg.mongodb.url,function(err,db){
if(err) throw err; else app.set('db',db)
}
// ...your routes here...
return app;
}
With envigor, the structure of the app server is so common and lightweight that
it is provided as a binary with the library named envigorate
. Using
envigorate
, the only scaffolding you need to run an app is, in package.json:
"main": "app.js",
"scripts": {
"start": "envigorate"
}
(And you can technically leave out that first line if you use index.js
instead of app.js
.)
Configuration
In the root index.js
, envigor only adds a few properties:
port
, the value of the almost-inescapablePORT
variable, used for setting the port for a server to listen onip
, the value of theIP
variable, used in some environments to specify a specific network interface to listen ondatabase
, described in detail in the "database" section belowenv
, the environment variables used to construct the configuration
Every other object in envigor is set by a script in lib/cfg
, with a minimal
overview described below (read the files themselves for full details as to the
environment variables that can give the corresponding values).
cors
Headers for Cross-Origin Resource Sharing. Goes great with ach.
Note that allowOrigin and possibly maxAge are the only CORS configuration
parameters that are likely to be deployment-specific, and as such are the only
variables you should be setting through the environment / envigor()
. While
the rest are gathered by envigor, it's mostly for symmetry; they're more likely
to be specific to your code, and as such should be ignored / clobbered by
static strings when you set up CORS.
cors is also aliased as accessControl.
- allowOrigin
- allowCredentials
- exposeHeaders
- maxAge
- allowMethods
- allowHeaders
Adds: smtp, mandrill, postmark, sendgrid, mailgun
smtp
- username, user, auth.user
- password, pass, auth.pass
- hostname, host, server
- port
- service
mandrill
Mandrill by MailChimp
- username
- apiKey, password
postmark
https://postmarkapp.com
- apiKey
- inboundAddress
sendgrid
SendGrid (http://sendgrid.com)
- username
- password
mailgun
Mailgun: Programmable Mail Servers
- apiKey
- smtp
- username, user, login
- password, pass
- hostname, host, server
- port
mongodb
Services: mongolab, mongohq (aliased as compose.mongodb)
- url, uri
redis
Services: rediscloud, redistogo, myredis, openredis, redisgreen
- url
- hostname
- port
- password
- database
The individual fields will by default be gathered from url using the form
redis://database:password@hostname:port
if url is defined: if not, url
will be constructed from these fields.
You can also set DEFAULT_REDIS
to populate redis with all the default
values.
memcache
Services: memcachier, memcachedcloud
- servers, as an array split on semicolons and commas in the defined
variable. To reconstruct the string, use
servers.join(',')
. - username
- password
You can also set DEFAULT_MEMCACHE
to populate memcache
with all the default
values.
mysql
Services: cleardb
- url
neo4j
Services: graphenedb, graphstory
- url
rabbitmq
Services: rabbitmqBigwig, cloudamqp
rabbitmq is also aliased as amqp.
- url
- tx.url
- rx.url
rethinkdb
- hostname, host, server
- port
- database, db
- authKey, auth
- table
arangodb
- url
postgresql
- url
Note that, while DATABASE_URL
is conventionally used to refer to a PostgreSQL
database on Heroku, envigor does not use DATABASE_URL
as a fallback
name for the PostgreSQL URL. If you wish to have this behavior, add this
line after your call to require('envigor')();
.
cfg.postgresql = cfg.postgresql || cfg.database;
database
(Per the note in the section introduction, this is added in index.js.)
The "database" hash, if present, contains the content of env.DATABASE_URL
in
its url field.
Use of "database" / DATABASE_URL
is discouraged, and is included primarily
for the use of applications with legacy configuration schemas.
Note that, while DATABASE_URL
is conventionally used to refer to a PostgreSQL
database on Heroku, envigor does not use DATABASE_URL
as a fallback
name for the PostgreSQL URL. See the section on postgresql
.
bitcoin
RPC interfaces for cryptocurrency daemons patterned after bitcoind
Adds: bitcoin, litecoin, dogecoin
- hostname, host
- port
- username, user
- password, pass
amazonaws
Amazon Web Services
Adds: aws, s3
aws
- accessKey
- secret
s3
- accessKey, key
- secret
- bucket
- endpoint
Facebook App configuration
- appId, clientID
- secret, clientSecret
Reddit App configuration
- username
- password
- appId, clientID, consumerKey, oauth.consumerKey
- secret, clientSecret, consumerSecret, oauth.consumerSecret
Twitter application OAuth credentials
- key, consumerKey
- secret, consumerSecret
twilio
The Twilio cloud communications platform
- accountSid
- authToken
- number
recaptcha
reCAPTCHA - http://www.google.com/recaptcha
- privateKey
- publicKey
firebase
https://www.firebase.com/
- secret
- url
- appName