README
¶
About envcfg
envcfg is a package to retrieve configuration settings from the environment,
in adherence with 12-factor app principles.
Installing
Install in the usual Go fashion:
$ go get -u github.com/kenshaw/envcfg
Using
envcfg can be used similarly to the following:
// examples/main.go
package main
import (
"fmt"
"log"
"net/http"
"github.com/kenshaw/envcfg"
)
func main() {
// load config from the default APP_CONFIG environment variable
config, err := envcfg.New()
if err != nil {
log.Fatal(err)
}
// load additional config from SOME_OTHER_VAR environment variable
config2, err := envcfg.New(
envcfg.VarName("SOME_OTHER_VAR"),
)
if err != nil {
log.Fatal(err)
}
config2 = config2
// read a config key
val := config.GetKey("mysection.mykeyname")
log.Printf("> val: %s", val)
// create a http.Server with a host, port, and TLS based on config pulled
// from environment
s := &http.Server{
Addr: fmt.Sprintf("%s:%d", config.Host(), config.Port()),
TLSConfig: config.TLS(nil),
}
log.Fatal(s.ListenAndServe())
}
Please see the GoDoc listing for a full API listing.
Environment Variables
By default, envcfg loads configuration data from the base64-encoded
environment variable APP_CONFIG, and expects a git config
style configuration file of sections, subsections, and keys.
Config files and key data
Configuration data is stored in git config style configuration files, and uses the github.com/kenshaw/ini package for parsing configuration data.
The below is the examples/sample.config:
# examples/sample.config
[runtime]
environment="$ENV||production" ; production / development / etc.
[server]
host="$HOST||example.com" ; hostname
port="$PORT||8443" ; port
certs="$CERTS||./env/certs" ; certificate directory cache
certProvider="dns:godo:<domain>:<email>:<token>" ; certificate provider
[google]
creds="$GOOGLECREDS||env/gsa.json||file" ; "file" encoded gsa credentials loaded from disk,
; relative to the current working directory
[service "something"]
key="$NAME||subdir/myfile||relfile" ; "relfile" encoded file will be loaded relative to the original config file
; for example, if the config file was on disk at /etc/myapp then
; the /etc/myapp/subdir/myfile value would be loaded
[example]
b64value="$B64VALUE||e30K||base64" ; "base64" encoded value
Certificate Providers
The following certificate providers are supported for server.certProvider:
| Name | Type | Example |
|---|---|---|
auto |
LetsEncrypt TLS-SNI-01 | auto |
disk |
Certificate on disk | disk:/path/to/cert.pem:/path/to/key.pem |
dns |
LetsEncrypt DNS-01 | dns:clouddns:mydomain.com:ken@example.com:my-managed-zone-name:/path/to/credentials.json |
LetsEncrypt DNS-01 Provider
DNS certificate provider strings have a general form of dns:<type>:<domain>:<email>:....
| Type | DNS Provider | Parameters |
|---|---|---|
godo |
DigitalOcean DNS | <type>:<domain>:<email>:<token> |
clouddns |
Google Cloud DNS | <type>:<domain>:<email>:<managed-zone-name>:/path/to/credentials.json |
Documentation
¶
Overview ¶
Package envcfg provides a common way to load configuration variables from the system environment or from based on initial configuration values stored on disk or in a base64 encoded environment variable.
Index ¶
- Constants
- type Envcfg
- func (ec *Envcfg) Env() string
- func (ec *Envcfg) GetBool(key string) bool
- func (ec *Envcfg) GetDuration(key string) time.Duration
- func (ec *Envcfg) GetFloat(key string, bitSize int) float64
- func (ec *Envcfg) GetInt(key string) int
- func (ec *Envcfg) GetInt64(key string, base, bitSize int) int64
- func (ec *Envcfg) GetKey(key string) string
- func (ec *Envcfg) GetString(key string) string
- func (ec *Envcfg) GetUint64(key string, base, bitSize int) uint64
- func (ec *Envcfg) Host() string
- func (ec *Envcfg) MustInt(key string) int
- func (ec *Envcfg) MustKey(key string) string
- func (ec *Envcfg) Port() int
- func (ec *Envcfg) PortString() string
- func (ec *Envcfg) TLS() *tls.Config
- type Option
- func CertDelayKey(key string) Option
- func CertPathKey(key string) Option
- func CertWaitKey(key string) Option
- func ConfigFile(path string) Option
- func EnvKey(key string) Option
- func Errorf(f func(string, ...interface{})) Option
- func HostKey(key string) Option
- func Logf(f func(string, ...interface{})) Option
- func PortKey(key string) Option
- func VarName(name string) Option
Constants ¶
const ( // DefaultVarName is the default environment variable name to load the // initial configuration data from. DefaultVarName = "APP_CONFIG" // DefaultEnvKey is the default runtime environment key. DefaultEnvKey = "runtime.environment" // DefaultHostKey is the default server hostname key. DefaultHostKey = "server.host" // DefaultPortKey is the default server port key. DefaultPortKey = "server.port" // DefaultCertPathKey is the default server certificate path key. DefaultCertPathKey = "server.certs" // DefaultCertProviderKey is the default server certificate provider key. DefaultCertProviderKey = "server.certProvider" // DefaultCertWaitKey is the default server certificate wait key. DefaultCertWaitKey = "server.certWait" // DefaultCertDelayKey is the default server certificate delay key. DefaultCertDelayKey = "server.certDelay" // DefaultConfigFile is the default file path to load the initial // configuration data from. DefaultConfigFile = "env/config" // DefaultCertPath is the default certificate caching path. DefaultCertPath = "env/certs" // DefaultEnvironment is the default environment name. DefaultEnvironment = "development" // DefaultCertWait is the default certificate provider wait duration. DefaultCertWait = 180 * time.Second // DefaultCertDelay is the default certificate provider propagation delay. DefaultCertDelay = 30 * time.Second )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Envcfg ¶
type Envcfg struct {
// contains filtered or unexported fields
}
Envcfg handles loading configuration variables from system environment variables or from an initial configuration file.
func (*Envcfg) GetBool ¶
GetBool retrieves the value for key from the environment, or the supplied configuration data, returning it as a bool.
func (*Envcfg) GetDuration ¶
GetDuration retrievses the value for key from the environment, or the supplied configuration data, returning it as a time.Duration.
func (*Envcfg) GetFloat ¶
GetFloat retrieves the value for key from the environment, or the supplied configuration data, returning it as a float64. Uses bitSize as the precision.
func (*Envcfg) GetInt ¶
GetInt retrieves the value for key from the environment, or the supplied configuration data, returning it as a int. Expects numbers to be base 10 and no larger than 32 bits.
func (*Envcfg) GetInt64 ¶
GetInt64 retrieves the value for key from the environment, or the supplied configuration data, returning it as a int64. Uses base and bitSize to parse.
func (*Envcfg) GetKey ¶
GetKey retrieves the value for the key from the environment, or from the initial supplied configuration data.
When the initial value read from the config file or the supplied app environment variable is in the form of "$NAME||<default>" or "$NAME||<default>||<encoding>". Then the value will be read from from the system environment variable $NAME. If that value is empty, then the <default> value will be returned instead. If the third, optional parameter is supplied then the environment variable value (or the default value) will be decoded using the appropriate method.
Current supported <encoding> parameters:
base64 -- value should be base64 decoded file -- value should be read from disk relfile -- value should be read from a path on disk relative to the loaded file
func (*Envcfg) GetString ¶
GetString retrieves the value for key from the environment or the supplied configuration data, returning it as a string.
NOTE: alias for GetKey.
func (*Envcfg) GetUint64 ¶
GetUint64 retrieves the value for key from the environment, or the supplied configuration data, returning it as a uint64. Uses base and bitSize to parse.
func (*Envcfg) MustInt ¶
MustInt returns the value for key (same as GetInt) but panics if the key was blank or if the value is an invalid int.
func (*Envcfg) MustKey ¶
MustKey returns the value for key (same as GetKey) but panics if the string is empty.
func (*Envcfg) PortString ¶
PortString retrieves the value for the server port key as a string.
type Option ¶
type Option func(*Envcfg)
Option is an Envcfg option.
func CertDelayKey ¶
CertDelayKey is an option that sets the server certificate delay key.
func CertPathKey ¶
CertPathKey is an option that sets the server certificate path key.
func CertWaitKey ¶
CertWaitKey is an option that sets the server certificate wait key.
func ConfigFile ¶
ConfigFile is an option that sets the file path to read data from.
Source Files