config

Configuration Package

A modern, senior-level configuration package using Viper with best practices.

Features

✅ No Global State - Uses instance-based configuration instead of global variables
✅ Environment Variable Support - Automatic environment variable binding with PW_ prefix
✅ Type-Safe - Strongly typed configuration structs with validation
✅ Multiple Sources - Supports config files, environment variables, and defaults
✅ Auto-Creation - Automatically creates config file with secure defaults if missing
✅ Validation - Built-in configuration validation
✅ Testable - Fully testable without globals or side effects
✅ Backwards Compatible - Supports legacy environment variable names

Usage

Basic Usage

import "github.com/passwall/passwall-server/internal/config"

// Load configuration with defaults
cfg, err := config.Load()
if err != nil {
    log.Fatal(err)
}

// Access configuration
fmt.Println(cfg.Server.Port)
fmt.Println(cfg.Database.Host)

Custom Config File

cfg, err := config.Load(config.LoaderOptions{
    ConfigFile: "/path/to/config.yml",
    EnvPrefix:  "PW",
})

Using Environment Variables

The package supports automatic environment variable binding:

# Server configuration
export PW_SERVER_PORT=8080
export PW_SERVER_ENV=production
export PW_SERVER_PASSPHRASE=your-secure-passphrase
export PW_SERVER_SECRET=your-jwt-secret

# Database configuration
export PW_DB_HOST=localhost
export PW_DB_PORT=5432
export PW_DB_NAME=passwall
export PW_DB_USERNAME=postgres
export PW_DB_PASSWORD=secure-password

# Email configuration
export PW_EMAIL_HOST=smtp.example.com
export PW_EMAIL_PORT=587
export PW_EMAIL_USERNAME=noreply@example.com

Backwards Compatible Variables

For backwards compatibility, these environment variables are also supported:

• PORT → server.port
• DOMAIN → server.domain
• POSTGRES_DB → database.name
• POSTGRES_USER → database.username
• POSTGRES_PASSWORD → database.password
• POSTGRES_HOST → database.host
• POSTGRES_PORT → database.port

Configuration Structure

Server Configuration

server:
  env: prod # Environment: dev, prod
  host: 0.0.0.0 # Server host
  port: 3625 # Server port
  domain: https://vault.passwall.io # Public domain
  dir: /app/config # Config directory
  passphrase: <auto-generated-secure-key> # Encryption passphrase
  secret: <auto-generated-secure-key> # JWT secret
  timeout: 24 # Request timeout (seconds)
  generated_password_length: 16 # Default password length
  access_token_expire_duration: 30m # Access token expiry
  refresh_token_expire_duration: 15d # Refresh token expiry
  api_key: <auto-generated-secure-key> # API key

Database Configuration

database:
  name: passwall # Database name
  username: postgres # Database username
  password: password # Database password
  host: localhost # Database host
  port: 5432 # Database port
  log_mode: false # Enable SQL logging
  ssl_mode: disable # SSL mode: disable, require, verify-full, verify-ca

Email Configuration

email:
  host: smtp.passwall.io # SMTP host
  port: 25 # SMTP port
  username: hello@passwall.io # SMTP username
  password: password # SMTP password
  from_name: Passwall # From name
  from_email: hello@passwall.io # From email
  admin: hello@passwall.io # Admin email
  api_key: "" # Email service API key

Validation

The configuration is automatically validated on load. Required fields:

• server.port - Must be set
• server.passphrase - Must be a secure value (not placeholder)
• server.secret - Must be a secure value (not placeholder)
• database.host - Must be set
• database.name - Must be set
• database.username - Must be set

Security Features

Secure Key Generation

The package automatically generates cryptographically secure keys using crypto/rand:

• 32-byte keys encoded as base64
• Used for server.passphrase, server.secret, and server.api_key
• Keys are unique per installation

Validation

Configuration is validated to ensure:

• No placeholder values in production
• Required fields are present
• Values meet security requirements

Testing

The package includes comprehensive tests:

go test ./internal/config -v

Tests cover:

• Default configuration loading
• Environment variable override
• Backwards compatible env vars
• Configuration validation
• Secure key generation
• Config file auto-creation

Migration from Old Config

Old Way (Junior)

// Global state
cfg, err := config.Init("./config", "config")

// Accessing global viper
viper.GetString("server.port")

New Way (Senior)

// Instance-based, no globals
cfg, err := config.Load(config.LoaderOptions{
    ConfigFile: "./config/config.yml",
    EnvPrefix:  "PW",
})

// Type-safe access
cfg.Server.Port
cfg.Database.Host

Best Practices

1. Use Environment Variables in Production - Don't commit secrets to config files
2. Validate Configuration - The package validates on load, catch errors early
3. Use Type-Safe Access - Access config via structs, not string keys
4. Set Secure Values - Always override auto-generated keys in production
5. Test Configuration - Write tests that validate your config loading

Environment Variable Precedence

Values are loaded in this order (later overrides earlier):

1. Default values (in code)
2. Config file values
3. Environment variables

Example Config File

The package auto-generates a config.yml file with secure defaults:

database:
  host: localhost
  log_mode: false
  name: passwall
  password: password
  port: "5432"
  ssl_mode: disable
  username: postgres
email:
  admin: hello@passwall.io
  api_key: ""
  from_email: hello@passwall.io
  from_name: Passwall
  host: smtp.passwall.io
  password: password
  port: "25"
  username: hello@passwall.io
