Simple Ruby framework-agnostic application configuration.
Ruby JavaScript
Pull request Compare This branch is 61 commits ahead, 88 commits behind Oshuma:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

AppConfig Build Status Dependency Status

An easy to use, customizable library to easily store and retrieve application (or library) configuration, API keys or basically anything in 'key/value' pairs.


Usage is simple. Just pass either a hash of options, or a block, to {AppConfig.setup}.

In it's simplest form, you can use it like so:

config = AppConfig.setup do |config|
  config[:admin_email] = ''
  # Other setter:
  # config["admin_email"] = ''
  # config.admin_email = ''

# Strings or symbols or dynamic methods as keys.
config[:admin_email]  #=> ''
config["admin_email"] #=> ''
config.admin_email    #=> ''

You may also specify the storage method along with options specific to that storage method. Check the wiki for more usage examples.

If you like to use the {AppConfig::Configurable} module, see how easy it is:

module Client
  include Configurable

  def set_config
    # Use it everywhere you want
    config.api_url     = ""
    config.api_key     = "2H28dsaa4"
    config.api_version = "2"

Please scroll down to the last chapter for more informtation and details.

Deprecation Note

Version 2.0 is not backwards compatible with 1.0 and 0.7.1! See the wiki for upgrade instructions.


Given this YAML file:

admin_email: ''
api_name:    'Supr Webz 2.0'

Use it like so:

config = AppConfig.setup(:yaml => '/path/to/app_config.yml')

# Later on...
# Strings or symbols or dynamic methods as keys.
config['admin_email'] #=> ''
config.api_name       #=> 'Supr Webz 2.0'
config[:api_key]      #=> 'SUPERAWESOMESERVICE'

Create the YAML file, if it doesn't exist

I like to create the YAML file, if it doesn't exist

config = AppConfig.setup(:yaml => '/path/to/file_doesnt_exist.yml', :create => true)
# File will be created with all non-existing directories.

# Later on...
config['admin_email'] = ''
config['admin_email'] #=> ''

Save all changes automatically

When you use your config sometimes, it would be nice, if your config will be saved automatically to your YAML file.

config = AppConfig.setup(:yaml => '/path/to/app_config.yml', :save_changes => true)

# Later on...
config['admin_email'] #=> ''
# YAML file will be written and includes 'admin_email'.


You can pass a :mongo options hash to {AppConfig.setup} which should contain configuration values for a Mongo database. Check the {AppConfig::Storage::Mongo::DEFAULTS} constant for the default Mongo connection options.

mongo_opts = {
  :host       => 'localhost',   # default
  :database   => 'app_config',  # default
  :collection => 'app_config'   # default

config = AppConfig.setup(:mongo => mongo_opts)

config[:admin_email] #=> ''

# Override an existing value (saves to the database):
config[:admin_email] = ''

The values are read/saved (by default) to the app_config database and app_config collection. These defaults can be overridden, however, which might lend well to versioned configurations; collection names such as app_config_v1, app_config_v2, etc.

AppConfig.setup(:mongo => { :collection => 'app_config_v2' })

Environment Mode

There's also an 'environment mode' where you can organize the config sort of like the Rails database config. Given this YAML file:

# Rails.root/config/app_config.yml
  title: 'Development Mode'

  title: 'Production Mode'

Set the :env option to your desired environment.

# Rails.root/config/initializers/app_config.rb
config = config.setup({
  :yaml => "#{Rails.root}/config/app_config.yml",
  :env  => Rails.env  # or any string

# Uses the given environment section of the config.
# => 'Production Mode'

Module Configurable

You can include the module Configurable to have access to your configuration in all your code. This module is created to include it in all classes where you want to have access to your configuration.

Forcing or reloading

Your access by config is cached. So if you'd like to have another object, you could do this by passing :force or :reload.

config.object_id #=> 123456
config(:force => true).object_id #=> 654321
# ..or..
config(:reload => true)

New object, because :force is set

config(:force => true)

New object, because :force is set and block is given

config(:force => true) { |config| config[:key] = "value" }

New object, because :force isn't set and block is given

config { |config| config[:key] = "value" }

No new object, because :force is false and block is given

config(:force => false) { |config| config[:key] = "value" }

Creates a new object and YAML file will be empty

config(:yaml => "path/to/file.yml", :force => true, :save_changes => true)"path/to/file.yml") #=> "--- {}"

See {AppConfig::Configurable#config} for datails.