{"id":15033134,"url":"https://github.com/krystal/konfig","last_synced_at":"2025-10-23T07:37:47.347Z","repository":{"id":143172455,"uuid":"614984102","full_name":"krystal/konfig","owner":"krystal","description":"🧳 This toolkit allows you to easily access configuration variables from a variety of different sources based on a pre-defined schema.","archived":false,"fork":false,"pushed_at":"2024-03-08T15:57:42.000Z","size":49,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-24T08:32:55.761Z","etag":null,"topics":["config","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/krystal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-16T17:59:20.000Z","updated_at":"2023-05-22T13:49:16.000Z","dependencies_parsed_at":"2024-03-08T16:47:42.234Z","dependency_job_id":"ba1df794-8b82-463b-8a08-b663a10ce00a","html_url":"https://github.com/krystal/konfig","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krystal%2Fkonfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krystal%2Fkonfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krystal%2Fkonfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krystal%2Fkonfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krystal","download_url":"https://codeload.github.com/krystal/konfig/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248124848,"owners_count":21051757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["config","ruby"],"created_at":"2024-09-24T20:20:12.051Z","updated_at":"2025-10-23T07:37:42.272Z","avatar_url":"https://github.com/krystal.png","language":"Ruby","readme":"# Konfig\n\n\u003ca href=\"https://rubygems.org/gems/konfig-config\"\u003e\n  \u003cimg src=\"https://img.shields.io/gem/v/konfig-config?label=RubyGems\u0026logo=rubygems\" alt=\"RubyGems\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/krystal/konfig-config/actions\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/krystal/konfig/commit.yaml?branch=main\u0026logo=github\" alt=\"Actions Status\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/krystal/konfig/blob/main/MIT-LICENSE\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/krystal/konfig.svg?style=flat\" alt=\"License Status\"\u003e\n\u003c/a\u003e\n\nThis toolkit allows you to easily access configuration variables from a variety of different sources based on a pre-defined schema.\n\nThere are a few built-in config sources that you can use, but you can also easily create your own. The sources available out the box are:\n\n- Environment variables\n- YAML files\n- Directory of plain text files\n\n## Installation\n\nJust add the gem to your Gemfile as normal.\n\n```ruby\ngem 'konfig-config', '~\u003e 2.0'\n```\n\n## Getting started\n\nIt's fairly easy to get started with Konfig. The block below shows the key things you need to know.\n\n```ruby\n# Begin by defining a schema which you wish to use for your application.\n# This should be configured globally.\nschema = Konfig::Schema.draw do\n\n  group :app do\n    string :hostname do\n      description \"The hostname for the application\"\n    end\n\n    integer  :port do\n      description \"The port for the application\"\n      default 8080\n    end\n\n    string :extra_hostnames do\n      array\n      description \"Additional hosts to be permitted to receive requests\"\n      transform { |v| v.downcase }\n    end\n  end\n\n  # You can also define things more succicntly if you wish.\n  group :mysql do\n    string    :hostname,        default: 'localhost'\n    integer   :port,            default: 3306\n    string    :username,        default: 'root'\n    string    :password\n    string    :database_name,   default: 'my_database'\n    string    :roles,           array: true\n  end\n\nend\n\n# Create a source object. In this example, we're using the environment\n# variables source and providing `ENV` which contains all the environment\n# variables provided to the process.\nsource = Konfig::Sources::Environment.new(ENV)\n\n# Create your final configuration object by providing an array of sources.\nconfig = Konfig::Config.build(schema, sources: [source])\nconfig.app.hostname = \"localhost\"\nconfig.app.port = 8080\nconfig.app.extra_hostnames = [\"example.com\", \"example.org\"]\n```\n\n## Notes\n\n- All configuration is evaluated when the config is built.\n- There is no nesting of configuration other than adding all attributes into a group at present.\n- When config is built, values will be used from the sources in the order they are provided. If a value is not found in a source, the next source will be used otherwise the value will come from the default configured in the schema.\n\n## Types\n\nYou can use the following types in your schema:\n\n- `string`\n- `integer`\n- `float`\n- `boolean`\n\n## Value transformation\n\nYou can transform the value of an attribute by providing a block to the `transform` method. The block will be passed the value of the attribute and should return the transformed value.\n\n```ruby\ngroup :app do\n  string :trusted_ipds do\n    array\n    transform { |ip| IPAddr.new(ip) }\n  end\nend\n```\n\nThe values provided as default will also be passed through the transform block. For example, the block below will result an default being returned as an array of `IPAddr` objects.\n\n```ruby\ngroup :app do\n  string :trusted_ipds do\n    array\n    default ['1.2.3.4', '5.5.5.5']\n    transform { |ip| IPAddr.new(ip) }\n  end\nend\n```\n\n## Source options\n\n### Environment variables\n\nIf you have your configuration in environment variables, you can load that in as shown. Environment variables are the most common source of configuration. The config value will be taken by uppercasing the group and attribute name and joining them with an underscore. For example, the config value for `web.hostname` will be taken from the environment variable `WEB_HOSTNAME`.\n\n```ruby\nsource = Konfig::Sources::Environment.new(ENV)\n\n# If your attribute is an array, by default, it will be split based on commas.\n# You can override this if you wish.\nsource = Konfig::Sources::Environment.new(ENV, array_seperator: /\\s+/)\n```\n\n### YAML\n\nIf you have your configuration in a YAML file, you can load that in as shown.\n\n```ruby\nsource = Konfig::Sources::YAML.new(File.read('config.yml'))\n```\n\n### Directory\n\nIf you have a directory of plain text files, you can load that in as shown. This is likely if you are mounting a config map on a Kubernetes cluster, for example. The path to the config file will be determined by joining the group name and the attribute name with a `.`. For example, the config value for `web.hostname` will be taken from the file `/config/web.hostname` (where `/config` is the path you provide to the directory).\n\n```ruby\nsource = Konfig::Sources::Directory.new('/config')\n\n# By default, the contents of the file read will be stripped. You can disable\n# this if you wish.\nsource = Konfig::Sources::Directory.new('/config', strip_contents: false)\n\n# If your attribute is an array, by default, it will be split based on\n# new line characters. You can override this if you wish.\nsource = Konfig::Sources::Directory.new('/config', array_seperator: /\\,/)\n```\n\n## Exporting configuration\n\nYou can export your configuration schema to various formats as needed. Right now, the only built in option is Markdown.\n\n```ruby\nrequire 'konfig/exporters/env_vars_as_markdown'\noutput = Konfig::Exporters::EnvVarsAsMarkdown.new(schema).export\nFile.write(\"CONFIG.md\", output)\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrystal%2Fkonfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrystal%2Fkonfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrystal%2Fkonfig/lists"}