viper-configuration

name	Viper Configuration
description	This skill should be used when the user asks to "setup Viper", "configuration management", "load config files", "environment variables", "Viper with Cobra", or works with application configuration in Go.
version	0.1.0

Viper Configuration

Viper is a complete configuration solution for Go applications supporting multiple formats and sources.

Core Concepts

Configuration Sources (Priority Order)

1. Explicit Set() calls
2. Command-line flags
3. Environment variables
4. Configuration files
5. Key/value store (etcd/Consul)
6. Defaults

Basic Setup

package config

import (
    "fmt"
    "github.com/spf13/viper"
    "strings"
)

var Config *viper.Viper

// Init initializes Viper configuration
func Init() error {
    Config = viper.New()

    // Set config name (without extension)
    Config.SetConfigName("config")
    Config.SetConfigType("yaml")

    // Add search paths
    Config.AddConfigPath(".")
    Config.AddConfigPath("./config")
    Config.AddConfigPath("/etc/myapp/")
    Config.AddConfigPath("$HOME/.myapp")

    // Set defaults
    setDefaults()

    // Read config file
    if err := Config.ReadInConfig(); err != nil {
        if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
            return fmt.Errorf("error reading config file: %w", err)
        }
        // Config file not found; use defaults
    }

    // Setup environment variables
    setupEnvironment()

    return nil
}

func setDefaults() {
    Config.SetDefault("server.port", "8080")
    Config.SetDefault("server.host", "0.0.0.0")
    Config.SetDefault("server.readTimeout", 30)
    Config.SetDefault("server.writeTimeout", 30)

    Config.SetDefault("database.host", "localhost")
    Config.SetDefault("database.port", 3306)
    Config.SetDefault("database.name", "myapp")
    Config.SetDefault("database.maxOpenConns", 25)
    Config.SetDefault("database.maxIdleConns", 5)

    Config.SetDefault("log.level", "info")
    Config.SetDefault("log.format", "json")
}

func setupEnvironment() {
    // Set environment prefix
    Config.SetEnvPrefix("MYAPP")
    Config.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
    Config.AutomaticEnv()
}

Configuration File Formats

YAML (config.yaml):

server:
  port: "8080"
  host: "0.0.0.0"
  readTimeout: 30
  writeTimeout: 30

database:
  host: "localhost"
  port: 3306
  user: "root"
  password: "secret"
  name: "myapp"
  sslMode: "disable"
  maxOpenConns: 25
  maxIdleConns: 5

redis:
  host: "localhost"
  port: 6379
  password: ""
  db: 0

features:
  enableCache: true
  enableMetrics: true
  rateLimit:
    enabled: true
    requestsPerSecond: 100

JSON (config.json):

{
  "server": {
    "port": "8080",
    "host": "0.0.0.0"
  },
  "database": {
    "host": "localhost",
    "port": 3306
  }
}

Reading Configuration Values

// Get string
port := Config.GetString("server.port")
host := Config.GetString("server.host")

// Get int
dbPort := Config.GetInt("database.port")
timeout := Config.GetInt("server.readTimeout")

// Get bool
cacheEnabled := Config.GetBool("features.enableCache")

// Get float64
rateLimit := Config.GetFloat64("features.rateLimit.requestsPerSecond")

// Get duration
timeout := Config.GetDuration("server.timeout") // e.g., "30s"

// Get string slice
allowedHosts := Config.GetStringSlice("server.allowedHosts")

// Get map
featureFlags := Config.GetStringMap("features")
rateLimitConfig := Config.GetStringMapString("features.rateLimit")

// Check if key exists
if Config.IsSet("database.password") {
    // Key exists
}

// Get all settings
allSettings := Config.AllSettings()

Environment Variables

// With prefix
export MYAPP_SERVER_PORT=9090
export MYAPP_DATABASE_HOST=db.example.com
export MYAPP_DATABASE_PORT=5432

// Access via Viper
port := Config.GetString("server.port")      // "9090"
host := Config.GetString("database.host")    // "db.example.com"

Bind to Struct

type ServerConfig struct {
    Port         string        `mapstructure:"port"`
    Host         string        `mapstructure:"host"`
    ReadTimeout  int           `mapstructure:"readTimeout"`
    WriteTimeout int           `mapstructure:"writeTimeout"`
}

type DatabaseConfig struct {
    Host          string `mapstructure:"host"`
    Port          int    `mapstructure:"port"`
    User          string `mapstructure:"user"`
    Password      string `mapstructure:"password"`
    Name          string `mapstructure:"name"`
    SSLMode       string `mapstructure:"sslMode"`
    MaxOpenConns  int    `mapstructure:"maxOpenConns"`
    MaxIdleConns  int    `mapstructure:"maxIdleConns"`
}

type Config struct {
    Server   ServerConfig   `mapstructure:"server"`
    Database DatabaseConfig `mapstructure:"database"`
}

var cfg Config
if err := Config.Unmarshal(&cfg); err != nil {
    return fmt.Errorf("unable to decode config: %w", err)
}

Cobra Integration

package cmd

import (
    "github.com/spf13/cobra"
    "github.com/spf13/viper"
)

var (
    cfgFile string
    rootCmd = &cobra.Command{
        Use:   "myapp",
        Short: "My application",
        Long:  `A longer description of my application`,
    }
)

func Execute() error {
    return rootCmd.Execute()
}

func init() {
    cobra.OnInitialize(initConfig)

    // Persistent flags (available to all subcommands)
    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.myapp.yaml)")
    rootCmd.PersistentFlags().StringP("server.port", "p", "8080", "Server port")
    rootCmd.PersistentFlags().String("server.host", "0.0.0.0", "Server host")
    rootCmd.PersistentFlags().String("log.level", "info", "Log level")

    // Bind flags to viper
    viper.BindPFlag("server.port", rootCmd.PersistentFlags().Lookup("server.port"))
    viper.BindPFlag("server.host", rootCmd.PersistentFlags().Lookup("server.host"))
    viper.BindPFlag("log.level", rootCmd.PersistentFlags().Lookup("log.level"))

    // Set defaults
    viper.SetDefault("server.port", "8080")
}

func initConfig() {
    if cfgFile != "" {
        viper.SetConfigFile(cfgFile)
    } else {
        home, _ := os.UserHomeDir()
        viper.AddConfigPath(home)
        viper.SetConfigName(".myapp")
    }

    viper.AutomaticEnv()
    viper.SetEnvPrefix("MYAPP")

    if err := viper.ReadInConfig(); err == nil {
        fmt.Println("Using config file:", viper.ConfigFileUsed())
    }
}

Multiple Config Files

// Load base config
viper.SetConfigName("config")
viper.AddConfigPath(".")
viper.ReadInConfig()

// Merge environment-specific config
env := viper.GetString("environment")
viper.SetConfigName("config." + env) // config.development, config.production
viper.MergeInConfig()

Configuration Validation

func ValidateConfig() error {
    required := []string{
        "database.host",
        "database.name",
        "server.port",
    }

    for _, key := range required {
        if !Config.IsSet(key) {
            return fmt.Errorf("required configuration missing: %s", key)
        }
    }

    // Validate port range
    port := Config.GetInt("server.port")
    if port < 1 || port > 65535 {
        return fmt.Errorf("invalid server port: %d", port)
    }

    return nil
}

Watching Configuration Changes

func WatchConfig() {
    Config.WatchConfig()
    Config.OnConfigChange(func(e fsnotify.Event) {
        fmt.Println("Config file changed:", e.Name)
        // Reload configuration
    })
}

Best Practices

1. Use struct tags for clean mapping
2. Set sensible defaults for all configuration
3. Use environment prefix to avoid conflicts
4. Validate configuration at startup
5. Use nested keys for organization
6. Document configuration options

Additional Resources

• references/config-patterns.md - Advanced configuration patterns
• examples/viper-cobra/ - Complete integration example