configurator

README

Ridiculously simple application configuration built on top of Viper.

What is Configurator?

Configurator is an application configuration solution built on top of Viper. It was designed to be as easy to use as possible. Since Configurator is built on top of Viper it supports:

• setting defaults
• reading from JSON, TOML, YAML and HCL config files
• reading from environment variables
• reading from command line flags
• setting explicit values

Configurator does not currently support the following Viper features:

• live watching and re-reading of config files (optional)
• reading from remote config systems (etcd or Consul), and watching changes
• reading from buffer

NOTE: Full Viper support is planned in future releases.

Why Configurator?

Viper is awesome and has seen widespread use in many popular Go packages. The goal of Configurator was to make Viper easier to use.

Every application needs some form of configuration and Viper and Configurator make ingesting configuration data easy no matter what the source. If you haven't familiarized yourself what Viper is, please do so.

Since configurator is built on top of Viper the same source precedence are applicable:

• Overrides, or setting the config struct field directly.
• Flags - note that github.com/spf13/pflag is used in lieu of the standard flag package
• Environment variables
• Configuration file values
• Default values

Usage

There are two ways of using Configurator. You can embed configurator.Config into your configuration struct or call configurator.Load(&yourStruct) directly. Whichever method you pick Configurator requires you to annotate your struct with the configuration sources like so:

type AppConfig struct {
	configurator.Config

	Secret      string `env:"APP_SECRET" file:"secret flag:"secret" default:"asecretvalue"`
	Port        string `env:"APP_PORT" file:"port" flag:"port" default:"3000"`
	Environment string `env:"APP_ENV" file:"env" flag:"env" default:"dev"`
}

Embedded configurator.Config

import (
	"fmt"
	"log"

	"github.com/illyabusigin/configurator"
)

type AppConfig struct {
	configurator.Config

	Secret      string `env:"APP_SECRET" file:"secret flag:"secret" default:"asecretvalue"`
	Port        string `env:"APP_PORT" file:"port" flag:"port" default:"3000"`
	Environment string `env:"APP_ENV" file:"env" flag:"env" default:"dev"`
}

var Config AppConfig

func main() {
	Config = AppConfig{}
	Config.FileName = "config"
	Config.FilePaths = []string{
		".",
	}
	
	err := Config.Load(& Config)
	
	if err != nil {
		// Always handle your errors
		log.Fatalf("Unable to load application configuration! Error: %s", err.Error())
	}
}

Load Configuration Directly

import (
	"fmt"
	"log"

	"github.com/illyabusigin/configurator"
)

type AppConfig struct {
	Secret      string `env:"APP_SECRET" file:"secret flag:"secret" default:"asecretvalue"`
	Port        string `env:"APP_PORT" file:"port" flag:"port" default:"3000"`
	Environment string `env:"APP_ENV" file:"env" flag:"env" default:"dev"`
}

var Config AppConfig

func main() {
	Config = AppConfig{}
	configurator.FileName = "config"
	configurator.FilePaths = []string{
		".",
	}
	
	Config.Secret = "my test secret" // Because we set Secret directly prior to calling configurator.Load() it won't be overridden by configurator.Load()
	err := configurator.Load(&Config)
	
	if err != nil {
		// Always handle your errors
		log.Fatalf("Unable to load application configuration! Error: %s", err.Error())
	}
}

Bugs & Feature Requests

There is no support offered with this component. If you would like a feature or find a bug, please submit a feature request through the GitHub issue tracker.

Pull-requests for bug-fixes and features are welcome!

Attribution

Component	Description	License
viper	Go configuration with fangs	MIT
pflag	Drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags.	MIT

Documentation

Overview

Package configurator implements simple configuration built on top of Viper.

It aims to make application configuration as easy as possible. This is accomplish by allowing you to annotate your struct with env, file, flag, default annotations that will tell Viper where to where to look for configuration values. Since configurator is built on top of Viper the same source precedence is applicable.

The priority of config sources is the following: 1. Overrides, or setting the config struct field directly. 2. Flags - note that github.com/spf13/pflag is used in lieu of the standard flag package. 3. Environment variables. 4. Configuration file values. 5. Default values.

NOTE: Viper key/value store and/or watching config sources is not yet supported.

Use of this source code is governed by an MIT-style license that can be found in the LICENSE file.

Index

• Variables
• func Load(structRef interface{}) error
• func SetFileName(fileName string)
• func SetFilePaths(filePaths []string)
• type Config
  • func (c *Config) Load(structRef interface{}) error

Variables

var (
	// ErrValueNotStruct is returned when value passed to config.Load() is not a struct.
	ErrValueNotStruct = errors.New("Value does not appear to be a struct!")

	// ErrValueNotStructPointer is returned when value passed to config.Load() is not a pointer to a struct.
	ErrValueNotStructPointer = errors.New("Value passed was not a struct pointer!")
)

Functions

func Load

func Load(structRef interface{}) error

Load attempts to populate the struct with configuration values. The value passed to load must be a struct reference or an error will be returned.

func SetFileName

func SetFileName(fileName string)

SetFileName specifies the name of the configuration file without any extensions.

func SetFilePaths

func SetFilePaths(filePaths []string)

SetFilePaths specifies the array of configuration file paths to search for the configuration file.

Types

type Config

type Config struct {
	// FileName is the name of the configuration file without any extensions.
	FileName string

	// FilePaths is an array of configuration file paths to search for the configuration file.
	FilePaths []string
	// contains filtered or unexported fields
}

Config is a convenience configuration struct built on top of Viper. You use Config by annotating your configuration struct with env, flag, file, and default tags which will be parsed by Config. You can either embed Configurator.Config in your struct or reference configurator.Load() directly. The priority of the sources is the same Viper: 1. overrides 2. flags 3. env. variables 4. config file 5. defaults

For example, if you embedded configurator.Config in your struct and configured it like so:

 type AppConfig struct {
	configurator.Config
	Secret      string `file:"secret" env:"APP_SECRET" flag:"secret" default:"abc123xyz"`
	User        string `file:"user" env:"APP_USER" flag:"user" default:"root"`
	Environment string `file:"env" env:"APP_ENV" flag:"env" default:"dev"`
  }

Assuming your source values were the following:

 File : {
	"user": "test_user"
	"secret": "defaultsecret"
 }
 Env : {
 	"APP_SECRET": "somesecretkey"
 }

This is how you would load the configuration:

 func loadConfig() {
	config := AppConfig{}
	err := config.Load(&config)

	if err != nil {
		// Always handle your errors
		log.Fatalf("Unable to load application configuration! Error: %s", err.Error())
	}

	fmt.Println("config.Secret =", config.Secret)           // somesecretkey, from env
	fmt.Println("config.User =", config.User)               // test_user, from file
	fmt.Println("config.Environment =", config.Environment) // dev, from defaults
 }

func (*Config) Load

func (c *Config) Load(structRef interface{}) error

Load attempts to populate the struct with configuration values. The value passed to load must be a struct reference or an error will be returned.