An opinionated configuration loading framework for Containerized and Cloud-Native applications.

Overview



Opinionated configuration loading framework for Containerized and 12-Factor compliant applications.

Read configurations from Environment Variables, and/or Configuration Files. With support to Environment Variables Expanding and Validation Methods.

Mentioned in Awesome Go Go Doc Go Version Coverage Status Go Report GitHub license

Introduction

Configuro 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.

The method defined by Configuro allow you to implement 12-Factor's Config and it mimics how many mature applications do configurations (e.g Elastic, Neo4J, etc); and is also fit for containerized applications.


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.

Loading Configuration

1. Define Application configurations in a struct

  • Which Configuro will Load() the read configuration into.

2. Setting Configuration by Environment Variables.

  • Value for key database.password can be set by setting CONFIG_DATABASE_PASSWORD. (CONFIG_ default prefix can be changed)
  • If the key itself contains _ then replace with __ in the Environment Variable.
  • You can express Maps and Lists in Environment Variables by JSON encoding them. (e.g CONFIG: {"a":123, "b": "abc"})
  • You can provide a .env file to load environment variables that are not set by the OS.

3. Setting Configuration by Configuration File.

  • Defaults to config.yml; name and extension can be configured.
  • Supported extensions are .yml, .yaml, .json, and .toml.

4. Support Environment Variables Expanding.

  • Configuration Values can have ${ENV|default} expression that will be expanded at loading time.
  • Example host: www.example.com:%{PORT|3306} with 3306 being the default value if env ${PORT} is not set).

5. Validate Loaded Values

  • Configuro can validate structs recursively using Validation Tags.
  • By Implementing Validatable Interface Validate() error.

Notes

  • 📣 Values' precedence is OS EnvVar > .env EnvVars > Config File > Value set in Struct before loading.

Install

go get github.com/sherifabdlnaby/configuro
import "github.com/sherifabdlnaby/configuro"

Usage

1. Define You Config Struct.

This is the struct you're going to use to retrieve your config values in-code.

type Config struct {
    Database struct {
        Host     string
        Port     int
    }
    Logging struct {
        Level  string
        LineFormat string `config:"line_format"`
    }
}
  • Nested fields accessed with . (e.g Database.Host )
  • Use config tag to change field name if you want it to be different from the Struct field name.
  • All mapstructure tags apply to config tag for unmarshalling.
  • Fields must be public to be accessible by Configuro.

2. Create and Configure the Configuro.Config object.

    // Create Configuro Object with supplied options (explained below)
    config, err := configuro.NewConfig( opts ...configuro.ConfigOption )

    // Create our Config Struct
    configStruct := &Config{ /*put defaults config here*/ }

    // Load values in our struct
    err = config.Load(configStruct)
  • Create Configuro Object Passing to the constructor opts ...configuro.ConfigOption which is explained in the below sections.
  • This should happen as early as possible in the application.

3. Loading from Environment Variables

  • Values found in Environment Variables take precedence over values found in config file.
  • The key database.host can be expressed in environment variables as CONFIG_DATABASE_HOST.
  • If the key itself contains _ then replace them with __ in the Environment Variable.
  • CONFIG_ prefix can be configured.
  • You can express Maps and Lists in Environment Variables by JSON encoding them. (e.g CONFIG: {"a":123, "b": "abc"})
  • 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)

The above settings can be changed upon constructing the configuro object via passing these options.

    configuro.WithLoadFromEnvVars(EnvPrefix string)  // Enable Env loading and set Prefix.
    configuro.WithoutLoadFromEnvVars()               // Disable Env Loading Entirely
    configuro.WithLoadDotEnv(envDotFilePath string)  // Enable loading .env into Environment Variables
    configuro.WithoutLoadDotEnv()                    // Disable loading .env

4. Loading from Configuration Files

  • Upon setting up you will declare the config filepath.
    • Default filename => "config.yml"
  • Supported formats are Yaml, Json, and Toml.
  • Config file directory can be overloaded with a defined Environment Variable.
    • Default: CONFIG_DIR.
  • If file was not found Configuro won't raise an error unless configured too. This is you can rely 100% on Environment Variables.

The above settings can be changed upon constructing the configuro object via passing these options.

    configuro.WithLoadFromConfigFile(Filepath string, ErrIfFileNotFound bool)    // Enable Config File Load
    configuro.WithoutLoadFromConfigFile()                                        // Disable Config File Load
    configuro.WithEnvConfigPathOverload(configFilepathENV string)                // Enable Overloading Path with ENV var.
    configuro.WithoutEnvConfigPathOverload()                                     // Disable Overloading Path with ENV var.

