361 lines
12 KiB
Markdown
361 lines
12 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
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
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```dockerfile
|
|
# 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
|
|
|
|
```yaml
|
|
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
|
|
- [x] Add Viper dependency
|
|
- [x] Create configuration structures
|
|
- [x] Implement file-based configuration loading
|
|
- [x] Maintain environment variable compatibility
|
|
- [x] Add validation and error handling
|
|
- [x] Create environment-specific configuration files
|
|
- [x] Update application startup code
|
|
- [x] 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
|
|
- [x] Configuration file loading from multiple locations
|
|
- [x] Environment variable override functionality
|
|
- [x] Default value fallback
|
|
- [x] Environment-specific configuration selection
|
|
- [x] Backward compatibility with existing environment variables
|
|
- [x] Configuration validation and error handling
|
|
- [x] Application startup with different configuration sources
|
|
|
|
### 🧪 Test Commands
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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. |