Simple Ruby framework-agnostic application configuration.

View project onGitHub


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:

AppConfig.setup!(admin_email: '')
# ..or..
AppConfig.setup! do |config|
  config.admin_email = ''

AppConfig.admin_email  # => ''

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


Given this YAML file:

admin_email: ''
api_name:    'Supr Webz 2.0'

Use it like so:

AppConfig.setup!(yaml: '/path/to/app_config.yml')

# Later on...
AppConfig.admin_email  # => ''
AppConfig.api_name     # => 'Supr Webz 2.0'
AppConfig.api_key      # => 'SUPERAWESOMESERVICE'


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.

# These are the defaults.
mongo_opts = {
  host:       'localhost',
  database:   'app_config',
  collection: 'app_config'

AppConfig.setup!(mongo: mongo_opts)

AppConfig.admin_email  # => ''

# Override an existing value and save to the database:
AppConfig.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' })


Using PostgreSQL is similar to a Mongo setup. The only current requirement is that the table have a primary key named id. All other columns are used as configuration keys.

Note: The database and schema must exist prior to calling AppConfig.setup!.

Given this schema:

CREATE TABLE app_config (
  id bigserial NOT NULL PRIMARY KEY,
  admin_email character varying(255) DEFAULT ''::character varying,
  api_key character varying(255) DEFAULT 'SOME_API_KEY'::character varying

Setup AppConfig:

# These are the defaults.
postgres_opts = {
  host:     'localhost',
  port:     5432,
  dbname:   'app_config',
  table:    'app_config',

  # If these are nil (or omitted), the PostgreSQL defaults will be used.
  user:     nil,
  password: nil,

AppConfig.setup!(postgres: postgres_opts)

AppConfig.admin_email  # => ''

# Override an existing value and save to the database:
AppConfig.admin_email = ''!

Using Storage Defaults

All storage options accept true as a value, which uses the default options for that storage.

For example, to use the Mongo defaults:

AppConfig.setup!(mongo: true)

Storage Defaults

Deprecation Note

Version 2.x is not backwards compatible with the 1.x branch.

See the wiki for current usage instructions.