.env.example

# Database Configuration
# ====================
# These environment variables are required for the trackers application
# to connect to the PostgreSQL database.

# Clever Cloud PostgreSQL Addon Variables (Production)
# ====================================================
# These are automatically set by Clever Cloud when you add a PostgreSQL addon

# PostgreSQL server host
POSTGRESQL_ADDON_HOST=localhost

# Database username
POSTGRESQL_ADDON_USER=postgres

# Database password
POSTGRESQL_ADDON_PASSWORD=postgres

# Database name
POSTGRESQL_ADDON_DB=trackers

# Database port
POSTGRESQL_ADDON_PORT=5432


# Alternative Local Development Variables (Fallback)
# ==================================================
# These can be used for local development if you prefer the old format
# The application will use Clever Cloud variables first, then fall back to these

# PostgreSQL server host
# For local development with Docker: localhost
# For Docker Compose services: postgres-test
# DB_HOST=localhost

# Database username
# Default PostgreSQL user in docker-compose.test.yml: postgres
# DB_USER=postgres

# Database password
# Default PostgreSQL password in docker-compose.test.yml: postgres
# DB_PASSWORD=postgres

# Database name
# The application will use this as the base database name
# Test database will automatically append "_test" (e.g., trackers_test)
# DB_NAME=trackers

# Database port (optional, defaults to 5432)
# DB_PORT=5432

# Database SSL mode (optional, defaults to auto)
# Values: disable, allow, prefer, require, verify-ca, verify-full, auto
# - auto: automatically detects production (require) vs development (prefer)
# - disable: no SSL connection
# - prefer: use SSL if available, but don't require it (good for local dev)
# - require: require SSL connection (good for production)
# DB_SSL_MODE=auto


# Flask Application Configuration
# ===============================
# Optional Flask configuration variables

# Flask server host (default: 0.0.0.0)
FLASK_HOST=0.0.0.0

# Flask server port (default: 5000)
FLASK_PORT=5000

# Flask debug mode (default: true)
# Set to false for production
FLASK_DEBUG=true

# Flask environment (development, staging, production)
FLASK_ENV=development


# Google OAuth Configuration
# ===========================
# Configure Google OAuth 2.0 authentication

# Google OAuth Client ID (required)
# Get this from Google Cloud Console > APIs & Services > Credentials
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com

# Google OAuth Client Secret (required)
# Get this from Google Cloud Console > APIs & Services > Credentials
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Google OAuth Redirect URI (required)
# Must match exactly what's configured in Google Cloud Console
# For development: http://localhost:5000/auth/google/callback
# For production: https://your-domain.com/auth/google/callback
GOOGLE_REDIRECT_URI=http://localhost:5000/auth/google/callback


# External API Configuration for Job Scheduling
# ==============================================
# Configure API keys for external data sources used by automated jobs

# Alpha Vantage API Key (for stock price jobs)
# Get this from https://www.alphavantage.co/support/#api-key
# Required for stock job providers to fetch real-time and historical stock data
ALPHA_VANTAGE_API_KEY=your-alpha-vantage-api-key-here

# Other external API keys can be added here as needed
# YAHOO_FINANCE_API_KEY=your-yahoo-finance-key
# IEX_CLOUD_API_KEY=your-iex-cloud-key


# API Key Security Configuration
# ==============================
# Configure API key authentication for the application

# General API keys (comma-separated)
# Use this for development or when not using environment-specific keys
# API_KEYS=your-secret-api-key-here,another-key-here

# Environment-specific API keys (recommended for production)
# These take precedence over general API_KEYS
# API_KEYS_DEVELOPMENT=dev-key-1,dev-key-2
# API_KEYS_STAGING=staging-key-1,staging-key-2
# API_KEYS_PRODUCTION=prod-key-1,prod-key-2

# Alternative environment-specific format
# DEVELOPMENT_API_KEYS=dev-key-1,dev-key-2
# STAGING_API_KEYS=staging-key-1,staging-key-2
# PRODUCTION_API_KEYS=prod-key-1,prod-key-2

# Production Security Settings
# ============================

# Enable automatic API key rotation (default: true)
# Set to false to disable key reloading from environment
ENABLE_API_KEY_ROTATION=true

# Key reload interval in seconds (default: 300 = 5 minutes)
# How often to check for updated API keys in environment variables
API_KEY_RELOAD_INTERVAL=300

# Trust proxy headers for IP extraction (auto-enabled in production/staging)
# Set to true if behind reverse proxy or load balancer
TRUST_PROXY_HEADERS=false

# Require HTTPS connections (auto-enabled in production)
# Set to true to reject HTTP requests
REQUIRE_HTTPS=false

