Maps on-disk config files into a loaded global configatron instance, taking into account your current environment.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib Version 0.2.3 Feb 10, 2016
test Don't hard-code file path in test Feb 10, 2016
.gitignore Version 0.2.1 May 8, 2015
.travis.yml Add .travis.yml May 8, 2015
.yardopts Version 0.2.1 May 8, 2015
Gemfile Version 0.2.1 May 8, 2015
LICENSE.txt Version 0.2.1 May 8, 2015 Version 0.2.1 May 8, 2015
Rakefile Version 0.2.1 May 8, 2015
chalk-config.gemspec Version 0.2.1 May 8, 2015
demo_schema.rb Version 0.2.1 May 8, 2015


Maps on-disk config files into a loaded global configatron instance, taking into account your current environment.

configatron is used within many Chalk gems to control their behavior, and is also great for configuration within your application.



Chalk::Config relies on describing your environment as an opaque string (production, qa, etc). You can set it like so:

Chalk::Config.environment = 'production'

At that point, the global configatron will be cleared and all registered config reapplied, meaning you don't have to worry about setting the environment prior to registering files.

environment defaults to the value 'default'.

Registering config files

Additional configuration files are registered using {Chalk::Config.register}. The most basic usage looks like


to register a YAML configuration file. You must provide an absolute path, in order to ensure you're not relying on the present working directory. The following is a pretty good idiom:

Chalk::Config.register(File.expand_path('../config.yaml', __FILE__))

By default, YAML configuration files should have a top-level key for each environment.

A good convention is to have most configuration in a dummy default environment and use YAML's native merging to keep your file somewhat DRY (WARNING: there exists at least one gem which changes Ruby's YAML parser in the presence of multiple merge operators on a single key, so be wary of two << calls at once.) However, it's also fine to repeat yourself to make the file more human readable.

# /path/to/config.yaml

default: &default
    enable: true
    shards: 2

    host: localhost
    port: 2800

  <<: *default
    host: appserver1
	port: 2800

  send_emails: true

  <<: *default
  send_emails: false

The configuration from the currently active environment will then be added to the global configatron when you register the file:


Chalk::Config.environment = 'production'
#=> 'appserver1'

Chalk::Config.environment = 'development'
#=> 'localhost'

Keys present in multiple files will be deep merged:

# /path/to/site.yaml

    host: otherappserver

development: {}

Chalk::Config.environment = 'production'
#=> 'otherappserver'
#=> 2800

You can explicitly nest a config file (only a single level of nesting is current supported) using the :nested option. You can also indicate a file has no environment keys and should be applied directly via :raw:

# /path/to/cookies.yaml

tasty: yes
Chalk::Config.register('/path/to/cookies.yaml', nested: 'cookies', raw: true)
#=> 'yes'

Best practices

Config keys for everything

Writing code that switches off the environment is usually indicative of the antipattern:

# BAD!
if Chalk::Config.environment == 'production'
  puts email

Instead, you should create a fresh config key for all of these cases:

if configatron.send_emails
  puts email

This means your code doesn't need to know anything about the set of environment names, making adding a new environment easy. As well, it's much easier to have fine-grained control and visibility over exactly how your application behaves.

It's totally fine (and expected) to have many config keys that are used only once.


  • Greg Brockman
  • Evan Broder
  • Michelle Bu
  • Nelson Elhage
  • Jeremy Hoon