server:
  access_token_expire_duration: 30m
  api_key: <secure-random-key>
  dir: /app/config
  domain: https://vault.passwall.io
  env: prod
  generated_password_length: 16
  host: 0.0.0.0
  passphrase: <secure-random-key>
  port: "3625"
  refresh_token_expire_duration: 15d
  secret: <secure-random-key>
  timeout: 24

Mocking for Tests

The config package provides comprehensive mocking utilities that can be used anywhere in your project for testing.

Basic Mock Usage

import "github.com/passwall/passwall-server/internal/config"

func TestMyService(t *testing.T) {
    // Create a ready-to-use mock config
    cfg := config.NewMockConfig()

    // Use it in your service
    service := NewMyService(cfg)

    // All values are pre-set and validated
    assert.Equal(t, "test", cfg.Server.Env)
    assert.Equal(t, "passwall_test", cfg.Database.Name)
}

Using the Builder Pattern

For custom test scenarios, use the fluent builder:

func TestWithCustomConfig(t *testing.T) {
    cfg := config.NewMockBuilder().
        WithServerPort("8080").
        WithDatabaseName("my_test_db").
        WithPassphrase("my-test-passphrase").
        WithAccessTokenDuration("30m").
        Build()

    service := NewAuthService(cfg)
    // ... your tests
}

Available Builder Methods

Server Configuration:

• WithServerPort(port string)
• WithServerHost(host string)
• WithServerEnv(env string)
• WithPassphrase(passphrase string)
• WithSecret(secret string)
• WithAccessTokenDuration(duration string)
• WithRefreshTokenDuration(duration string)
• WithCustomServer(server ServerConfig)

Database Configuration:

• WithDatabaseHost(host string)
• WithDatabasePort(port string)
• WithDatabaseName(name string)
• WithDatabaseUser(username string)
• WithDatabasePassword(password string)
• WithDatabaseSSLMode(sslMode string)
• WithCustomDatabase(database DatabaseConfig)

Email Configuration:

• WithEmailHost(host string)
• WithEmailPort(port string)
• WithEmailFrom(email, name string)
• WithCustomEmail(email EmailConfig)

Practical Examples

Testing Different Environments

func TestEnvironmentBehavior(t *testing.T) {
    tests := []struct {
        name   string
        config *config.Config
    }{
        {
            name: "development",
            config: config.NewMockBuilder().
                WithServerEnv("dev").
                Build(),
        },
        {
            name: "production",
            config: config.NewMockBuilder().
                WithServerEnv("prod").
                WithDatabaseSSLMode("require").
                Build(),
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // Test with specific environment config
        })
    }
}

Testing Authentication Services

func TestAuthService(t *testing.T) {
    cfg := config.NewMockBuilder().
        WithSecret("test-jwt-secret").
        WithAccessTokenDuration("15m").
        WithRefreshTokenDuration("7d").
        Build()

    authService := NewAuthService(cfg)
    // Test token generation, validation, etc.
}

Testing Database Services

func TestDatabaseConnection(t *testing.T) {
    cfg := config.NewMockBuilder().
        WithDatabaseHost("localhost").
        WithDatabasePort("5432").
        WithDatabaseName("test_db").
        WithDatabaseUser("test_user").
        Build()

    db, err := ConnectDatabase(cfg)
    // Test database operations
}

Parallel Tests with Isolated Configs

func TestParallelServices(t *testing.T) {
    t.Run("service_a", func(t *testing.T) {
        t.Parallel()
        cfg := config.NewMockBuilder().
            WithServerPort("8081").
            Build()
        // Test service A with its own config
    })

    t.Run("service_b", func(t *testing.T) {
        t.Parallel()
        cfg := config.NewMockBuilder().
            WithServerPort("8082").
            Build()
        // Test service B with its own config
    })
}

Mock Config Defaults

The mock config comes with safe test defaults:

server:
  env: test
  host: localhost
  port: 3625
  passphrase: test-passphrase-for-encryption
  secret: test-secret-for-jwt-tokens
  timeout: 10
  access_token_expire_duration: 15m
  refresh_token_expire_duration: 1h

database:
  name: passwall_test
  username: test_user
  password: test_password
  host: localhost
  port: 5432
  ssl_mode: disable

email:
  host: smtp.test.local
  from_email: test@passwall.io
  from_name: Passwall Test

Using Mocks Across Packages

The mock can be imported and used from any package in your project:

// In internal/service/auth_test.go
import "github.com/passwall/passwall-server/internal/config"

func TestAuthService(t *testing.T) {
    cfg := config.NewMockConfig()
    service := NewAuthService(cfg.Server.Secret, cfg.Server.AccessTokenExpireDuration)
    // ... tests
}

// In internal/handler/http/login_test.go
import "github.com/passwall/passwall-server/internal/config"

func TestLoginHandler(t *testing.T) {
    cfg := config.NewMockBuilder().
        WithPassphrase("handler-test-passphrase").
        Build()
    handler := NewLoginHandler(cfg)
    // ... tests
}

// In internal/repository/gormrepo/user_test.go
import "github.com/passwall/passwall-server/internal/config"

func TestUserRepository(t *testing.T) {
    cfg := config.NewMockBuilder().
        WithDatabaseName("user_repo_test").
        Build()
    // Use cfg.Database for test database setup
}

Troubleshooting

Config file not found

The package automatically creates a config file if it doesn't exist. Ensure the directory is writable.

Validation errors

Check that required fields are set and secure values are not placeholders.

Environment variables not working

Ensure the PW_ prefix is used and keys use underscores (e.g., PW_SERVER_PORT).

Mock config validation failing in tests

The mock config is pre-validated and should always pass. If it fails, check that you haven't overridden required fields with empty values using the builder.