# Maximum API key age in hours (optional)
# Set to enforce key rotation policies
# MAX_API_KEY_AGE_HOURS=168

# Route Protection Configuration
# ==============================

# Custom protected routes (comma-separated patterns)
# Default: /api/*,/trackers/*,/tracker-values/*,/add_tracker
# PROTECTED_ROUTES=/api/*,/custom/*

# Custom public routes (comma-separated patterns)  
# Default: /health,/health/*,/status,/ping,/hello
# PUBLIC_ROUTES=/health,/status,/custom-public


# Setup Instructions
# ==================

# 1. Copy this file to .env:
#    cp .env.example .env

# 2. Edit .env with your actual database credentials if different from defaults

# 3. Configure API key authentication:
#    - For development: Set API_KEYS with comma-separated keys
#    - For production: Set environment-specific keys (API_KEYS_PRODUCTION)
#    - Generate secure keys using: scripts/generate-api-key.py

# 4. For Clever Cloud deployment:
#    - The POSTGRESQL_ADDON_* variables are automatically set by Clever Cloud
#    - Set API_KEYS_PRODUCTION in Clever Cloud environment variables
#    - FLASK_ENV will be automatically set to "production"

# 5. For local development with Docker Compose:
#    docker compose -f docker-compose.test.yml up -d
#    
#    Or use the helper script:
#    ./scripts/test-db.sh start

# 6. Run the Flask application:
#    uv run trackers-app
#    
#    Or alternatively:
#    uv run python main.py
#    uv run python run.py

# 7. Run tests:
#    pytest

# 8. Stop the test database when done:
#    docker compose -f docker-compose.test.yml down
#    
#    Or use the helper script:
#    ./scripts/test-db.sh stop


# Test Database Details
# =====================
# The test infrastructure automatically:
# - Creates a test database named {DB_NAME}_test (e.g., trackers_test)
# - Applies all schema definitions from SQLAlchemy models
# - Provides isolated database sessions for each test
# - Rolls back transactions after each test for clean state
# - Preserves the test database after test runs for inspection

# The test database is separate from your development database,
# ensuring tests never interfere with development data.


# Production Deployment Notes
# ===========================

# Environment Detection:
# - The application automatically detects production environments
# - FLASK_ENV=production enables production security features
# - Proxy headers are automatically trusted in production/staging

# Security Features Enabled in Production:
# - HTTPS requirement enforcement
# - Proxy header trust for accurate IP logging
# - Enhanced security metrics logging
# - Automatic key rotation support
# - Production readiness validation

# Load Balancer Compatibility:
# - Supports standard proxy headers (X-Forwarded-For, X-Real-IP, etc.)
# - Handles multiple proxy hops correctly
# - Compatible with Cloudflare, AWS ALB, nginx, Apache

# Horizontal Scaling:
# - Stateless authentication (no server-side sessions)
# - Environment-based configuration (no file dependencies)
# - Thread-safe key reloading
# - Consistent behavior across multiple instances


# Troubleshooting
# ===============

# If you see "MISSING REQUIRED ENVIRONMENT VARIABLES" error:
# - For Clever Cloud: Ensure PostgreSQL addon is properly configured
# - For local development: Ensure you've created a .env file from this template
# - Verify all required variables are set (either POSTGRESQL_ADDON_* or DB_*)
# - Check that the .env file is in the project root directory

# If you see connection errors:
# - For Clever Cloud: Check addon status in Clever Cloud console
# - For local development: Verify PostgreSQL is running
# - Check the database is healthy: docker compose -f docker-compose.test.yml logs
# - Ensure port is not already in use by another PostgreSQL instance

# If you see permission errors:
# - For Clever Cloud: Contact Clever Cloud support
# - For local development: Verify the database user has CREATE DATABASE privileges
# - For Docker setup, the default postgres user has all necessary privileges

# If tests fail with "database already exists" errors:
# - The test infrastructure handles this automatically by dropping and recreating
# - If issues persist, manually clean up: ./scripts/test-db.sh clean

# If API authentication is not working:
# - Check that API_KEYS or environment-specific keys are set
# - Verify keys meet minimum security requirements (16+ characters)
# - Check application logs for security system initialization messages
# - Test with curl: curl -H "Authorization: Bearer your-key" http://localhost:5000/api/trackers

# If behind reverse proxy/load balancer:
# - Set TRUST_PROXY_HEADERS=true
# - Verify proxy is sending correct headers (X-Forwarded-For, etc.)
# - Check logs for accurate IP addresses
# - For production, proxy headers are automatically trusted