tankstopp-app/CONFIG_DOCUMENTATION.md

TankStopp Configuration Documentation

Overview

TankStopp uses Viper for configuration management, providing a flexible and powerful way to configure the application using:

• Configuration files (YAML, JSON, TOML, etc.)
• Environment variables
• Command-line flags (future feature)
• Default values

This system allows for easy deployment across different environments while maintaining security and flexibility.

Configuration Precedence

Configuration values are loaded in the following order (highest to lowest priority):

1. Environment variables (highest priority)
2. Configuration files
3. Default values (lowest priority)

This means environment variables will always override config file values, providing a secure way to override sensitive settings in production.

Configuration File Locations

The application searches for configuration files in the following locations (in order):

1. Explicit path: If TANKSTOPP_CONFIG_PATH environment variable is set
2. Current directory: ./config.yaml
3. Config subdirectory: ./config/config.yaml
4. User home directory: $HOME/.tankstopp/config.yaml
5. System directory: /etc/tankstopp/config.yaml

Environment-Specific Configuration

You can use environment-specific configuration files:

• config.development.yaml - Development environment
• config.production.yaml - Production environment
• config.test.yaml - Test environment

Set the TANKSTOPP_ENV or ENV environment variable to automatically load the appropriate config file.

Supported File Formats

• YAML (recommended): config.yaml
• JSON: config.json
• TOML: config.toml
• Properties: config.properties

Configuration Structure

Complete Configuration Example

# Server Configuration
server:
  host: "localhost"
  port: 8081
  read_timeout: 30s
  write_timeout: 30s
  idle_timeout: 120s
  shutdown_timeout: 10s

# Database Configuration
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"           # silent, error, warn, info
    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
    ignore_relationships_when_migrating: false
    query_fields: true
    dry_run: false
    create_in_batches: 100

# Application Settings
app:
  name: "TankStopp"
  version: "1.0.0"
  environment: "development"  # development, production, test
  debug: true

# Security Settings
security:
  session:
    timeout: "24h"
    cookie_name: "tankstopp_session"
    secure_cookies: false
    http_only: true
  
  password:
    min_length: 8
    require_uppercase: true
    require_lowercase: true
    require_numbers: true
    require_special_chars: false

# Logging Configuration
logging:
  level: "info"             # debug, info, warn, error
  format: "text"            # text, json
  output: "stdout"          # stdout, stderr, file
  file_path: "logs/tankstopp.log"
  
  rotation:
    enabled: false
    max_size: "100MB"
    max_age: "30d"
    max_backups: 5

# External Services
external_services:
  overpass_api:
    url: "https://overpass-api.de/api/interpreter"
    timeout: "30s"
    max_retries: 3
    search_radius: 5000

# Feature Flags
features:
  fuel_station_search: true
  vehicle_management: true
  statistics_dashboard: true
  data_export: true
  api_endpoints: true

# Default Values
defaults:
  currency: "EUR"
  fuel_type: "Super E5"
  distance_unit: "km"
  volume_unit: "liters"

Environment Variables

All configuration options can be overridden using environment variables with the TANKSTOPP_ prefix:

Format Convention

Convert the YAML path to an environment variable by:

1. Adding TANKSTOPP_ prefix
2. Converting to uppercase
3. Replacing dots (.) with underscores (_)

Examples

YAML 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

Legacy Environment Variables

For backward compatibility, these legacy environment variables are still supported:

Legacy Variable	New Variable	Description
DB_PATH	TANKSTOPP_DATABASE_PATH	Database file path
DB_MAX_IDLE_CONNS	TANKSTOPP_DATABASE_CONNECTION_POOL_MAX_IDLE_CONNECTIONS	Max idle connections
DB_MAX_OPEN_CONNS	TANKSTOPP_DATABASE_CONNECTION_POOL_MAX_OPEN_CONNECTIONS	Max open connections
DB_DEBUG	TANKSTOPP_DATABASE_LOGGING_DEBUG	Debug mode
ENV	TANKSTOPP_APP_ENVIRONMENT	Application environment

Configuration Options Reference

Server Configuration

