← Back to Table of Contents

Configuration Guide

This guide covers the configuration options available for the Open Source Site Tracking platform.

Environment Setup Database Configuration Analytics Configuration Security Configuration Performance Configuration Logging Configuration Customization

Environment Setup

Environment Variables

Backend Environment Variables

# Database Configuration
DATABASE_URL=sqlite:///site_tracking.db
# DATABASE_URL=postgresql://user:password@localhost/dbname
# Security Configuration
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-key
JWT_EXPIRATION_HOURS=24
# Application Configuration
DEBUG=False
ENVIRONMENT=production
HOST=0.0.0.0
PORT=8000
# Analytics Configuration
ANALYTICS_ENABLED=True
DATA_RETENTION_DAYS=365
REAL_TIME_PROCESSING=True
# Email Configuration
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password

Frontend Environment Variables

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000
# Application Configuration
NEXT_PUBLIC_APP_NAME=Open Source Site Tracking
NEXT_PUBLIC_APP_VERSION=1.0.0
# Analytics Configuration
NEXT_PUBLIC_TRACKING_ENABLED=True
NEXT_PUBLIC_DEBUG_MODE=False

Configuration Files

Backend Configuration (config.py)

import os
from datetime import timedelta
class Config:
    # Database
    DATABASE_URL = os.environ.get('DATABASE_URL', 'sqlite:///site_tracking.db')
    
    # Security
    SECRET_KEY = os.environ.get('SECRET_KEY', 'dev-secret-key')
    JWT_SECRET_KEY = os.environ.get('JWT_SECRET_KEY', 'jwt-secret-key')
    JWT_EXPIRATION_HOURS = int(os.environ.get('JWT_EXPIRATION_HOURS', '24'))
    
    # Application
    DEBUG = os.environ.get('DEBUG', 'False').lower() == 'true'
    ENVIRONMENT = os.environ.get('ENVIRONMENT', 'development')
    HOST = os.environ.get('HOST', '0.0.0.0')
    PORT = int(os.environ.get('PORT', 8000))
    
    # Analytics
    ANALYTICS_ENABLED = os.environ.get('ANALYTICS_ENABLED', 'True').lower() == 'true'
    DATA_RETENTION_DAYS = int(os.environ.get('DATA_RETENTION_DAYS', 365))
    REAL_TIME_PROCESSING = os.environ.get('REAL_TIME_PROCESSING', 'True').lower() == 'true'
class DevelopmentConfig(Config):
    DEBUG = True
    ENVIRONMENT = 'development'
class ProductionConfig(Config):
    DEBUG = False
    ENVIRONMENT = 'production'
class TestingConfig(Config):
    TESTING = True
    DATABASE_URL = 'sqlite:///:memory:'
config = {
    'development': DevelopmentConfig,
    'production': ProductionConfig,
    'testing': TestingConfig
}

Database Configuration

SQLite Configuration

# SQLite Configuration
DATABASE_URL=sqlite:///site_tracking.db
# SQLite Options
SQLITE_ECHO=False
SQLITE_POOL_SIZE=10
SQLITE_MAX_OVERFLOW=20

PostgreSQL Configuration

# PostgreSQL Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/dbname
# PostgreSQL Options
DB_POOL_SIZE=20
DB_MAX_OVERFLOW=30
DB_POOL_TIMEOUT=30
DB_POOL_RECYCLE=3600

Database Migration

# Migration Configuration
MIGRATION_DIR=migrations
MIGRATION_HISTORY_TABLE=alembic_version
MIGRATION_AUTO_GENERATE=True

Analytics Configuration

Analytics Settings

Setting Default Description
ANALYTICS_ENABLED True Enable/disable analytics processing
DATA_RETENTION_DAYS 365 Days to retain analytics data
REAL_TIME_PROCESSING True Enable real-time data processing
BATCH_SIZE 100 Batch size for data processing
PROCESSING_INTERVAL 5 Processing interval in seconds

Custom Analytics Configuration

# Custom Analytics Config
ANALYTICS_CONFIG = {
    'tracking': {
        'page_views': True,
        'clicks': True,
        'scrolls': True,
        'forms': True,
        'custom_events': True
    },
    'privacy': {
        'respect_do_not_track': True,
        'anonymize_ip': True,
        'cookie_consent': True
    },
    'performance': {
        'sample_rate': 1.0,
        'batch_size': 100,
        'flush_interval': 5000
    }
}

Security Configuration

Security Settings

# Security Configuration
SECURITY_CONFIG = {
    'authentication': {
        'jwt_expiration_hours': 24,
        'refresh_expiration_days': 30,
        'max_login_attempts': 5,
        'lockout_duration_minutes': 15
    },
    'authorization': {
        'rbac_enabled': True,
        'default_role': 'viewer',
        'role_hierarchy': True
    },
    'encryption': {
        'encryption_key': os.environ.get('ENCRYPTION_KEY'),
        'algorithm': 'AES-256-GCM',
        'key_derivation': 'PBKDF2'
    },
    'session': {
        'timeout_minutes': 30,
        'max_sessions_per_user': 5,
        'secure_cookies': True
    }
}

