.env.example

# =============================================================================
# Environment Configuration Template
# Copy to .env and configure for your environment
# NEVER commit .env with real credentials
# =============================================================================

# =============================================================================
# Application Settings
# =============================================================================
APP_NAME="My API"                    # Application display name
APP_ENV=development                  # Environment: development, staging, production
DEBUG=false                          # Enable debug mode (NEVER true in production)
VERSION="0.1.0"                      # API version
API_PREFIX="/api/v1"                 # API route prefix

# =============================================================================
# Database Settings
# =============================================================================
# Format: postgresql+asyncpg://user:password@host:port/database
DATABASE__URL=postgresql+asyncpg://user:password@localhost:5432/mydb
DATABASE__POOL_SIZE=5                # Connection pool size (1-100, prod: 10-20)
DATABASE__MAX_OVERFLOW=10            # Max overflow connections (0-100)
DATABASE__ECHO=false                 # Echo SQL statements (NEVER true in production)
DATABASE__POOL_RECYCLE=3600          # Recycle connections after N seconds

# =============================================================================
# Security Settings (CRITICAL)
# =============================================================================
# REQUIRED: Secret key for JWT signing
# Generate with: python -c "import secrets; print(secrets.token_urlsafe(64))"
# Minimum 32 characters, recommended 64+
SECURITY__SECRET_KEY=CHANGE_ME_GENERATE_WITH_SECRETS_TOKEN_URLSAFE_64

# CORS allowed origins (JSON array format)
# Production: specify exact domains, never use "*"
SECURITY__CORS_ORIGINS=["http://localhost:3000"]

# Rate limiting (format: "requests/period")
# Examples: "100/minute", "1000/hour", "10000/day"
SECURITY__RATE_LIMIT=100/minute

# JWT settings
SECURITY__ALGORITHM=HS256            # HS256, HS384, HS512, RS256
SECURITY__ACCESS_TOKEN_EXPIRE_MINUTES=30
SECURITY__REFRESH_TOKEN_EXPIRE_DAYS=7

# =============================================================================
# Redis Settings (Token Storage & Cache)
# =============================================================================
# Redis connection URL (with optional password)
# Format: redis://[:password]@host:port/db
REDIS__URL=redis://localhost:6379/0

# Enable Redis for token storage (uses in-memory if disabled)
REDIS__ENABLED=false

# Default token TTL in seconds (7 days = 604800)
REDIS__TOKEN_TTL=604800

# Connection pool settings
REDIS__MAX_CONNECTIONS=10

# =============================================================================
# Observability Settings
# =============================================================================
# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
# Production: INFO or WARNING recommended
OBSERVABILITY__LOG_LEVEL=INFO

# Log format: json (production) or console (development)
OBSERVABILITY__LOG_FORMAT=json

# OpenTelemetry collector endpoint (optional)
# Example: http://localhost:4317
OBSERVABILITY__OTLP_ENDPOINT=

# Service name for distributed tracing
OBSERVABILITY__SERVICE_NAME=my-api

# Enable/disable features
OBSERVABILITY__ENABLE_TRACING=true
OBSERVABILITY__ENABLE_METRICS=true

# =============================================================================
# Kafka Settings (Optional - for event streaming)
# =============================================================================
# Enable Kafka producer for domain events
OBSERVABILITY__KAFKA_ENABLED=false

# Kafka broker addresses (comma-separated for multiple brokers)
OBSERVABILITY__KAFKA_BOOTSTRAP_SERVERS=["localhost:29092"]

# Client identifier for Kafka connections
OBSERVABILITY__KAFKA_CLIENT_ID=python-api-base

# Consumer group ID
OBSERVABILITY__KAFKA_GROUP_ID=python-api-base-group

# Security protocol: PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL
OBSERVABILITY__KAFKA_SECURITY_PROTOCOL=PLAINTEXT

# SASL settings (required if using SASL_* security protocol)
# OBSERVABILITY__KAFKA_SASL_MECHANISM=PLAIN
# OBSERVABILITY__KAFKA_SASL_USERNAME=
# OBSERVABILITY__KAFKA_SASL_PASSWORD=

# =============================================================================
# Feature Flags (Optional)
# =============================================================================
FEATURES__ENABLE_GRAPHQL=false
FEATURES__ENABLE_WEBSOCKETS=false
FEATURES__ENABLE_CACHE=true

# =============================================================================
# Email Settings (Optional - for notifications/password reset)
# =============================================================================
EMAIL__SMTP_HOST=smtp.gmail.com
EMAIL__SMTP_PORT=587
EMAIL__SMTP_USER=
EMAIL__SMTP_PASSWORD=
EMAIL__FROM_EMAIL=noreply@example.com
EMAIL__FROM_NAME="My API"
EMAIL__USE_TLS=true

# =============================================================================
# Storage Settings (Optional - for file uploads)
# =============================================================================
STORAGE__TYPE=local              # local, s3, gcs, azure
STORAGE__LOCAL_PATH=./uploads
STORAGE__MAX_FILE_SIZE=10485760  # 10MB in bytes
STORAGE__ALLOWED_EXTENSIONS=jpg,jpeg,png,pdf

# AWS S3 (if STORAGE__TYPE=s3)
STORAGE__S3_BUCKET=
STORAGE__S3_REGION=us-east-1
STORAGE__S3_ACCESS_KEY=
STORAGE__S3_SECRET_KEY=

# =============================================================================
# External Services (Optional)
# =============================================================================
# Sentry for error tracking (production recommended)
SENTRY__DSN=
SENTRY__ENVIRONMENT=development
SENTRY__TRACES_SAMPLE_RATE=0.1   # 10% of transactions

# Slack webhooks for alerts
SLACK__WEBHOOK_URL=
SLACK__CHANNEL=#api-alerts

# =============================================================================
# Performance & Limits
# =============================================================================
# Request timeout in seconds
REQUEST__TIMEOUT=30

# Max request size in MB
REQUEST__MAX_SIZE=10

# Worker settings (if using celery/background jobs)
WORKER__CONCURRENCY=4
WORKER__MAX_TASKS_PER_CHILD=1000

# =============================================================================
# Development Only Settings
# =============================================================================
# Hot reload for development
DEV__AUTO_RELOAD=true

# Profiling
DEV__ENABLE_PROFILING=false

# Query logging
DEV__LOG_QUERIES=false