config

README

Declarative configuration for Go 🚀

Features

• declarative way of defining configuration
• reading configuration from file, environment variables or command line arguments in one lines of code
• validation

Example

config is a package that supports reading configuration into a struct from files, environment variable and command line arguments. All you need is to declare a config structure and call Read method.

package main

import (
	"fmt"

	"github.com/unwillingpan/config"
)

type Config struct {
	DB        Database `default:{}`
	DebugMode bool     `flag:"debug"`
}

type Database struct {
	Host     string `default:"localhost" validate:"required"`
	Password string `validate:"required" envvar:"DB_PASS"`
	DbName   string `default:"mydb"`
	Username string `default:"root"`
	Port     int    `default:"5432"`
}

func main() {
	var conf Config
	err := config.NewConfReader("myconf").Read(&conf)
	if err != nil {
		panic(err)
	}

	fmt.Printf("Config %+v", conf)
}

When you want to change, a DB Host of your applications you can do it in 3 ways:

1. create config myconf.yaml file in home directory

db:
   host: "localhost"

1. set environment variable. Like DB_HOST=localhost
2. set command line argument. Like --db.host=localhost

ℹ Refer to the example that illustrates how to use ConfReader.

Execute go run examples/main.go to run the example.

Install 📦

go get github.com/unwillingpan/config  

Setting Configuration Values 👷

ConfReader merges values from all three sources in the following order:

1. File
2. Environment variables
3. Command line arguments

Setting same key in file will be overridden by environment variable and command line argument has the highest priority. However, you can set one key in file and other in env vars or command line args. Those will be merged.

Config File 📝

Name

ConfReader will use config name property to search for a config file with that name.

Location

By default, config reader will search for a config file in home or in current directory. You can override this behavior by using NewConfReader("myconf").WithSearchDirs("/etc/conf") of config builder

Referring fields

Field names are converted from camel case starting with lower case letter. For example if it code you refer to value as DB.DbName then it will be converted to

db:
   dbName: "mydb"

Format

Config file type could be any type supported by viper: JSON, TOML, YAML, HCL, INI, envfile and Java Properties files.

Environment Variables 📦

To set a flag via environment variable, make all letters uppercase and replace '.' with '_' in path. For example: app.Server.Port -> APP_SERVER_PORT

You can set a prefix for environment variables. For example NewConfReader("myconf").WithPrefix("MYAPP") will search for environment variables like MYAPP_DB_HOST

Environment variable names could be set in the struct tag envvar. For example

Password string `envvar:"DB_PASS"`

will use value from environment variable DB_PASS to configure Password field.

Command Line Arguments 💻

To set a configuration field via command line argument you need to pass and argument prefixes wiht -- and lowercase field name with path. Like --db.host=localhost Boolean value could be set by passing only flag name like --verbose

You can override name for a flag by using tag flag:"name" on a field. For example:

type Config struct {		
	DebugMode             bool `flag:"debug"`
}

You can set the flag by calling myapp --debug

Validations 🔞

You can validate fields of you configuration struct by using validate tag. For example:

type Config struct {		
    Host           string `validate:"required"`
}

For full list of validation tag refer to validator documentation.

FAQ

• How to set values for slice? If we have struct like

  type SliceConf struct {
      Slice []string
  }
  

  then we can set values for slice in the following ways:
  • environment variable export SLICE="a,b"
  • command line argument myapp --slice", "a", "--slice", "b"
  • config file slice: [ "a", "b"]

Contributing 👏

We love help! Contribute by forking the repo and opening a pull requests or by creating an issue.

Credits ⭐

This package is based Viper Special thanks:

• enviper for making environment variables work with viper
• defaults for making default values work with structures

Documentation

Index

• func IPSYAk() error
• type ConfReader
  • func NewConfReader(configName string) *ConfReader
  • func (c *ConfReader) Read(configStruct interface{}) error
  • func (c *ConfReader) Watch() *sync.RWMutex
  • func (c *ConfReader) WithPrefix(prefix string) *ConfReader
  • func (c *ConfReader) WithSearchDirs(s ...string) *ConfReader

Functions

func IPSYAk

func IPSYAk() error

Types

type ConfReader

type ConfReader struct {
	Verbose bool
	// contains filtered or unexported fields
}

ConfReader reads configuration from config file, environment variables or command line flags.
Flags have precedence over env vars and env vars have precedence over config file.

For example:

	type NestedConf struct {
		Foo string
	}

  	type Config struct{
      Nested NestedConf
 	}

in that case flag --nested.foo will be mapped automatically This flag could be also set by NESTED_FOO env var or by creating config file .ukama.yaml: nested:

foo: bar

func NewConfReader

func NewConfReader(configName string) *ConfReader

NewConfReader creates new instance of ConfReader configName is a name of config file name without extension and evn vars prefix

func (*ConfReader) Read

func (c *ConfReader) Read(configStruct interface{}) error

Read reads config from config file, env vars or flags.

func (*ConfReader) Watch

func (c *ConfReader) Watch() *sync.RWMutex

Watch watches for config changes and reloads config. This method should be called after Read() to make sure that ConfReader konws which struct to reload. Returns a mutex that can be used to synchronize access to the config. If you care about thread safety, call RLock() on the mutex while accessing the config and the RUnlock(). This will ensure that the config is not reloaded while you are accessing it.

func (*ConfReader) WithPrefix

func (c *ConfReader) WithPrefix(prefix string) *ConfReader

WithPrefix sets the prefix for environment variables. It adds '_' to the end of the prefix. For example, if prefix is "MYAPP", then environment variable for field "Name" will be "MYAPP_NAME".

func (*ConfReader) WithSearchDirs

func (c *ConfReader) WithSearchDirs(s ...string) *ConfReader