Option	Type	Default	Description
server.host	string	"localhost"	Server bind address
server.port	int	8081	Server port
server.read_timeout	duration	"30s"	HTTP read timeout
server.write_timeout	duration	"30s"	HTTP write timeout
server.idle_timeout	duration	"120s"	HTTP idle timeout
server.shutdown_timeout	duration	"10s"	Graceful shutdown timeout

Database Configuration

Option	Type	Default	Description
database.path	string	"fuel_stops.db"	SQLite database file path
database.connection_pool.max_idle_connections	int	10	Maximum idle connections
database.connection_pool.max_open_connections	int	100	Maximum open connections
database.connection_pool.connection_max_lifetime	duration	"1h"	Connection max lifetime
database.connection_pool.connection_max_idle_time	duration	"30m"	Connection max idle time
database.logging.level	string	"warn"	Log level: silent, error, warn, info
database.logging.slow_query_threshold	duration	"200ms"	Slow query threshold
database.logging.debug	bool	false	Enable debug logging
database.migration.auto_migrate	bool	true	Auto-run migrations
database.migration.drop_tables_first	bool	false	Drop tables before migration
database.migration.create_batch_size	int	1000	Batch size for bulk operations

Application Configuration

Option	Type	Default	Description
app.name	string	"TankStopp"	Application name
app.version	string	"1.0.0"	Application version
app.environment	string	"development"	Environment: development, production, test
app.debug	bool	true	Enable debug mode

Security Configuration

Option	Type	Default	Description
security.session.timeout	duration	"24h"	Session timeout
security.session.cookie_name	string	"tankstopp_session"	Session cookie name
security.session.secure_cookies	bool	false	Require HTTPS for cookies
security.session.http_only	bool	true	HTTP-only cookies
security.password.min_length	int	8	Minimum password length
security.password.require_uppercase	bool	true	Require uppercase letters
security.password.require_lowercase	bool	true	Require lowercase letters
security.password.require_numbers	bool	true	Require numbers
security.password.require_special_chars	bool	false	Require special characters

Environment-Specific Configurations

Development Configuration

# config.development.yaml
server:
  host: "localhost"
  port: 8081

database:
  path: "fuel_stops_dev.db"
  logging:
    level: "info"
    debug: true

app:
  environment: "development"
  debug: true

security:
  session:
    timeout: "8h"
    secure_cookies: false
  password:
    min_length: 6
    require_uppercase: false
    require_special_chars: false

logging:
  level: "debug"
  format: "text"
  output: "stdout"

Production Configuration

# config.production.yaml
server:
  host: "0.0.0.0"
  port: 8080

database:
  path: "/var/lib/tankstopp/fuel_stops.db"
  logging:
    level: "error"
    debug: false
  migration:
    auto_migrate: false

app:
  environment: "production"
  debug: false

security:
  session:
    timeout: "24h"
    secure_cookies: true
  password:
    min_length: 12
    require_special_chars: true

logging:
  level: "info"
  format: "json"
  output: "file"
  file_path: "/var/log/tankstopp/application.log"
  rotation:
    enabled: true
    max_size: "500MB"
    max_age: "90d"

Migration from Environment Variables

If you're currently using environment variables only, you can migrate to config files:

Step 1: Create Base Configuration

Create a config.yaml file with your current settings:

server:
  port: 8081

database:
  path: "fuel_stops.db"

app:
  environment: "development"

Step 2: Environment-Specific Overrides

Keep sensitive or environment-specific values as environment variables:

# Production overrides
export TANKSTOPP_DATABASE_PATH="/var/lib/tankstopp/fuel_stops.db"
export TANKSTOPP_APP_ENVIRONMENT="production"
export TANKSTOPP_APP_DEBUG="false"

Step 3: Gradual Migration

You can migrate gradually since environment variables take precedence over config files.

Docker Configuration

Using Configuration Files

# Copy config files
COPY config.production.yaml /app/config.yaml

# Set environment for config selection
ENV TANKSTOPP_ENV=production

Using Environment Variables

# Database configuration
ENV TANKSTOPP_DATABASE_PATH=/var/lib/tankstopp/fuel_stops.db
ENV TANKSTOPP_APP_ENVIRONMENT=production
ENV TANKSTOPP_APP_DEBUG=false

