hnrx/tankstopp-app
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
523f6cbdeae9abefd61e8e589a6aad4f82c178ea
tankstopp-app/VIPER_IMPLEMENTATION_SUMMARY.md
T
matthias bf68bde4ce first commit
2025-07-07 01:44:12 +02:00

12 KiB
Raw Blame History

Viper Configuration Implementation Summary

Overview

Successfully implemented Viper configuration management for TankStopp, replacing the previous environment-variable-only configuration system with a flexible, hierarchical configuration system that supports:

  • 📄 Configuration files (YAML, JSON, TOML)
  • 🌍 Environment variables (with precedence)
  • 🔧 Default values
  • 🏗️ Environment-specific configs
  • 🔒 Backward compatibility

Implementation Details

🆕 Files Created

  1. internal/config/config.go - Global application configuration package

    • Comprehensive configuration structures
    • Viper-based loading with environment variable binding
    • Configuration validation
    • Environment detection

  2. config.yaml - Default configuration file

    • Complete configuration template
    • Production-ready defaults
    • Comprehensive documentation

  3. config.development.yaml - Development environment configuration

    • Development-optimized settings
    • Verbose logging and debugging
    • Relaxed security for development

  4. config.production.yaml - Production environment configuration

    • Production-hardened settings
    • Security-focused defaults
    • Performance optimizations

  5. CONFIG_DOCUMENTATION.md - Comprehensive configuration documentation

    • Complete reference guide
    • Environment variable mapping
    • Migration instructions
    • Troubleshooting guide

🔄 Files Modified

  1. internal/database/config.go - Enhanced database configuration

    • Added LoadFromConfig() function using Viper
    • Maintained backward compatibility with environment variables
    • Added getLogLevelFromString() helper function
    • Environment variables still take precedence over config files

  2. internal/database/db.go - Added new initialization function

    • Added NewDBFromConfig() function
    • Supports loading database config from Viper configuration

  3. cmd/main.go - Updated application startup

    • Integrated Viper configuration loading
    • Graceful fallback to environment variables
    • Enhanced server configuration with timeouts
    • Improved logging and error handling

  4. Makefile - Added configuration management targets

    • config-validate - Validate configuration files
    • config-show - Display current configuration
    • config-help - Show configuration documentation
    • run-dev - Run with development config
    • run-prod - Run with production config
    • config-test - Test configuration loading

  5. go.mod - Added Viper dependency

    • Added github.com/spf13/viper v1.20.1
    • Includes all necessary dependencies for configuration management

Configuration Hierarchy

The configuration system follows this precedence order (highest to lowest):

  1. Environment Variables (highest priority)

    • TANKSTOPP_* prefixed variables
    • Legacy DB_* variables (backward compatibility)
    • Override any config file values

  2. Configuration Files

    • config.yaml (default)
    • config.development.yaml (development)
    • config.production.yaml (production)
    • Searched in multiple locations

  3. Default Values (lowest priority)

    • Hardcoded sensible defaults
    • Ensure application runs without configuration

Key Features Implemented

🔧 Environment Variable Mapping

Configuration Path Environment Variable
server.port TANKSTOPP_SERVER_PORT
database.path TANKSTOPP_DATABASE_PATH
database.connection_pool.max_idle_connections TANKSTOPP_DATABASE_CONNECTION_POOL_MAX_IDLE_CONNECTIONS
app.debug TANKSTOPP_APP_DEBUG
security.session.timeout TANKSTOPP_SECURITY_SESSION_TIMEOUT

🏗️ Environment-Specific Configuration

  • Development: Verbose logging, relaxed security, shorter timeouts
  • Production: Minimal logging, strict security, performance optimized
  • Automatic Selection: Based on TANKSTOPP_ENV or ENV environment variable

🔄 Backward Compatibility

Legacy environment variables are still supported:

  • DB_PATH → TANKSTOPP_DATABASE_PATH
  • DB_MAX_IDLE_CONNS → TANKSTOPP_DATABASE_CONNECTION_POOL_MAX_IDLE_CONNECTIONS
  • ENV → TANKSTOPP_APP_ENVIRONMENT

📂 Configuration File Discovery

The application searches for configuration files in:

  1. TANKSTOPP_CONFIG_PATH (explicit path)
  2. ./config.yaml (current directory)
  3. ./config/config.yaml (config subdirectory)
  4. $HOME/.tankstopp/config.yaml (user directory)
  5. /etc/tankstopp/config.yaml (system directory)

Configuration Structure

🏗️ Main Configuration Categories

server:          # HTTP server settings
database:        # Database connection and performance
app:             # Application metadata and environment
security:        # Authentication and session management
logging:         # Application logging configuration
external_services: # External API configurations
features:        # Feature flags
defaults:        # Default values for new entities

🔍 Database Configuration Details

database:
  path: "fuel_stops.db"
  
  connection_pool:
    max_idle_connections: 10
    max_open_connections: 100
    connection_max_lifetime: "1h"
    connection_max_idle_time: "30m"
  
  logging:
    level: "warn"
    slow_query_threshold: "200ms"
    debug: false
  
  migration:
    auto_migrate: true
    drop_tables_first: false
    create_batch_size: 1000
  
  performance:
    prepare_statements: true
    disable_foreign_key_check: false
    query_fields: true
    dry_run: false
    create_in_batches: 100

Usage Examples

🚀 Running with Different Configurations

# Use default configuration
./tankstopp

# Use development configuration
make run-dev

# Use production configuration
make run-prod

# Use custom configuration file
TANKSTOPP_CONFIG_PATH=/path/to/custom-config.yaml ./tankstopp

# Override specific settings with environment variables
TANKSTOPP_SERVER_PORT=9000 TANKSTOPP_APP_DEBUG=true ./tankstopp

🐳 Docker Usage

# Copy configuration file
COPY config.production.yaml /app/config.yaml

# Or use environment variables
ENV TANKSTOPP_DATABASE_PATH=/data/fuel_stops.db
ENV TANKSTOPP_APP_ENVIRONMENT=production
ENV TANKSTOPP_SERVER_HOST=0.0.0.0

☸️ Kubernetes ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: tankstopp-config
data:
  config.yaml: |
    server:
      host: "0.0.0.0"
      port: 8080
    database:
      path: "/data/fuel_stops.db"
    app:
      environment: "production"

Benefits Achieved

🎯 Developer Experience

  • Easy Configuration: YAML files are human-readable and easy to edit
  • Environment Flexibility: Different configs for dev/prod without code changes
  • Validation: Built-in configuration validation with clear error messages
  • Documentation: Comprehensive docs with examples

🔒 Security & Operations

  • Environment Override: Sensitive values can be set via environment variables
  • File Permissions: Config files can be secured with proper permissions
  • No Secrets in Code: Database paths and other sensitive settings externalized
  • Production Ready: Separate production configuration with security hardening

🚀 Deployment & Scaling

  • Container Friendly: Works well with Docker and Kubernetes
  • Environment Specific: Automatic environment detection and configuration
  • Fallback Support: Graceful degradation to environment variables
  • Hot Configuration: Some settings can be changed without code modification

🔧 Maintenance & Development

  • Centralized Configuration: All settings in one place
  • Type Safety: Strongly typed configuration with validation
  • Default Values: Sensible defaults ensure application works out-of-the-box
  • Migration Path: Smooth transition from existing environment variable setup

Migration Path

Phase 1: ✅ Implemented

  • Add Viper dependency
  • Create configuration structures
  • Implement file-based configuration loading
  • Maintain environment variable compatibility
  • Add validation and error handling
  • Create environment-specific configuration files
  • Update application startup code
  • Add Makefile targets for configuration management

Phase 2: 🔄 Next Steps

  • Add configuration validation command-line flag
  • Implement configuration hot-reloading
  • Add configuration REST API endpoints
  • Create configuration management UI
  • Add configuration backup/restore functionality
  • Implement configuration templating
  • Add configuration encryption for sensitive values

Phase 3: 🎯 Future Enhancements

  • Integration with external configuration services (Consul, etcd)
  • Configuration versioning and rollback
  • Dynamic feature flag management
  • Configuration compliance checking
  • Automated configuration testing
  • Configuration drift detection

Testing & Validation

✅ Verified Features

  • Configuration file loading from multiple locations
  • Environment variable override functionality
  • Default value fallback
  • Environment-specific configuration selection
  • Backward compatibility with existing environment variables
  • Configuration validation and error handling
  • Application startup with different configuration sources

🧪 Test Commands

# Test configuration validation
make config-validate

# Show current configuration
make config-show

# Test different configuration loading
make config-test

# Run with development configuration
make run-dev

# Test environment variable override
TANKSTOPP_SERVER_PORT=9999 ./tankstopp

Troubleshooting

Common Issues & Solutions

  1. Config file not found

    • Check file exists in search paths
    • Verify TANKSTOPP_CONFIG_PATH environment variable
    • Use make config-show to see available files

  2. Environment variables not working

    • Ensure proper TANKSTOPP_ prefix
    • Use uppercase with underscores
    • Example: database.path → TANKSTOPP_DATABASE_PATH

  3. Invalid configuration

    • Use make config-validate to check syntax
    • Check YAML indentation (spaces, not tabs)
    • Verify data types match expected values

Documentation

📚 Available Documentation

  • CONFIG_DOCUMENTATION.md - Complete configuration reference
  • Configuration files - Inline comments and examples
  • Makefile help - make config-help for quick reference
  • Environment examples - Development and production configurations

🔍 Quick Reference

# Get help
make help
make config-help

# Validate configuration
make config-validate

# Show current settings
make config-show

# Test configuration loading
make config-test

Summary

The Viper configuration implementation provides TankStopp with a modern, flexible, and secure configuration management system. It maintains full backward compatibility while adding powerful new capabilities for managing different environments and deployment scenarios.

Key Achievements:

  • ✅ Zero Breaking Changes - Existing deployments continue to work
  • ✅ Enhanced Flexibility - Multiple configuration sources and formats
  • ✅ Improved Security - Environment-specific settings and validation
  • ✅ Better Developer Experience - Clear documentation and tooling
  • ✅ Production Ready - Secure defaults and deployment-friendly features

The implementation positions TankStopp for easier deployment, better maintainability, and more flexible configuration management across different environments and deployment scenarios.

Reference in New Issue View Git Blame Copy Permalink