Getting Started with confkit

Install confkit and load your first configuration in 5 minutes.

Installation

terminal
go get github.com/MimoJanra/confkit@latest

Requirements: Go 1.25.0 or later

Optional Cloud Modules

Cloud integrations are separate modules — install only what you need:

terminal
go get github.com/MimoJanra/confkit/vault@latest      # HashiCorp Vault
go get github.com/MimoJanra/confkit/aws@latest        # AWS SSM + Secrets Manager
go get github.com/MimoJanra/confkit/k8s@latest        # Kubernetes ConfigMap
go get github.com/MimoJanra/confkit/consul@latest     # Consul KV
go get github.com/MimoJanra/confkit/etcd@latest       # etcd v3
go get github.com/MimoJanra/confkit/prometheus@latest # Prometheus metrics
go get github.com/MimoJanra/confkit/otel@latest       # OpenTelemetry tracing

Your First Config

Step 1: Define Your Config

Create a struct with tags describing where values come from:

main.go
package main

import (
    "log"
    "github.com/MimoJanra/confkit"
)

type Config struct {
    // Load from PORT env var, default to 8080
    Port int `env:"PORT" default:"8080" validate:"min=1,max=65535"`

    // Load from DATABASE_URL env var, required
    DatabaseURL string `env:"DATABASE_URL" validate:"required" secret:"true"`

    // Load from LOG_LEVEL, with default
    LogLevel string `env:"LOG_LEVEL" default:"info"`
}

Step 2: Load and Use

func main() {
    cfg, err := confkit.Load[Config](
        confkit.FromEnv(),
    )
    if err != nil {
        log.Fatal(confkit.Explain(err))
    }

    // cfg is fully typed and validated
    log.Printf("Starting server on port %d\n", cfg.Port)
}

Step 3: Set Environment Variables and Run

terminal
export PORT=3000
export DATABASE_URL="postgres://user:pass@localhost/db"
export LOG_LEVEL="debug"

go run main.go
# Output: Starting server on port 3000

Using Configuration Files

Load from YAML, JSON, or TOML files:

cfg, err := confkit.Load[Config](
    confkit.FromEnv(),                 // env vars take priority
    confkit.FromYAML("config.yaml"),   // file provides fallback values
)

config.yaml:

config.yaml
port: 3000
databaseURL: postgres://localhost/db
logLevel: debug

Validation

confkit validates configuration at load time:

type Config struct {
    Port int `validate:"min=1,max=65535"`
    Count int `validate:"min=0"`
    Status string `validate:"oneof=active,inactive,pending"`
}

Error on validation failure:

Invalid configuration:

  Port
    error: must be between 1 and 65535
    got: 99999
    source: env (PORT)

  Status
    error: must be one of: active, inactive, pending
    got: unknown
    source: yaml (config.yaml)

Supported Types

confkit supports a wide range of types out of the box:

type Config struct {
    // Primitives
    Port     int    `env:"PORT"`
    Enabled  bool   `env:"ENABLED"`
    Name     string `env:"NAME"`
    Factor   float64 `env:"FACTOR"`

    // Time durations (e.g., "5s", "10m", "1h30m")
    Timeout  time.Duration `env:"TIMEOUT" default:"30s"`

    // Collections
    AllowedHosts []string `env:"ALLOWED_HOSTS"` // comma-separated
}

Supported types:

  • string, int, int8–int64, uint, uint8–uint64
  • float32, float64
  • bool (accepts: true/1/yes/on or false/0/no/off)
  • time.Duration (Go duration format: "5s", "10m", "1h30m")
  • time.Time (RFC3339 format: "2026-01-01T00:00:00Z")
  • []string, []int (from comma-separated values)
  • map[string]string, map[string]int, etc.
  • Nested structs with prefix: tags

Secrets & Security

Mark sensitive fields with secret:"true" to redact them:

type Config struct {
    // This will be redacted in errors, logs, and dumps
    APIKey string `env:"API_KEY" validate:"required" secret:"true"`
}

In error messages:

APIKey
  error: field is required
  source: env (API_KEY=***)

Multiple Sources & Precedence

Sources use first-wins semantics: the first source that provides a value for a field wins. List your highest-priority source first.

cfg, err := confkit.Load[Config](
    confkit.FromEnv(),                    // highest priority — runtime overrides
    confkit.FromYAML("config.yaml"),      // fallback
    confkit.FromYAML("defaults.yaml"),    // base defaults
)

Real-World Examples

Check out the examples directory for complete, production-ready examples:

  • Web Service — Typical API with database, cache, logging
  • Microservice — Enterprise setup with PostgreSQL, Redis, RabbitMQ, observability
  • CLI Tool — Command-line tool with flags and file processing
  • Cloud-Native — Kubernetes + AWS + Vault integration with health checks and mTLS
  • Full Setup — Schema generation and comprehensive feature demo

Each example includes complete struct definitions, multiple configuration sources, and comprehensive test suites.