Overview

This library helps applications work with configs through environment variables. It's a more opinionated and much smaller version of Viper. It assumes you're following the 12 factor app recommendations for configs and logging.

Goals

Applications generally want to do the following:

1. Define some default config values which work in development.
2. Let apps overwrite defaults with environment variables.
3. Validate the config values.
4. Log values of any config variables except for credentials.

This library's goal is to make these steps as painless as possible.

Usage

Define structs with names matching your environment variables:

type struct Config {
  Main Server
  Admin Server
  Password string
  DatabasePassword string
}

type struct Server {
  Port int
}

Set some environment variables in your shell. The names will be derived from your Struct's field names.

export MYAPP_MAIN_PORT=80
export MYAPP_ADMIN_PORT=81
export MYAPP_PASSWORD=boo
export MYAPP_DATABASE_PASSWORD=ghost

A prefix like MYAPP_ is not required, but recommended to help namespace your project's environment variables from other programs running on the system. It is defined when the variables are loaded into the struct, like so:

import (
  "github.com/fluff-shark/go-environment-configs"
)

func Parse() Config {
  // Define defaults by setting the initial struct values.
  cfg := Config{
    Main: Server{
      Port: 80
    },
    Admin: Server{
      Port: 81
    }
  }

  // Overwrite the defaults with environment variables.
  // Panic with a descriptive error message if the values don't match the types.
  configs.MustLoadWithPrefix(&cfg, "MYAPP")

  // Print the config values.
  // Anything named "password" will be logged as "<redacted>"
  configs.LogWithPrefix(&cfg, "MYAPP")
}

This library's validation only checks things it can know given the types declared on the struct. Any extra validation is on the caller, but there are some utils to help concatenate errors and normalize the error output. For example:

  cfg := Config{
    // Set defaults like above
  }

  err := configs.LoadWithPrefix(&cfg, "MYAPP")

  // Add app-specific validation errors. The library will collect these
  // alongside errors generated by LoadWithPrefix for pretty printing.
  err = configs.Ensure(err, "MYAPP_MAIN_PORT", cfg.Main.Port > 0, "must be a positive integer")

Contributing

Pull requests are welcome for bugfixes and support for types that aren't implemented yet. Otherwise please open an issue first to discuss.