README.md in envied-0.3.1 vs README.md in envied-0.4.0
- old
+ new
@@ -1,6 +1,6 @@
-# ENVied
+# ENVied [](https://secure.travis-ci.org/#!/eval/envied)
### TL;DR ensure presence and type of your app's ENV-variables.
For applications that are configured via ENV-variables, this gem will provide:
@@ -18,37 +18,65 @@
Let's configure the ENV-variables we need:
```ruby
# e.g. config/application.rb
-ENVied.configure do |env|
- env.variable :force_ssl, :Boolean
- env.variable :port, :Integer
+ENVied.configure do
+ variable :FORCE_SSL, :Boolean
+ variable :PORT, :Integer
end
```
### 2) Check for presence and type
```ruby
-ENVied.require!
+ENVied.require
```
-Excecution will halt unless ENV is something like
-`{'FORCE_SSL' => 'false', 'PORT' => '3001'}`.
-A meaningful error will in this case explain what key and type is needed.
+This will throw an error if not:
+* both `ENV['FORCE_SSL']` and `ENV['PORT']` are present
+* both the values of `ENV['FORCE_SSL']` and `ENV['PORT']` can be coerced (to resp. Boolean or Integer).
+(The error contains exactly what ENV-variables are missing/faulty.)
+
### 3) Use typed variables
Variables accessed via ENVied have the configured type:
```ruby
-ENVied.port # => 3001
-ENVied.force_ssl # => false
+ENVied.PORT # => 3001
+ENVied.FORCE_SSL # => false
```
## Configuration
+### Groups
+
+Groups give you more flexibility to define when variables are needed.
+It's just like you Gemfile:
+
+```ruby
+ENVied.configure do
+ variable :FORCE_SSL, :Boolean
+
+ group :production do
+ variable :NEW_RELIC_LICENSE_KEY
+ end
+end
+
+# For local development you would typically do:
+ENVied.require(:default) #=> Only ENV['FORCE_SSL'] is required
+# On the server:
+ENVied.require(:default, :production) #=> ...also ENV['NEW_RELIC_LICENSE_KEY'] is required
+
+# BTW the following are equivalent:
+ENVied.require
+ENVied.require(:default)
+ENVied.require('default')
+ENVied.require(nil)
+```
+
### Types
The following types are supported:
* `:String` (implied)
@@ -61,22 +89,73 @@
### Defaults
In order to let other developers easily bootstrap the application, you can assign defaults to variables.
Defaults can be a value or a `Proc` (see example below).
-Note that 'easily bootstrap' is quite the opposite of 'fail-fast when not all ENV-variables are present'. Therefor it's disabled by default and you should explicitly state whén it is allowed:
+Note that 'easily bootstrap' is quite the opposite of 'fail-fast when not all ENV-variables are present'. Therefor you should explicitly state whén defaults are allowed:
```ruby
-ENVied.configure(enable_defaults: Rails.env.development?) do |env|
- env.variable :port, :Integer, default: proc {|env, variable| env.force_ssl ? 443 : 80 }
- env.variable :force_ssl, :Boolean, default: false
+ENVied.configure(enable_defaults: ENV['RACK_ENV'] == 'development') do
+ variable :FORCE_SSL, :Boolean, default: false
+ variable :PORT, :Integer, default: proc {|envied| envied.FORCE_SSL ? 443 : 80 }
end
```
-Please remember that ENVied only **reads** from ENV; don't let setting a default for, say `rails_env`, give you or your team the impression that `ENV['RAILS_ENV']` is set.
-As a rule of thumb: you should only use defaults:
-* in a development-environment
+Please remember that ENVied only **reads** from ENV; it doesn't set ENV-variables.
+Don't let setting a default for, say `RAILS_ENV`, give you the impression that `ENV['RAILS_ENV']` is set.
+As a rule of thumb you should only use defaults:
+* for local development
* for ENV-variables that your application introduces (i.e. for `ENV['DEFAULT_SENDER']` not for `ENV['REDIS_URL']`)
+
+### A more extensive example:
+
+```ruby
+# We allow defaults for local development (and local tests), but want our CI
+# to mimic our production as much as possible.
+# New developers that don't have RACK_ENV set, will in this way not be presented with a huge
+# list of missing variables, as defaults are still enabled.
+not_production_nor_ci = ->{ !(ENV['RACK_ENV'] == 'production' || ENV['CI']) }
+ENVied.configure(enable_defaults: ¬_production_nor_ci) do
+ # Your code will likely not use ENVied.RACK_ENV (better use Rails.env),
+ # we want it to be present though; heck, we're using it in this file!
+ variable :RACK_ENV
+
+ variable :FORCE_SSL, :Boolean, default: false
+ variable :PORT, :Integer, default: 3000
+ # generate the default value using the value of PORT:
+ variable :PUBLIC_HOST_WITH_PORT, :String, default: proc {|envied| "localhost:#{envied.PORT}" }
+
+ group :production do
+ variable :MAIL_PAAS_USERNAME
+ variable :DATABASE_URL, :Symbol
+ end
+
+ group :ci do
+ # ci-only stuff
+ end
+
+ group :not_ci do
+ # CI needs no puma-threads, and sidekiq-stuff etc.
+ # Define that here:
+ variable :MIN_THREADS, :Integer, default: 1
+ # more...
+ end
+end
+
+# Depending on our situation, we can now require the groups needed:
+# At local machines:
+ENVied.require(:default, :development, :not_ci) or
+ENVied.require(:default, :test, :not_ci)
+
+# At the server:
+ENVied.require(:default, :production, :not_ci)
+
+# At CI:
+ENVied.require(:default, :test, :ci)
+
+# All in one line:
+ENVied.require(:default, ENV['RACK_ENV'], (ENV['CI'] ? :ci : :not_ci))
+```
## Installation
Add this line to your application's Gemfile: