# How to Use Viper for Configuration Management in Gorig

> Learn to master Viper for configuration management in Gorig. Discover how Gorig simplifies settings with automatic YAML loading and type-safe getters.

- Repository: [Jom/gorig](https://github.com/jom-io/gorig)
- Tags: how-to-guide
- Published: 2026-03-04

---

**Gorig centralizes all configuration handling in the `utils/cofigure` package, a thin wrapper around Viper that automatically initializes environment-aware YAML loading and exposes type-safe getters like `GetString()` and `GetBool()`.**

Gorig leverages the popular Viper configuration library through a dedicated abstraction layer to simplify application settings management. According to the `jom-io/gorig` source code, the `utils/cofigure` package encapsulates Viper's complexity, providing a consistent API for reading YAML files and environment variables while supporting runtime mode detection.

## Understanding the Viper Wrapper Architecture

The configuration system resides in [`utils/cofigure/cfg.go`](https://github.com/jom-io/gorig/blob/main/utils/cofigure/cfg.go). This file contains both the initialization logic and the public getter API. The wrapper implements a **lazy initialization pattern**: Viper configuration is set up automatically when any getter function is invoked for the first time, ensuring the application code never needs to manually bootstrap the configuration engine.

## Configuration Initialization Process

When the first configuration value is requested, the wrapper executes a seven-step initialization sequence defined in [`utils/cofigure/cfg.go`](https://github.com/jom-io/gorig/blob/main/utils/cofigure/cfg.go):

1. **Environment Prefix Setup** — `viper.SetEnvPrefix("gorig")` at line 111 establishes that all environment variables must use the `GORIG_` prefix.
2. **Automatic Environment Scanning** — `viper.AutomaticEnv()` at line 112 enables automatic lookup of matching environment variables without manual registration.
3. **Key Normalization** — `viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))` at line 113 converts dotted configuration keys (e.g., `sys.mode`) to underscored environment names (`SYS_MODE`).
4. **Config Path Registration** — Lines 114-115 add `./_bin/` and `./` as search paths using `viper.AddConfigPath()`.
5. **Runtime Mode Detection** — Line 116 sets the config filename dynamically via `viper.SetConfigName(GetString("sys.mode", "local"))`, defaulting to [`local.yaml`](https://github.com/jom-io/gorig/blob/main/local.yaml) unless overridden.
6. **Format Specification** — `viper.SetConfigType("yaml")` at line 117 forces YAML format for all configuration files.
7. **File Loading** — `viper.ReadInConfig()` at line 118 loads the selected file and merges it with environment variables and defaults.

## Accessing Configuration Values

After initialization, the codebase interacts with configuration through type-safe helper functions that delegate directly to Viper.

### String Values with Fallbacks

The `GetString(key, fallback)` function at line 21 wraps `viper.GetString()`, returning the fallback value if the key is undefined:

```go
import "github.com/jom-io/gorig/utils/cofigure"

func main() {
    // Returns value of app.name or "gorig" if undefined
    appName := cofigure.GetString("app.name", "gorig")
    fmt.Println("Application:", appName)
}

```

### Boolean and Numeric Types

For primitive types, the wrapper provides direct mappings:

- **`GetBool(key)`** — Line 41 wraps `viper.GetBool()` for boolean flags.
- **`GetInt(key)`** — Line 52 wraps `viper.GetInt()` for signed integers.
- **`GetUint64(key)`** — Line 63 wraps `viper.GetUint64()` for unsigned 64-bit values.
- **`GetDuration(key)`** — Line 74 wraps `viper.GetDuration()` for time-based settings.

```go
debug := cofigure.GetBool("log.debug")
if debug {
    fmt.Println("Debug logging enabled")
}

timeout := cofigure.GetDuration("server.timeout")

```

### Map Structures

For nested configuration blocks, `GetStringMap(key)` at line 15 returns a map of values:

```go
dbConfig := cofigure.GetStringMap("database")
fmt.Printf("Host: %s\n", dbConfig["host"])

```

## Environment Variable Integration

Gorig's Viper wrapper implements seamless environment variable override capabilities. The initialization establishes a `GORIG_` prefix requirement and automatic key transformation.

To override a configuration value using environment variables:

```bash
export GORIG_SYS_MODE=production
export GORIG_LOG_DEBUG=true
go run ./cmd/server

```

The wrapper automatically maps `GORIG_SYS_MODE` to the `sys.mode` configuration key and `GORIG_LOG_DEBUG` to `log.debug`, overriding any YAML file values due to Viper's precedence rules.

## Configuration File Structure

By default, Gorig expects configuration files named after the runtime mode:

- [`local.yaml`](https://github.com/jom-io/gorig/blob/main/local.yaml) (default)
- [`production.yaml`](https://github.com/jom-io/gorig/blob/main/production.yaml)
- [`development.yaml`](https://github.com/jom-io/gorig/blob/main/development.yaml)

Files are searched in `./_bin/` first, then the project root `./`. The active mode is determined by the `sys.mode` key, which can be set via environment variable (`GORIG_SYS_MODE`) or command-line flag before initialization.

## Summary

- Gorig encapsulates Viper in [`utils/cofigure/cfg.go`](https://github.com/jom-io/gorig/blob/main/utils/cofigure/cfg.go), providing a centralized configuration management system.
- The wrapper initializes automatically on first use, configuring environment variable support with the `GORIG_` prefix and YAML file loading.
- Type-safe helpers (`GetString`, `GetBool`, `GetInt`, `GetUint64`, `GetDuration`, `GetStringMap`) provide direct access to Viper functionality.
- Environment variables automatically override YAML values using dot-to-underscore key mapping (e.g., `database.host` becomes `GORIG_DATABASE_HOST`).
- Configuration filenames are determined by the `sys.mode` setting, defaulting to [`local.yaml`](https://github.com/jom-io/gorig/blob/main/local.yaml).

## Frequently Asked Questions

### How does Gorig determine which configuration file to load?

According to [`utils/cofigure/cfg.go`](https://github.com/jom-io/gorig/blob/main/utils/cofigure/cfg.go) line 116, Gorig calls `viper.SetConfigName(GetString("sys.mode", "local"))`, which sets the filename based on the `sys.mode` configuration value. This defaults to `local`, causing the system to search for [`local.yaml`](https://github.com/jom-io/gorig/blob/main/local.yaml). You can override this by setting the `GORIG_SYS_MODE` environment variable before startup.

### Can I use JSON configuration files instead of YAML?

The current implementation in [`utils/cofigure/cfg.go`](https://github.com/jom-io/gorig/blob/main/utils/cofigure/cfg.go) line 117 explicitly calls `viper.SetConfigType("yaml")`, which forces YAML format for all configuration files. To use JSON, you would need to modify the wrapper source code to change the config type or extend the initialization logic to support multiple formats.

### How do I access deeply nested configuration values?

Use the dot notation within the getter functions. For a structure like `database.connections.primary.host`, call `cofigure.GetString("database.connections.primary.host", "localhost")`. The wrapper passes these dotted keys directly to Viper's lookup mechanism, which traverses nested YAML maps automatically.

### What happens if a configuration key is missing?

For `GetString()`, the second argument serves as a fallback default value. For other types like `GetBool()` or `GetInt()`, Viper returns the zero value for that type (false, 0, etc.) if the key is undefined. The wrapper does not panic on missing keys; it delegates Viper's default return behavior to the caller.