envconfig
Easily configure your Ruby / Rails app to use the backing services specified in environment variables such as those provided by Broadstack or Heroku add-ons.
This lets you easily switch between providers, or between development and production, without having configuration conditionals in your code.
For more on why this makes a lot of sense, read the Config and Backing Services sections of the excellent Twelve-Factor App written by Heroku co-founder Adam Wiggins.
Services and Providers
- Database: generic
DATABASE_URL. - memcached: MemCachier.
- MongoDB: MongoHQ, MongoLab.
- Redis: openredis, RedisCloud, RedisGreen, Redis To Go.
- SMTP: generic, Mailgun, Mandrill, Postmark, Sendgrid.
Examples
Given the following ENV vars:
POSTMARK_SMTP_SERVER="smtp.example.org"
POSTMARK_API_KEY="bcca0a78abbaed6533f3c8017b804bda"
MONGOHQ_URL="mongodb://user:pass@mongo.example.com:2468/stack618"Envconfig will look like this:
config = Envconfig.load
# Individual keys:
config.smtp[:address] # => "smtp.example.org"
config.mongodb[:host] # => "mongo.example.com"
# Service configuration:
config.smtp.to_h # => {
port: "25",
authentication: :plain,
address: "smtp.example.org",
user_name: "bcca0a78abbaed6533f3c8017b804bda",
password: "bcca0a78abbaed6533f3c8017b804bda"
}
config.mongodb.to_h # => {
url: "mongodb://user:pass@mongo.example.com:2468/stack618",
database: "stack618",
username: "user",
password: "pass",
host: "mongo.example.com",
port: 2468
}And if you're using Rails, ActionMailer will be automatically configured
to use those SMTP details via Rails.application.config.action_mailer.smtp_settings.
Installation
Add gem "envconfig" to your Gemfile and run bundle,
or gem install envconfig.
Usage
envconfig
The envconfig gem exposes your ENV configuration as a consistent interface,
using its knowledge of many add-on providers.
Envconfig.load.smtp[:address] => "example.org"
Envconfig.load.smtp.to_h # => {address: "example.org", ...}envconfig-rails
The envconfig-rails gem adds Rails integration, pushing certain configuration
into the Rails application where it makes sense. Currently this is limited to
configuring ActionMailer for SMTP; feel free to open issues discussing others.
Supported Add-ons
Database
- Generic (
DATABASE_URLinENV)
Database example:
ENV["DATABASE_URL"] = "postgres://ab:secret@example.org:1234/db?encoding=utf-8"
Envconfig.load.database.to_h # =>
{
url: "postgres://ab:secret@example.org:1234/db?encoding=utf-8",
adapter: "postgresql",
database: "db",
username: "ab",
password: "secret",
host: "example.org",
port: 1234,
encoding: "utf-8"
}
SMTP
- Postmark (Broadstack, Heroku)
- Mandrill (Heroku)
- SendGrid (Heroku)
- Mailgun (Heroku)
- Generic (
SMTP_HOST,SMTP_PORT,SMTP_USERNAME,SMTP_PASSWORDinENV)
SMTP example:
ENV["MANDRILL_USERNAME"] = "mandrilluser"
ENV["MANDRILL_APIKEY"] = SecureRandom.hex
Envconfig.load.smtp.to_h # =>
{
address: "smtp.mandrillapp.com",
port: "587",
user_name: "mandrilluser",
password: "14941007dfdc2af76e2fafe1383cf33b"
}memcached
- MemCachier (Broadstack, Heroku)
memcached example:
ENV["MEMCACHIER_SERVERS"] = "a.example.org:11211,b.example.com:11211"
ENV["MEMCACHIER_USERNAME"] = "memcachieruser"
ENV["MEMCACHIER_PASSWORD"] = SecureRandom.hex
Envconfig.load.memcached.to_h # =>
{
servers: "a.example.org:11211,b.example.com:11211",
username: "memcachieruser",
password: "9d1d72d6828ed59bab3d1496da71ba59",
server_strings: ["a.example.org:11211", "b.example.com:11211"]
}MongoDB
- MongoHQ (Broadstack, Heroku)
- MongoLab (Heroku)
MongoDB example:
ENV["MONGOHQ_URL"] = "mongodb://user:pass@mhq.example.org:2468/stack618"
Envconfig.load.mongodb.to_h # =>
{
url: "mongodb://user:secret@mhq.example.org:2468/stack618",
username: "user",
password: "secret",
host: "mhq.example.org",
port: 2468,
database: "stack618"
}Redis
- Generic (
REDIS_URLinENV) - openredis (Heroku)
- RedisCloud (Heroku)
- RedisGreen (Heroku)
- Redis To Go (Heroku)
Redis example:
ENV["OPENREDIS_URL"] = "redis://:secrettoken@127.0.0.1:6379"
Envconfig.load.redis.to_h # =>
{
url: "redis://:secrettoken@127.0.0.1:6379",
host: "127.0.0.1",
port: 6379,
user: "",
password: "secrettoken",
}Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request