CORS Configuration

# CORS Configuration
CORS_CONFIG = {
    'allowed_origins': ['http://localhost:3000'],
    'allowed_methods': ['GET', 'POST', 'PUT', 'DELETE'],
    'allowed_headers': ['Content-Type', 'Authorization'],
    'expose_headers': ['X-Total-Count'],
    'supports_credentials': True,
    'max_age': 86400
}

Rate Limiting

# Rate Limiting Configuration
RATE_LIMITING = {
    'default': {
        'requests_per_minute': 100,
        'requests_per_hour': 1000,
        'requests_per_day': 10000
    },
    'api': {
        'requests_per_minute': 200,
        'requests_per_hour': 2000,
        'requests_per_day': 20000
    },
    'auth': {
        'requests_per_minute': 10,
        'requests_per_hour': 100,
        'requests_per_day': 1000
    }
}

Performance Configuration

Caching Configuration

# Caching Configuration
CACHE_CONFIG = {
    'type': 'redis',  # or 'memory'
    'redis_url': 'redis://localhost:6379/0',
    'default_timeout': 300,
    'key_prefix': 'site_tracking:',
    'compression': True
}

Connection Pooling

# Connection Pool Configuration
DB_POOL_CONFIG = {
    'pool_size': 20,
    'max_overflow': 30,
    'pool_timeout': 30,
    'pool_recycle': 3600,
    'pool_pre_ping': True
}

Worker Configuration

# Worker Configuration
WORKER_CONFIG = {
    'workers': 4,
    'worker_class': 'uvicorn.workers.UvicornWorker',
    'worker_connections': 1000,
    'max_requests': 1000,
    'max_requests_jitter': 100,
    'preload_app': True
}

Logging Configuration

Logging Setup

# Logging Configuration
LOGGING_CONFIG = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'default': {
            'format': '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
        },
        'detailed': {
            'format': '%(asctime)s - %(name)s - %(levelname)s - %(module)s - %(funcName)s - %(message)s'
        }
    },
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'level': 'INFO',
            'formatter': 'default',
            'stream': 'ext://sys.stdout'
        },
        'file': {
            'class': 'logging.handlers.RotatingFileHandler',
            'level': 'INFO',
            'formatter': 'detailed',
            'filename': 'logs/app.log',
            'maxBytes': 10485760,  # 10MB
            'backupCount': 5
        }
    },
    'loggers': {
        '': {
            'level': 'INFO',
            'handlers': ['console', 'file'],
            'propagate': False
        },
        'uvicorn': {
            'level': 'INFO',
            'handlers': ['console'],
            'propagate': False
        }
    }
}

Log Levels

Level Description Use Case
DEBUG Detailed debugging information Development troubleshooting
INFO General information messages Normal operation
WARNING Warning messages Potential issues
ERROR Error messages Errors that need attention
CRITICAL Critical error messages System failures

Customization

Application Customization

# Application Customization
APP_CONFIG = {
    'name': 'Open Source Site Tracking',
    'version': '1.0.0',
    'description': 'Advanced analytics for open source projects',
    'author': 'AutoBotSolutions',
    'contact': 'support@autobotsolutions.com',
    'license': 'MIT'
}

Feature Flags

# Feature Flags Configuration
FEATURE_FLAGS = {
    'advanced_analytics': True,
    'real_time_processing': True,
    'custom_reports': True,
    'api_v2': False,
    'beta_features': False,
    'experimental_features': False
}

Theme Configuration

# Theme Configuration
THEME_CONFIG = {
    'default_theme': 'dark',
    'available_themes': ['light', 'dark', 'system'],
    'custom_colors': {
        'primary': '#0066cc',
        'secondary': '#6c757d',
        'success': '#28a745',
        'warning': '#ffc107',
        'danger': '#dc3545'
    }
}

Configuration Best Practices

  • Use Environment Variables: Store sensitive data in environment variables
  • Version Control: Commit configuration files but exclude sensitive data
  • Documentation: Document all configuration options
  • Validation: Validate configuration values on startup
  • Defaults: Provide sensible defaults for all options

Configuration Validation

# Configuration Validation
def validate_config():
    required_vars = ['SECRET_KEY', 'DATABASE_URL']
    
    for var in required_vars:
        if not os.environ.get(var):
            raise ValueError(f"Required environment variable {var} is not set")
    
    # Validate database URL
    db_url = os.environ.get('DATABASE_URL')
    if not db_url.startswith(('sqlite://', 'postgresql://', 'mysql://')):
        raise ValueError("Invalid database URL format")
    
    return True