5. Expanding Environment Variables in Config

  • ${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.
config:
    database:
        host: xyz:${PORT:3306}
        username: admin
        password: ${PASSWORD}

The above settings can be changed upon constructing the configuro object via passing these options.

    configuro.WithExpandEnvVars()       // Enable Expanding
    configuro.WithoutExpandEnvVars()    // Disable Expanding

6. Validate Struct

    err := config.Validate(configStruct)
    if err != nil {
        return err
    }
  • Configuro Validate Config Structs using two methods.
    1. Using Validation Tags for quick validations.
    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.
  • Validation returns an error of type configuro.ErrValidationErrors if more than error occurred.
  • It can be configured to not recursively validate types with Validatable Interface. (default: recursively)
  • It can be configured to stop at the first error. (default: false)
  • It can be configured to not use Validation Tags. (default: false) The above settings can be changed upon constructing the configuro object via passing these options.
    configuro.WithValidateByTags()
    configuro.WithoutValidateByTags()
    configuro.WithValidateByFunc(stopOnFirstErr bool, recursive bool)
    configuro.WithoutValidateByFunc()

7. Miscellaneous

  • config and validate tag can be renamed using configuro.Tag(structTag, validateTag) construction option.

Built on top of

License

MIT License Copyright (c) 2020 Sherif Abdel-Naby

Contribution

PR(s) are Open and Welcomed.

Comments
  • feat: add symbols in expandEnvVariablesWithDefaults regexp

    feat: add symbols in expandEnvVariablesWithDefaults regexp

    (Thanks for sending a pull request! Please make sure you click the link above to view the contribution guidelines, then fill out the blanks below.)

    What does this implement/fix? Explain your changes.

    Improve expandEnvVariablesWithDefaults func in order to being able take default values strings that contains ':' (colon) and ',' (comma) symbols. In my case I need to add to default value host addresses in format like host1:3333,host1:2222,host3,4477

    opened by sergazyyev 4
  • Add change key delimiter option

    Add change key delimiter option

    What does this implement/fix? Explain your changes.

    Add an option for changing key delimiter

    Does this close any currently open issues?

    No

    Any relevant logs, error output, etc?

    No

    Any other comments?

    No

    Where has this been tested?

    Tested by unit test function

    opened by asaevich 3
  • A non-existant config file should not be an error

    A non-existant config file should not be an error

    It should be optional to actually have a config file - you might be specifying everything as environment variables

    https://github.com/sherifabdlnaby/configuro/blob/a580de8cd5c11380db8453e78212578ca2bad673/load.go#L21

    viper has example code on how to ignore it:

    https://github.com/spf13/viper#reading-config-files

    opened by tevansuk 3
  • add load config subsecion by key

    add load config subsecion by key

    (Thanks for sending a pull request! Please make sure you click the link above to view the contribution guidelines, then fill out the blanks below.)

    What does this implement/fix? Explain your changes.

    add load config with key

    Does this close any currently open issues?

    Any relevant logs, error output, etc?

    (If it’s long, please paste to https://ghostbin.com/ and insert the link here.)

    Any other comments?

    Where has this been tested?

    opened by lorentz-wu 2
  • Fix typo in pathErr handling

    Fix typo in pathErr handling

    (Thanks for sending a pull request! Please make sure you click the link above to view the contribution guidelines, then fill out the blanks below.)

    What does this implement/fix? Explain your changes.

    Just a type fix

    Does this close any currently open issues?

    No

    Any relevant logs, error output, etc?

    No

    Any other comments?

    No

    Where has this been tested?

    Tested

    opened by panki 2
  • Allow config file to be missing.

    Allow config file to be missing.

    What does this implement/fix? Explain your changes.

    Allows config file to be missing, and still load correctly.

    Does this close any currently open issues?

    Closes #2

    opened by tevansuk 2
Releases(v0.0.3)
  • v0.0.3(Sep 26, 2022)

    What's Changed

    • Fix typo in pathErr handling by @panki in https://github.com/sherifabdlnaby/configuro/pull/4
    • add load config subsecion by key by @lorentz-wu in https://github.com/sherifabdlnaby/configuro/pull/5
    • Add change key delimiter option by @asaevich in https://github.com/sherifabdlnaby/configuro/pull/6
    • feat: add symbols in expandEnvVariablesWithDefaults regexp by @sergazyyev in https://github.com/sherifabdlnaby/configuro/pull/7

    New Contributors

    • @panki made their first contribution in https://github.com/sherifabdlnaby/configuro/pull/4
    • @lorentz-wu made their first contribution in https://github.com/sherifabdlnaby/configuro/pull/5
    • @asaevich made their first contribution in https://github.com/sherifabdlnaby/configuro/pull/6
    • @sergazyyev made their first contribution in https://github.com/sherifabdlnaby/configuro/pull/7

    Full Changelog: https://github.com/sherifabdlnaby/configuro/compare/v0.0.2...v0.0.3

    Source code(tar.gz)
    Source code(zip)
Owner
Sherif Abdel-Naby
Software Engineer; Loves anything that scales(And Go)!
Sherif Abdel-Naby
Simple, useful and opinionated config loader.

aconfig Simple, useful and opinionated config loader. Rationale There are many solutions regarding configuration loading in Go. I was looking for a si

cristaltech 415 Nov 27, 2022
A configuration management framework written in Go

Viaduct A configuration management framework written in Go. The framework allows you to write configuration in plain Go, compiled and distributed as a

Laura Martin 8 Nov 19, 2022
goconfig uses a struct as input and populates the fields of this struct with parameters from command line, environment variables and configuration file.

goconfig goconfig uses a struct as input and populates the fields of this struct with parameters from command line, environment variables and configur

Go Sidekick 1 Sep 26, 2022
✨Clean and minimalistic environment configuration reader for Golang

Clean Env Minimalistic configuration reader Overview This is a simple configuration reading tool. It just does the following: reads and parses configu

Ilya Kaznacheev 791 Nov 25, 2022
go-up! A simple configuration library with recursive placeholders resolution and no magic.

go-up! A simple configuration library with placeholders resolution and no magic. go-up provides a simple way to configure an application from multiple

Francesco 38 Sep 26, 2022
Harvest configuration, watch and notify subscriber

Harvester Harvester is a configuration library which helps setting up and monitoring configuration values in order to dynamically reconfigure your app

Beat Labs 122 Nov 16, 2022
🛠 A configuration library for Go that parses environment variables, JSON files, and reloads automatically on SIGHUP

config A small configuration library for Go that parses environment variables, JSON files, and reloads automatically on SIGHUP. Example func main() {

Josh Betz 214 Oct 15, 2022
Manage local application configuration files using templates and data from etcd or consul

confd confd is a lightweight configuration management tool focused on: keeping local configuration files up-to-date using data stored in etcd, consul,

Kelsey Hightower 8k Nov 24, 2022
A flexible and composable configuration library for Go that doesn't suck

croconf A flexible and composable configuration library for Go that doesn't suck Ned's spec for Go configuration which doesn't suck: Fully testable: t

k6 15 Nov 17, 2022
A flexible and composable configuration library for Go that doesn't suck

croconf A flexible and composable configuration library for Go Why? We know that there are plenty of other Go configuration and CLI libraries out ther

Grafana Labs 15 Nov 17, 2022
Golang library for reading properties from configuration files in JSON and YAML format or from environment variables.

go-config Golang library for reading properties from configuration files in JSON and YAML format or from environment variables. Usage Create config in

null 3 Aug 22, 2022
Noel 2 Jul 4, 2022
12 factor configuration as a typesafe struct in as little as two function calls

Config Manage your application config as a typesafe struct in as little as two function calls. type MyConfig struct { DatabaseUrl string `config:"DAT

Jeremy Loy 319 Nov 16, 2022
JSON or YAML configuration wrapper with convenient access methods.

Config Package config provides convenient access methods to configuration stored as JSON or YAML. This is a fork of the original version. This version

Oleg Lebedev 259 Nov 17, 2022
Configure is a Go package that gives you easy configuration of your project through redundancy

Configure Configure is a Go package that gives you easy configuration of your project through redundancy. It has an API inspired by negroni and the fl

Harrison Shoebridge 57 Sep 26, 2022
Load configuration in cascade from multiple backends into a struct

Confita is a library that loads configuration from multiple backends and stores it in a struct. Supported backends Environment variables JSON files Ya

Heetch 456 Nov 10, 2022
Small library to read your configuration from environment variables

envconfig envconfig is a library which allows you to parse your configuration from environment variables and fill an arbitrary struct. See the example

Vincent Rischmann 229 Nov 3, 2022
A minimalist Go configuration library

fig fig is a tiny library for loading an application's config file and its environment into a Go struct. Individual fields can have default values def

null 243 Nov 11, 2022
Go configuration made easy!

gofigure Go configuration made easy! Just define a struct and call Gofigure Supports strings, ints/uints/floats, slices and nested structs Supports en

Ian Kent 65 Sep 26, 2022