• Stars
    star
    89
  • Rank 372,233 (Top 8 %)
  • Language
    Go
  • License
    MIT License
  • Created over 4 years ago
  • Updated about 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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



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.

More Repositories

1

elastdocker

🐳 Elastic Stack (ELK) v8+ on Docker with Compose. Pre-configured out of the box to enable Logging, Metrics, APM, Alerting, ML, and SIEM features. Up with a Single Command.
Dockerfile
1,625
star
2

kubephp

🐳 Production Grade, Rootless, and Optimized PHP Container Image Template for Cloud-Native Deployments and Kubernetes.
Shell
448
star
3

gpool

gpool - a generic context-aware resizable goroutines pool to bound concurrency based on semaphore.
Go
87
star
4

sched

In-process Go Job Scheduler. Supports Fixed, Timely, and Cron Expression Intervals. Instrument and Expose Scheduler's Job Metrics.
Go
57
star
5

rubban

Kibana Automatic Index Pattern Discovery and Other Elastic Stack Curating Tasks
Go
53
star
6

Golang-study-notes

This is my study notes for Golang. It is a quick intro/guide to start with golang if you have prior programming experience. 📝💨
Go
40
star
7

Valley-eCommerce-prototype

An eCommerce website prototype with a layered architecture and MVC using Spring Boot v1.2, Spring Security, Hibernate, and Apache Lucene for full-text searching. for front-end: Bootstrap, Typeahead.js and Graph.js using Thymeleaf as RE.
Java
31
star
8

Ciro

MVC PHP Framework to kickstart personal projects. Designed to be simple and lightweight. Demonstrate core building blocks for a PHP Framework.
PHP
23
star
9

medium-elastic-stack

Code used for Medium Article
Shell
12
star
10

Vector-Quantization-LBG-Image-Compression

A Java program that implments Vector Quantization LBG Algorithm on greyscale RAW images, user determines the compression level.
Java
6
star
11

prism

Image Processing Engine built using GO
Go
3
star
12

Lossless-Text-Compression-App

A Java program that implements (4) four lossless text compression techniques for ASCII Text and compares compression ratio.
Java
3
star
13

semaphore

A fork of golang/x/sync/semaphore that is also resizable in runtime.
Go
3
star
14

Algorithms-Assignments

C++
2
star
15

awsso

A small ad-hoc -very personal- script that wraps AWS SSO and aws-sso-util for my shell luxury ✨
Shell
2
star
16

Algorithms-Data-Structures

An educational collection of self-implemented popular algorithms and data-structures using C++.
C++
1
star
17

sherifabdlnaby

1
star
18

HTTPServe

A very basic HTTP Server using net package TCP listener for the sole purpose of printing a Hello World on a browser. 💻🌍
Go
1
star
19

Cafe-Simulator-Multithreading-Java

A Java program that simulates a Cafe customers entering, waiting in queue, sitting, eating and leaving. The program is an application of multi-threading using Java.
Java
1
star
20

ExpressHR

A small web-app to experiment with NodeJS & MongoDB
JavaScript
1
star
21

File-Structures-Organization

A Collection of personal applications that utilizes File-Structures and Organization concepts using C++.
C++
1
star