Persey Build Status Gem VersionCode Climate Downloads count


Persey help you easily manage the configuration, depending on the environment. The main objective is to provide opportunities to reuse the configuration provided by the project, as the default configuration.


For the occurrence of the gem was a few prerequisites.

  • Work on opensource projects that support the relevance of problem configurations, changing the appearance of new versions and functionality.
  • Use in the project configuration, diversity in different files, and the inability to unite all in one configuration
  • Desire to use sensitive data as easily as those that can be safely stored in the repository.
  • Sometimes configuration happens in a variety of formats: yaml, json, ini

I do not want to engage in writing parsers, I want to work fine :)

This solution allows to accumulate different configs in one, with the possibility of reusability of configuration options and simple override. It uses an intuitive DSL.


Add this to your Gemfile:

gem "persey", '>= 1.0.0'

Generate default config file

$ rails g persey:install



# Rails.root are not initialized here
app_path = File.expand_path('../../', __FILE__)

# your redis config
redis_config = File.join(app_path, 'config', 'redis.yml.example')

# your project config
# as example - it's default options from opensource
# you don't want redeclare then with copy default file
project_config = File.join(app_path, 'config', 'project.yml.example')

# some different environment specifed configuration options in separate config
project_env_config = File.join(app_path, 'config', "project.#{Rails.env}.yml")

# config for awesome gem
awesome_gem_config = File.join(app_path, 'config', 'awesome_gem_config.yml')

# config with secret keys
# you don't want store this config in repository and copy to secret folder on host machine
my_secret_key_config = '/home/user/secret/keys.yml'

# We support not only YAML
# Also JSON
my_node_js_config = '/rest/u/apps/node/config.json'
# And TOML
my_berkshelf_config = File.join(app_path, 'provisioning', '.berkshelf')
# And INI
my_ini_config = File.join(app_path, 'provisioning', 'php.ini') # lol
# And AWS SSM secure string (we assume you're using JSON inside)
my_ssm_config = '/some/ssm/parameter/path.json'

# Persey.init ENV["environment"] do # set current environment
Persey.init Rails.env do # set current environment
  source :yaml, redis_config,         :redis              # set specific namespace for settings (mount config in :redis key)
  source :yaml, project_config                            # if project config and project_env_config have some options keys
  source :yaml, project_env_config                        # last declared keys overwite before declared
  source :yaml, awesome_gem_config,   :awesome_gem        # it's good to mount unknown configs to special :namespace
  source :yaml, my_secret_key_config, :secret             # no comments. It's secret!
  source :json, my_node_js_config,    :node_js_namespace
  source :toml, my_berkshelf_config,  :berkshelf_namespace
  source :ini,  my_ini_config,        :ini_namespace
  source :ssm,  my_ssm_config,        :ssm_namespace

  env :production do
    site_name 'Example'
    web do
      # domain   ''   # domain described in project_env_config
                                 # you can use them, or overwirite here
      protocol 'https'           # we overwrite prolocol option here
                                 # by default was 'http', but we need some little security
      port      12345            # more, more security!
      # and now we use configs for our options, which are not declared in any config
      uri      -> { "#{protocol}://#{domain}:#{port}" }

    site_uri   -> { web.uri }    # we can re-re-use different options

    email do
      pop do
        address ''
        port    110
      smtp do
        address ''
        port    25

  env :development, :parent => :production do
    web do
      domain   'localhost'
      protocol 'http'
      port      9292
    email do
      smtp do
        address ''

If you generate Persey config with run rails g persey:install in your config/application.rb were added strings to run config initialization. If you do not run installer, you can specify of run config manually. For example:

in your config/application.rb

# We require gem here
require "persey"
require File.expand_path('../config', __FILE__)

module AppName
  # If you don't want use configs with call Persey.config
  # you can do something like it:
  def self.config

  class Application < Rails::Application
    # ...


config = Persey.config

config.site_name      # => 'Example'
config.web.uri        # => ''
config.site_uri       # => '' # => 110

AppName.config.site_name # => 'Example'


define your config in config/config.rb

Persey.init Rails.env do
  # settings


# config/environments/development.rb
ActionDispatch::Reloader.to_prepare do
  load Rails.root.join('config/config.rb')

Supported config formats

  • YAML
  • JSON
  • TOML
  • INI
  • AWS SSM Secure string (json inside)



  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Another help

You can give me feedback with issue.