# Server configuration
ENV TANKSTOPP_SERVER_HOST=0.0.0.0
ENV TANKSTOPP_SERVER_PORT=8080

Docker Compose Example

version: '3.8'
services:
  tankstopp:
    build: .
    ports:
      - "8080:8080"
    environment:
      - TANKSTOPP_DATABASE_PATH=/data/fuel_stops.db
      - TANKSTOPP_APP_ENVIRONMENT=production
      - TANKSTOPP_APP_DEBUG=false
    volumes:
      - ./data:/data
      - ./config.production.yaml:/app/config.yaml

Kubernetes Configuration

ConfigMap Example

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"
      debug: false

Secret Example

apiVersion: v1
kind: Secret
metadata:
  name: tankstopp-secrets
type: Opaque
stringData:
  DATABASE_PATH: "/secure/fuel_stops.db"

Validation and Debugging

Configuration Validation

The application validates configuration on startup. Common validation errors:

• Invalid port number: Must be between 1-65535
• Empty database path: Database path cannot be empty
• Invalid environment: Must be development, production, or test
• Invalid log level: Must be debug, info, warn, or error

Debugging Configuration

Enable debug logging to see configuration loading:

export TANKSTOPP_APP_DEBUG=true
export TANKSTOPP_LOGGING_LEVEL=debug

The application will log:

• Which config files were found and loaded
• Which environment variables are being used
• Final merged configuration (without sensitive values)

Testing Configuration

You can test configuration without starting the full application:

# Test with specific config file
TANKSTOPP_CONFIG_PATH=config.production.yaml ./tankstopp --validate-config

# Test with environment variables
TANKSTOPP_APP_DEBUG=true ./tankstopp --validate-config

Security Best Practices

1. File Permissions

Protect configuration files containing sensitive data:

chmod 600 config.production.yaml
chown tankstopp:tankstopp config.production.yaml

2. Environment Variables for Secrets

Use environment variables for sensitive values:

# Don't put secrets in config files
export TANKSTOPP_DATABASE_PATH="/secure/path/fuel_stops.db"
export TANKSTOPP_SECURITY_SESSION_COOKIE_NAME="secure_session_name"

3. Production Settings

Ensure production-safe defaults:

app:
  environment: "production"
  debug: false

security:
  session:
    secure_cookies: true
    http_only: true

logging:
  level: "info"  # Don't use debug in production

Troubleshooting

Common Issues

1. Configuration file not found

Warning: Failed to load config file 'config.yaml': Config File "config" Not Found

• Check file exists in search paths
• Verify file permissions
• Check TANKSTOPP_CONFIG_PATH environment variable

2. Invalid YAML syntax

Error reading config file: yaml: line 10: mapping values are not allowed in this context

• Validate YAML syntax using an online validator
• Check indentation (use spaces, not tabs)
• Ensure proper quoting of string values

3. Environment variable not working

Configuration not being overridden by environment variable

• Verify variable name format: TANKSTOPP_ prefix + uppercase + underscores
• Check variable is exported: export TANKSTOPP_SERVER_PORT=8080
• Verify no typos in variable name

4. Database connection issues

Failed to connect to database: unable to open database file

• Check database path exists and is writable
• Verify file permissions
• Ensure directory exists

Getting Help

1. Enable debug logging: Set TANKSTOPP_APP_DEBUG=true
2. Check configuration loading: Look for config-related log messages
3. Validate configuration: Use --validate-config flag
4. Test minimal config: Start with basic configuration and add options gradually

Advanced Usage

Custom Configuration Paths

# Use custom config file
export TANKSTOPP_CONFIG_PATH=/etc/myapp/custom-config.yaml

# Use config directory
export TANKSTOPP_CONFIG_PATH=/etc/myapp/

Multiple Configuration Files

You can split configuration across multiple files:

# base.yaml
server:
  host: "localhost"

database:
  path: "fuel_stops.db"

# security.yaml  
security:
  session:
    timeout: "24h"

Configuration Templating

Use environment variable substitution in config files:

database:
  path: "${DATABASE_PATH:-fuel_stops.db}"

server:
  port: ${PORT:-8081}

This documentation provides comprehensive coverage of the TankStopp configuration system. For additional questions or advanced use cases, refer to the Viper documentation or check the application source code.