{"id":13410830,"url":"https://github.com/sherifabdlnaby/configuro","last_synced_at":"2025-07-03T08:34:47.158Z","repository":{"id":54118354,"uuid":"254488718","full_name":"sherifabdlnaby/configuro","owner":"sherifabdlnaby","description":"An opinionated configuration loading framework for Containerized and Cloud-Native applications.","archived":false,"fork":false,"pushed_at":"2022-09-26T13:44:43.000Z","size":78,"stargazers_count":96,"open_issues_count":1,"forks_count":14,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-01T23:34:52.953Z","etag":null,"topics":["12-factor","cloud-native","config","configuration","containerization","enviroment-variables","go","yaml-configuration"],"latest_commit_sha":null,"homepage":"https://medium.com/better-programming/designing-cloud-native-configuration-framework-eefb0b3793cb","language":"Go","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/sherifabdlnaby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null}},"created_at":"2020-04-09T22:10:34.000Z","updated_at":"2025-01-15T01:48:13.000Z","dependencies_parsed_at":"2022-08-13T07:00:33.988Z","dependency_job_id":null,"html_url":"https://github.com/sherifabdlnaby/configuro","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/sherifabdlnaby/configuro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherifabdlnaby%2Fconfiguro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherifabdlnaby%2Fconfiguro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherifabdlnaby%2Fconfiguro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherifabdlnaby%2Fconfiguro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sherifabdlnaby","download_url":"https://codeload.github.com/sherifabdlnaby/configuro/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherifabdlnaby%2Fconfiguro/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263291030,"owners_count":23443697,"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":["12-factor","cloud-native","config","configuration","containerization","enviroment-variables","go","yaml-configuration"],"created_at":"2024-07-30T20:01:09.615Z","updated_at":"2025-07-03T08:34:47.138Z","avatar_url":"https://github.com/sherifabdlnaby.png","language":"Go","funding_links":[],"categories":["配置","Configuration","Uncategorized","配置管理 `配置解析库`","配置管理"],"sub_categories":["标准CLI","Standard CLI","Advanced Console UIs","标准 CLI"],"readme":"\u003cp align=\"center\"\u003e\n\u003cbr/\u003e\n\u003cbr/\u003e\n\u003cimg width=\"637px\" src=\"https://user-images.githubusercontent.com/16992394/78989442-e7c1ae80-7b33-11ea-98c6-1d37ed276a3b.png\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003eOpinionated configuration loading framework for Containerized and \u003ca href=\"https://12factor.net/config\"\u003e12-Factor\u003c/a\u003e compliant applications.\u003c/h3\u003e\n\u003ch6 align=\"center\"\u003eRead configurations from Environment Variables, and/or Configuration Files. With support to Environment Variables Expanding and Validation Methods.\u003c/h4\u003e\n\u003cp align=\"center\"\u003e\n   \u003ca href=\"https://github.com/avelino/awesome-go#configuration\"\u003e\n      \u003cimg src=\"https://awesome.re/mentioned-badge.svg\" alt=\"Mentioned in Awesome Go\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"http://godoc.org/github.com/sherifabdlnaby/configuro\"\u003e\n      \u003cimg src=\"https://godoc.org/github.com/sherifabdlnaby/configuro?status.svg\" alt=\"Go Doc\"\u003e\n   \u003c/a\u003e\n   \u003ca\u003e\n      \u003cimg src=\"https://img.shields.io/github/v/tag/sherifabdlnaby/configuro?label=release\u0026amp;sort=semver\"\u003e\n    \u003c/a\u003e\n   \u003ca\u003e\n      \u003cimg src=\"https://img.shields.io/badge/Go-%3E=v1.11-blue?style=flat\u0026logo=go\" alt=\"Go Version\"\u003e\n   \u003c/a\u003e\n    \u003ca\u003e\n      \u003cimg src=\"https://github.com/sherifabdlnaby/configuro/workflows/Build/badge.svg\"\u003e\n    \u003c/a\u003e\n    \u003ca href='https://coveralls.io/github/sherifabdlnaby/configuro'\u003e\u003cimg src='https://img.shields.io/coveralls/github/sherifabdlnaby/configuro?logo=codecov\u0026logoColor=white' alt='Coverage Status' /\u003e\u003c/a\u003e\n   \u003ca href=\"https://goreportcard.com/report/github.com/sherifabdlnaby/configuro\"\u003e\n      \u003cimg src=\"https://goreportcard.com/badge/github.com/sherifabdlnaby/configuro\" alt=\"Go Report\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://raw.githubusercontent.com/sherifabdlnaby/configuro/blob/master/LICENSE\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"GitHub license\"\u003e\n   \u003c/a\u003e\n\u003c/p\u003e\n\n# Introduction\n\nConfiguro is an opinionated configuration loading and validation framework with not very much to configure. It *defines* a method for loading configurations without so many options for a straight-forward and simple code.\n\nThe method defined by Configuro allow you to implement [12-Factor's Config](https://12factor.net/config) and it mimics how many mature applications do configurations (e.g Elastic, Neo4J, etc); and is also fit for containerized applications.\n\n------------\n**With Only with two lines of code, and zero setting up** you get loading configuration from Config File, Overwrite values /or rely exclusively on Environment Variables, Expanding values using ${ENV} expressions, and validation tags.\n\n# Loading Configuration\n\u003cp align=\"center\"\u003e\n\u003cimg width=\"770\" src=\"https://user-images.githubusercontent.com/16992394/85208005-4b830780-b32d-11ea-9b41-83a3c87704e3.png\"\u003e\n\u003c/p\u003e\n\n### 1. Define Application **configurations** in a struct\n- Which *Configuro* will `Load()` the read configuration into.\n\n### 2. Setting Configuration by **Environment Variables**.\n- Value for key `database.password` can be set by setting `CONFIG_DATABASE_PASSWORD`. (`CONFIG_` default prefix can be changed)\n- If the key itself contains `_` then replace with `__` in the Environment Variable.\n- You can express **Maps** and **Lists** in Environment Variables by JSON encoding them. (e.g `CONFIG: {\"a\":123, \"b\": \"abc\"}`)\n- You can provide a `.env` file to load environment variables that are not set by the OS.\n\n### 3. Setting Configuration by Configuration File.\n- Defaults to `config.yml`; name and extension can be configured.\n- Supported extensions are `.yml`, `.yaml`, `.json`, and `.toml`.\n\n### 4. Support Environment Variables Expanding.\n- Configuration Values can have ${ENV|default} expression that will be expanded at loading time.\n- Example `host: www.example.com:%{PORT|3306}` with `3306` being the default value if env ${PORT} is not set).\n\n### 5. Validate Loaded Values\n- Configuro can validate structs recursively using [Validation Tags](https://godoc.org/github.com/go-playground/validator).\n- By Implementing `Validatable` Interface `Validate() error`.\n\n#### Notes\n- 📣 Values' precedence is `OS EnvVar` \u003e `.env EnvVars` \u003e `Config File` \u003e `Value set in Struct before loading.`\n\n\n-------------------------------------------------------------------------\n\n# Install\n``` bash\ngo get github.com/sherifabdlnaby/configuro\n```\n``` go\nimport \"github.com/sherifabdlnaby/configuro\"\n```\n\n# Usage\n\n### 1. Define You Config Struct.\nThis is the struct you're going to use to retrieve your config values in-code.\n```go\ntype Config struct {\n    Database struct {\n        Host     string\n        Port     int\n    }\n    Logging struct {\n        Level  string\n        LineFormat string `config:\"line_format\"`\n    }\n}\n```\n\n- Nested fields accessed with `.` (e.g `Database.Host` )\n- Use `config` tag to change field name if you want it to be different from the Struct field name.\n- All [mapstructure](https://github.com/mitchellh/mapstructure) tags apply to `config` tag for unmarshalling.\n- Fields must be public to be accessible by Configuro.\n\n### 2. Create and Configure the `Configuro.Config` object.\n\n```go\n    // Create Configuro Object with supplied options (explained below)\n    config, err := configuro.NewConfig( opts ...configuro.ConfigOption )\n\n    // Create our Config Struct\n    configStruct := \u0026Config{ /*put defaults config here*/ }\n\n    // Load values in our struct\n    err = config.Load(configStruct)\n```\n\n- Create Configuro Object Passing to the constructor `opts ...configuro.ConfigOption` which is explained in the below sections.\n- This should happen as early as possible in the application.\n\n### 3. Loading from Environment Variables\n\n- Values found in Environment Variables take precedence over values found in config file.\n- The key `database.host` can be expressed in environment variables as `CONFIG_DATABASE_HOST`.\n- If the key itself contains `_`  then replace them with `__` in the Environment Variable.\n- `CONFIG_` prefix can be configured.\n- You can express **Maps** and **Lists** in Environment Variables by JSON encoding them. (e.g `CONFIG: {\"a\":123, \"b\": \"abc\"}`)\n- You can provide a `.env` file to load environment variables that are not set by the OS. (notice that .env is loaded globally in the application scope)\n\nThe above settings can be changed upon constructing the configuro object via passing these options.\n```go\n    configuro.WithLoadFromEnvVars(EnvPrefix string)  // Enable Env loading and set Prefix.\n    configuro.WithoutLoadFromEnvVars()               // Disable Env Loading Entirely\n    configuro.WithLoadDotEnv(envDotFilePath string)  // Enable loading .env into Environment Variables\n    configuro.WithoutLoadDotEnv()                    // Disable loading .env\n```\n\n### 4. Loading from Configuration Files\n- Upon setting up you will declare the config `filepath`.\n    - Default `filename`  =\u003e \"config.yml\"\n- Supported formats are `Yaml`, `Json`, and `Toml`.\n- Config file directory can be overloaded with a defined Environment Variable.\n    - Default: `CONFIG_DIR`.\n- If file **was not found** Configuro won't raise an error unless configured too. This is you can rely 100% on Environment Variables.\n\nThe above settings can be changed upon constructing the configuro object via passing these options.\n```go\n    configuro.WithLoadFromConfigFile(Filepath string, ErrIfFileNotFound bool)    // Enable Config File Load\n    configuro.WithoutLoadFromConfigFile()                                        // Disable Config File Load\n    configuro.WithEnvConfigPathOverload(configFilepathENV string)                // Enable Overloading Path with ENV var.\n    configuro.WithoutEnvConfigPathOverload()                                     // Disable Overloading Path with ENV var.\n```\n\n### 5. Expanding Environment Variables in Config\n\n- `${ENV}` and `${ENV|default}` expressions are evaluated and expanded if the Environment Variable is set or with the default value if defined, otherwise it leaves it as it is.\n```\nconfig:\n    database:\n        host: xyz:${PORT:3306}\n        username: admin\n        password: ${PASSWORD}\n```\n\nThe above settings can be changed upon constructing the configuro object via passing these options.\n```go\n    configuro.WithExpandEnvVars()       // Enable Expanding\n    configuro.WithoutExpandEnvVars()    // Disable Expanding\n```\n\n### 6. Validate Struct\n\n```go\n    err := config.Validate(configStruct)\n    if err != nil {\n        return err\n    }\n````\n\n- Configuro Validate Config Structs using two methods.\n    1. Using [Validation Tags](https://godoc.org/github.com/go-playground/validator) for quick validations.\n    2. Using `Validatable` Interface that will be called on any type that implements it recursively, also on each element of a Map or a Slice.\n- Validation returns an error of type configuro.ErrValidationErrors if more than error occurred.\n- It can be configured to not recursively validate types with `Validatable` Interface. (default: recursively)\n- It can be configured to stop at the first error. (default: false)\n- It can be configured to not use Validation Tags. (default: false)\nThe above settings can be changed upon constructing the configuro object via passing these options.\n```go\n    configuro.WithValidateByTags()\n    configuro.WithoutValidateByTags()\n    configuro.WithValidateByFunc(stopOnFirstErr bool, recursive bool)\n    configuro.WithoutValidateByFunc()\n```\n\n### 7. Miscellaneous\n\n- `config` and `validate` tag can be renamed using `configuro.Tag(structTag, validateTag)` construction option.\n\n# Built on top of\n- [spf13/viper](https://github.com/spf13/viper)\n- [mitchellh/mapstructure](github.com/mitchellh/mapstructure)\n- [go-playground/validator](https://github.com/go-playground/validator)\n- [joho/godotenv](https://github.com/joho/godotenv)\n\n# License\n[MIT License](https://raw.githubusercontent.com/sherifabdlnaby/configuro/master/LICENSE)\nCopyright (c) 2020 Sherif Abdel-Naby\n\n# Contribution\n\nPR(s) are Open and Welcomed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsherifabdlnaby%2Fconfiguro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsherifabdlnaby%2Fconfiguro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsherifabdlnaby%2Fconfiguro/lists"}