gonf fills your Go structs from files, environment and flags, and checks them before your service starts.
- Typed structs: no string lookups, no casts
- Fail fast: every error at start, with file and line
- Layering: defaults, files,
.env, env and flags, each one on top - Any profiles:
dev,staging,local, combined - Explain: see where each value came from
- Env without binding:
APP_DB_URLsetsapp.db.url, typos warned - Formats: properties, JSON, YAML,
.env - Sources: files, env, flags, secret mounts, your own
- No secret logging:
****in logs, errors and docs - Expressions:
${app.db.host},${file::/run/secrets/db} - Safe reload: a broken change never goes live
- Generated docs: key reference and JSON Schema
- Extensible: own sources, formats and functions
- Library modules: packages bring their own config
- Zero dependencies: core is standard library only
go get github.com/efuturetoday/gonfDescribe your settings as a struct. default and desc are optional:
type Config struct {
Port int `default:"8080" desc:"HTTP port"`
DB struct {
Host string `default:"localhost" desc:"database host"`
URL string `desc:"connection string"`
Password gonf.Secret[string] `default:"change-me"`
}
}
var appConfig = gonf.NewMapping[Config]("app")gonf.NewMapping ties the struct to the name app: the field DB.URL
becomes the key app.db.url. Put values in config/app.properties:
app.port=8000
app.db.host=db.internal
app.db.url=postgres://${app.db.host}:5432/appLoad the configuration and read the struct in main.go:
func main() {
cfg, err := boot.Load(context.Background(), boot.WithMappings(appConfig))
if err != nil {
log.Fatal(err)
}
for _, w := range cfg.Warnings() {
log.Println("warning:", w)
}
c := appConfig.Get(cfg)
fmt.Println("port: ", c.Port)
fmt.Println("db.url: ", c.DB.URL)
fmt.Println("password:", c.DB.Password)
// go run . app.db.url
if len(os.Args) > 1 {
fmt.Println(cfg.Explain(os.Args[1]))
}
}The complete program is in examples/quickstart.
Run it from that directory:
$ go run .
port: 8000
db.url: postgres://db.internal:5432/app
password: ****
boot.Load found config/app.properties by itself. Now set a value with
an environment variable. It wins over the file:
$ APP_PORT=9000 go run .
port: 9000
db.url: postgres://db.internal:5432/app
password: ****
That is the whole idea: a struct, a file, and the environment on top.
Each example below runs against the quickstart program.
Say config/app.properties has a typo, ulr instead of url:
app.port=8000
app.db.host=db.internal
app.db.ulr=postgres://${app.db.host}:5432/appThe program stops at start and reports every problem, not only the first:
$ go run .
gonf: bind "app": 2 problems:
app.db.url: required, no value
app.db.ulr: unknown key, did you mean app.db.url? (from file:config/app.properties:3)
A wrong type is caught the same way, for example app.port=80x:
gonf: bind "app": app.port: invalid int "80x" (from file:config/app.properties:1)
The quickstart prints cfg.Explain(key) for a key given on the command
line:
$ APP_PORT=9000 go run . app.port
app.port = 9000 (env:APP_PORT)
overrides 8000 (file:config/app.properties:1)
default 8080 (main.go:30)
The first line is the value in use and where it comes from. The lines below show what it replaced, and the default from the struct tag. More in Where does a value come from?.
A profile is a named set of values for one environment. Add
config/app-dev.properties:
app.db.host=localhostand start with GONF_PROFILE=dev:
$ GONF_PROFILE=dev go run . app.db.url
port: 8000
db.url: postgres://localhost:5432/app
password: ****
app.db.url = postgres://localhost:5432/app (file:config/app.properties:3)
The profile file replaced app.db.host, and app.db.url, which refers to
it, followed. More in Profiles.
Password is a gonf.Secret[string], so it prints as **** with fmt,
JSON, slog and in Explain. Your code gets the real value when it asks
for it:
password := c.DB.Password.Value()More in Secrets.
A value can refer to another key with ${...}, as app.db.url does with
${app.db.host}. A function takes the form ${name::argument}. Read the
password from the environment variable DB_PASSWORD:
app.db.url=postgres://localhost/app
app.db.password=${env::DB_PASSWORD}$ DB_PASSWORD=s3cret go run . app.db.password
port: 8080
db.url: postgres://localhost/app
password: ****
app.db.password = **** (file:config/app.properties:2, via env)
default **** (main.go:30)
If DB_PASSWORD is not set, the start fails with a message that names the
key and the line. More in Sources.
The core has no dependencies. Everything else is a module of its own, released with the same version:
| Module | |
|---|---|
format/yaml |
YAML files: go get github.com/efuturetoday/gonf/format/yaml |
cmd/gonf |
gonf encrypt for encrypted values: go install github.com/efuturetoday/gonf/cmd/gonf@latest |
Planned: HashiCorp Vault, Azure Key Vault, Azure App Configuration, AWS SSM Parameter Store, AWS Secrets Manager, GCP Secret Manager.
- Profiles:
%dev.keys,app-dev.properties, activating profiles. - Structs: names, defaults, optional fields, lists, maps, validation, unknown keys, and converters for types of other packages.
- Secrets:
gonf.Secret[T], what gets masked, and encrypted values. - Where does a value come from?:
cfg.Explainshows the winning value, its file and line, and what it overrides;cfg.Warnings()andcfg.Sources()show what was skipped and loaded. - Configuration reference: generate a table of all keys with their environment variables, types and defaults, and a JSON Schema for editors.
- Sources and formats:
.properties, JSON, YAML,.env, the environment, flags, secret directories, expressions with functions such as what git knows, and your own Sources. - Reloading:
boot.Watchkeeps the configuration current when files change, and keeps the previous one if a change is invalid.
The API reference is on pkg.go.dev.
More programs in examples/:
examples/quickstart: the program of this pageexamples/basic: Sources, profiles and expressions, set up by handexamples/boot: loading by conventionexamples/library-module: a library that brings its own configuration, and a-config-docflagexamples/reload: a configuration that follows changes to its files
| gonf | viper | koanf | |
|---|---|---|---|
| Config | typed structs | keys by name, Unmarshal |
keys by name, Unmarshal |
| Unknown keys | error at start | ignored by default | ignored |
| Environment | matched against your structs | AutomaticEnv, BindEnv |
provider with a transform |
| Origin of a value | cfg.Explain |
no | no |
| Global state | none | a global instance by default | none |
| Dependencies | standard library | many | one module per provider |
- gonf: typed configuration, checked before the service starts.
- viper: the largest ecosystem, remote providers.
- koanf: providers and parsers assembled by hand.
Issues and pull requests are welcome. Run go vet ./...,
go test -race ./... and golangci-lint run, also in format/yaml and
cmd/gonf. Pull request titles follow
Conventional Commits; releases and
the changelog are made from them. Report vulnerabilities as
described in SECURITY.md.
The gonf logo is based on the Go gopher by Renée French, licensed under CC BY 4.0.


