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.
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.
- Which Configuro will
Load()
the read configuration into.
- Value for key
database.password
can be set by settingCONFIG_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.
- Defaults to
config.yml
; name and extension can be configured. - Supported extensions are
.yml
,.yaml
,.json
, and.toml
.
- Configuration Values can have ${ENV|default} expression that will be expanded at loading time.
- Example
host: www.example.com:%{PORT|3306}
with3306
being the default value if env ${PORT} is not set).
- Configuro can validate structs recursively using Validation Tags.
- By Implementing
Validatable
InterfaceValidate() error
.
- 📣 Values' precedence is
OS EnvVar
>.env EnvVars
>Config File
>Value set in Struct before loading.
go get github.com/sherifabdlnaby/configuro
import "github.com/sherifabdlnaby/configuro"
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.gDatabase.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.
// 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.
- Values found in Environment Variables take precedence over values found in config file.
- The key
database.host
can be expressed in environment variables asCONFIG_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
- Upon setting up you will declare the config
filepath
.- Default
filename
=> "config.yml"
- Default
- Supported formats are
Yaml
,Json
, andToml
. - Config file directory can be overloaded with a defined Environment Variable.
- Default:
CONFIG_DIR
.
- Default:
- 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.
${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
err := config.Validate(configStruct)
if err != nil {
return err
}
- Configuro Validate Config Structs using two methods.
- Using Validation Tags for quick validations.
- 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()
config
andvalidate
tag can be renamed usingconfiguro.Tag(structTag, validateTag)
construction option.
MIT License Copyright (c) 2020 Sherif Abdel-Naby
PR(s) are Open and Welcomed.