Simple Rails app configuration
Figaro v2 development is underway but stalled. I need your help! Please consider sponsoring Figaro's development.
With the constraints of a family and a full-time job, even the emotional support that sponsorship provides is extremely valuable in re-energizing Figaro development. Thank you! 💛
Simple, Heroku-friendly Rails app configuration using
ENVand a single YAML file
NOTE: If you're using Figaro 0.7 or prior, please refer to the appropriate documentation or upgrade to Figaro 1.0.
Figaro was written to make it easy to securely configure Rails applications.
Configuration values often include sensitive information. Figaro strives to be secure by default by encouraging a convention that keeps configuration out of Git.
Figaro is inspired by the Twelve-Factor App methodology, which states:
The twelve-factor app stores config in environment variables (often shortened to env vars or env). Env vars are easy to change between deploys without changing any code; unlike config files, there is little chance of them being checked into the code repo accidentally; and unlike custom config files, or other config mechanisms such as Java System Properties, they are a language- and OS-agnostic standard.
This is straightforward in production environments but local development environments are often shared between multiple applications, requiring multiple configurations.
Figaro parses a Git-ignored YAML file in your application and loads its values into
ENV.
Add Figaro to your Gemfile and
bundle install:
gem "figaro"
Figaro installation is easy:
$ bundle exec figaro install
This creates a commented
config/application.ymlfile and adds it to your
.gitignore. Add your own configuration to this file and you're done!
Given the following configuration file:
# config/application.ymlpusher_app_id: "2954" pusher_key: "7381a978f7dd7f9a1117" pusher_secret: "abdc3b896a0ffb85d373"
You can configure Pusher in an initializer:
# config/initializers/pusher.rbPusher.app_id = ENV["pusher_app_id"] Pusher.key = ENV["pusher_key"] Pusher.secret = ENV["pusher_secret"]
Please note:
ENVis a simple key/value store. All values will be converted to strings. Deeply nested configuration structures are not possible.
Oftentimes, local configuration values change depending on Rails environment. In such cases, you can add environment-specific values to your configuration file:
# config/application.ymlpusher_app_id: "2954" pusher_key: "7381a978f7dd7f9a1117" pusher_secret: "abdc3b896a0ffb85d373"
test: pusher_app_id: "5112" pusher_key: "ad69caf9a44dcac1fb28" pusher_secret: "83ca7aa160fedaf3b350"
You can also nullify configuration values for a specific environment:
# config/application.ymlgoogle_analytics_key: "UA-35722661-5"
test: google_analytics_key: ~
Figaro.env
Figaro.envis a convenience that acts as a proxy to
ENV.
In testing, it is sometimes more convenient to stub and unstub
Figaro.envthan to set and reset
ENV. Whether your application uses
ENVor
Figaro.envis entirely a matter of personal preference.
# config/application.ymlstripe_api_key: "sk_live_dSqzdUq80sw9GWmuoI0qJ9rL"
ENV["stripe_api_key"] # => "sk_live_dSqzdUq80sw9GWmuoI0qJ9rL" ENV.key?("stripe_api_key") # => true ENV["google_analytics_key"] # => nil ENV.key?("google_analytics_key") # => falseFigaro.env.stripe_api_key # => "sk_live_dSqzdUq80sw9GWmuoI0qJ9rL" Figaro.env.stripe_api_key? # => true Figaro.env.google_analytics_key # => nil Figaro.env.google_analytics_key? # => false
If a particular configuration value is required but not set, it's appropriate to raise an error. With Figaro, you can either raise these errors proactively or lazily.
To proactively require configuration keys:
# config/initializers/figaro.rbFigaro.require_keys("pusher_app_id", "pusher_key", "pusher_secret")
If any of the configuration keys above are not set, your application will raise an error during initialization. This method is preferred because it prevents runtime errors in a production application due to improper configuration.
To require configuration keys lazily, reference the variables via "bang" methods on
Figaro.env:
# config/initializers/pusher.rbPusher.app_id = Figaro.env.pusher_app_id! Pusher.key = Figaro.env.pusher_key! Pusher.secret = Figaro.env.pusher_secret!
Figaro is written with deployment in mind. In fact, Heroku's use of
ENVfor application configuration was the original inspiration for Figaro.
Heroku already makes setting application configuration easy:
$ heroku config:set google_analytics_key=UA-35722661-5
Using the
figarocommand, you can set values from your configuration file all at once:
$ figaro heroku:set -e production
For more information:
$ figaro help heroku:set
If you're not deploying to Heroku, you have two options:
ENVvariables directly
Generating a remote configuration file is preferred because of:
config/application.ymlis like that of
config/database.yml.
Yes. Kind of.
Figaro and dotenv were written around the same time to solve similar problems.
ENV.
KEY=VALUEpairs.
Either library may suit your configuration needs. It often boils down to personal preference.
Yes. Kind of.
Rails 4.1 introduced the
secrets.ymlconvention for Rails application configuration. Figaro predated the Rails 4.1 release by two years.
ENV.
Rails.application.secrets.
ENVfor configuration in every environment.
ENVfor production only.
The emergence of a configuration convention for Rails is an important step, but as long as the last three differences above exist, Figaro will continue to be developed as a more secure, more consistent, and more standards-compliant alternative to
secrets.yml.
For more information, read the original The Marriage of Figaro… and Rails blog post.
In most cases, upgrading from Figaro 0.7 to 1.0 is painless. The format expectations for
application.ymlare the same in 1.0 and values from
application.ymlare loaded into
ENVas they were in 0.7.
However, there are breaking changes:
Figaro.env
In Figaro 0.7, calling a method on the
Figaro.envproxy would raise an error if a corresponding key were not set in
ENV.
In Figaro 1.0, calling a method on
Figaro.envcorresponding to an unset key will return
nil. To emulate the behavior of Figaro 0.7, use "bang" methods as described in the Required Keys section.
NOTE: In Figaro 0.7,
Figaro.envinherited from
Hashbut in Figaro 1.0, hash access has been removed.
In Figaro 0.7, a Rake task existed to set remote Heroku configuration according to values in
application.yml.
In Figaro 1.0, the Rake task was replaced by a command for the
figaroexecutable:
$ figaro heroku:set -e production
For more information:
$ figaro help heroku:set
NOTE: The environment option is required for the
heroku:setcommand. The Rake task in Figaro 0.7 used the default of "development" if unspecified.
If you're using Spring, either stop or add
config/application.ymlto the watch list:
# config/spring.rb%w( ... config/application.yml ).each { |path| Spring.watch(path) }
My name is Steve Richert and I wrote Figaro in March, 2012 with overwhelming encouragement from my employer, Collective Idea. Figaro has improved very much since then, thanks entirely to inspiration and contribution from developers everywhere.
Thank you!
Figaro is open source and contributions from the community are encouraged! No contribution is too small.
See Figaro's contribution guidelines for more information.