Configuration Reference

Complete reference for all configuration options and environment variables.

Environment Variables

Application Settings

Variable	Type	Default	Description
APP_NAME	string	"2Sigma Backend"	Application name
APP_VERSION	string	"1.0.0"	Application version
DEBUG	boolean	False	Enable debug mode
ENVIRONMENT	string	"production"	Environment name (production/development/staging)
API_V1_PREFIX	string	"/api/v1"	API route prefix

Logging Configuration

Variable	Type	Default	Description
LOG_LEVEL	string	"INFO"	Log level (DEBUG, INFO, WARNING, ERROR)
LOG_FORMAT	string	"json"	Log format: "json" for production, "text" for development
ENABLE_ACCESS_LOG	boolean	True	Enable HTTP request logging
SLOW_QUERY_THRESHOLD_MS	integer	1000	Log DB queries slower than this (milliseconds)

File Logging

Variable	Type	Default	Description
LOG_FILE_ENABLED	boolean	True	Enable logging to files
LOG_DIR	string	"logs"	Directory for log files
LOG_FILE_MAX_BYTES	integer	10485760	Max log file size before rotation (10MB)
LOG_FILE_BACKUP_COUNT	integer	25	Number of rotated log files to keep

Example:

LOG_LEVEL=INFO
LOG_FORMAT=json          # "json" for production, "text" for development
ENABLE_ACCESS_LOG=True
SLOW_QUERY_THRESHOLD_MS=1000
LOG_FILE_ENABLED=True
LOG_DIR=logs
LOG_FILE_MAX_BYTES=10485760   # 10MB
LOG_FILE_BACKUP_COUNT=25      # ~260MB max disk usage

Metrics Configuration

Variable	Type	Default	Description
ENABLE_METRICS	boolean	True	Enable Prometheus metrics endpoint at /metrics

Database Configuration

Variable	Type	Required	Description
DATABASE_URL	string	Yes	Async PostgreSQL connection string
DATABASE_ECHO	boolean	No (False)	Log all SQL queries

DATABASE_URL Format:

postgresql+asyncpg://username:password@host:port/database

Example:

DATABASE_URL=postgresql+asyncpg://ai_tutor_user:secret@localhost:5432/ai_tutor_dev

Security Settings

Variable	Type	Required	Description
SECRET_KEY	string	Yes	JWT signing key (keep secret!)
ALGORITHM	string	No ("HS256")	JWT signing algorithm
ACCESS_TOKEN_EXPIRE_MINUTES	integer	No (30)	Access token lifetime in minutes
REFRESH_TOKEN_EXPIRE_DAYS	integer	No (7)	Refresh token lifetime in days

Security

• Use a strong SECRET_KEY in production (32+ random characters)
• Generate with: openssl rand -hex 32
• Never commit .env files or expose the secret key

Example:

SECRET_KEY=09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

CORS Configuration

Variable	Type	Required	Description
BACKEND_CORS_ORIGINS	JSON array or comma-separated	No	Allowed CORS origins

Examples:

# JSON array format
BACKEND_CORS_ORIGINS=["http://localhost:3000", "https://app.example.com"]

# Comma-separated format  
BACKEND_CORS_ORIGINS=http://localhost:3000,https://app.example.com

LLM Provider Configuration

Variable	Type	Required	Description
LLM_PROVIDER	string	Yes	LLM provider: "anthropic" or "aws_bedrock"
LLM_MAX_TOKENS	integer	No (4096)	Maximum tokens in LLM responses

Anthropic API (when LLM_PROVIDER=anthropic)

Variable	Type	Required	Description
ANTHROPIC_API_KEY	string	Yes	Anthropic API key
ANTHROPIC_MODEL	string	No	Claude model name

Default model: claude-3-5-sonnet-20241022

Example:

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-api03-...
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
LLM_MAX_TOKENS=4096

AWS Bedrock (when LLM_PROVIDER=aws_bedrock)

Variable	Type	Required	Description
AWS_BEDROCK_MODEL_ID	string	No	Bedrock model identifier
AWS_REGION	string	No ("eu-west-2")	AWS region
AWS_ACCESS_KEY_ID	string	No*	AWS access key
AWS_SECRET_ACCESS_KEY	string	No*	AWS secret key
AWS_SESSION_TOKEN	string	No	AWS session token (temporary credentials)

*Can be set via environment variables OR stored in database via admin endpoint.

Default model: anthropic.claude-3-5-sonnet-20241022-v2:0

Example:

LLM_PROVIDER=aws_bedrock
AWS_BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
AWS_REGION=eu-west-2
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
LLM_MAX_TOKENS=4096

Langfuse Observability (Optional)

Variable	Type	Required	Description
LANGFUSE_PUBLIC_KEY	string	No	Langfuse public API key
LANGFUSE_SECRET_KEY	string	No	Langfuse secret API key
LANGFUSE_HOST	string	No	Langfuse host (for self-hosted)

Example:

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
# LANGFUSE_HOST=https://cloud.langfuse.com  # Optional, defaults to cloud

Configuration File (.env)

Development Example

# .env (development)
APP_NAME="2Sigma Backend"
DEBUG=true
ENVIRONMENT=development

# Logging (human-readable for development)
LOG_LEVEL=DEBUG
LOG_FORMAT=text
ENABLE_ACCESS_LOG=True
LOG_FILE_ENABLED=True
LOG_DIR=logs

DATABASE_URL=postgresql+asyncpg://ai_tutor_user:dev_password@localhost:5432/ai_tutor_dev
DATABASE_ECHO=false

SECRET_KEY=dev-secret-key-replace-in-production
ACCESS_TOKEN_EXPIRE_MINUTES=10080  # 7 days for convenience
REFRESH_TOKEN_EXPIRE_DAYS=30

BACKEND_CORS_ORIGINS=["http://localhost:3000", "http://localhost:8000"]

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
LLM_MAX_TOKENS=4096

Production Example

# .env (production)
APP_NAME="2Sigma Backend"
DEBUG=false
ENVIRONMENT=production

# Logging (JSON for log aggregators)
LOG_LEVEL=INFO
LOG_FORMAT=json
ENABLE_ACCESS_LOG=True
SLOW_QUERY_THRESHOLD_MS=1000
LOG_FILE_ENABLED=True
LOG_DIR=logs
LOG_FILE_MAX_BYTES=10485760
LOG_FILE_BACKUP_COUNT=25

DATABASE_URL=postgresql+asyncpg://prod_user:strong_password@db.example.com:5432/ai_tutor_prod
DATABASE_ECHO=false

SECRET_KEY=09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

BACKEND_CORS_ORIGINS=["https://app.example.com"]

LLM_PROVIDER=aws_bedrock
AWS_BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
AWS_REGION=eu-west-2
# AWS credentials stored in database via admin endpoint

LANGFUSE_PUBLIC_KEY=pk-lf-production-key
LANGFUSE_SECRET_KEY=sk-lf-production-secret

Loading Configuration

Configuration is loaded via app/config.py using Pydantic Settings:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    APP_NAME: str = "2Sigma Backend"
    DEBUG: bool = False
    DATABASE_URL: str  # Required
    SECRET_KEY: str    # Required
    # ... other settings

    class Config:
        env_file = ".env"
        case_sensitive = True

settings = Settings()

Accessing Configuration

In your code:

from app.config import settings

# Access settings
print(settings.APP_NAME)
print(settings.DATABASE_URL)
print(settings.DEBUG)

Environment-Specific Configurations

Multiple Environment Files

# Use different .env files
cp .env.example .env.development
cp .env.example .env.production

# Load specific file
export ENV_FILE=.env.production
python -c "from dotenv import load_dotenv; load_dotenv('.env.production')"

Docker Environment Variables

# docker-compose.yml
version: '3.8'
services:
  backend:
    build: .
    environment:
      - DATABASE_URL=postgresql+asyncpg://user:pass@db:5432/ai_tutor
      - SECRET_KEY=${SECRET_KEY}
      - LLM_PROVIDER=anthropic
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    env_file:
      - .env.production

Configuration Validation

Pydantic validates configuration on startup. Invalid values cause startup errors:

# Missing required field
ValidationError: 1 validation error for Settings
DATABASE_URL
  field required (type=value_error.missing)

# Invalid type
ValidationError: 1 validation error for Settings
DEBUG
  value could not be parsed to a boolean (type=type_error.bool)

AWS Credentials Management

Option 1: Environment Variables

Set credentials in .env:

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=optional-session-token

Option 2: Database Storage (Recommended for Production)

Use the admin API to store encrypted credentials:

curl -X POST http://localhost:8000/api/v1/admin/aws-credentials \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "aws_session_token": "optional-token"
  }'

Credentials are encrypted in the system_settings table.

Priority

1. Database credentials (if present)
2. Environment variables
3. AWS default credential chain (IAM roles, etc.)

Troubleshooting

Configuration Not Loading

Issue: Changes to .env not reflected

Solutions: - Restart the server (.env loaded at startup only) - Check file is named exactly .env (not .env.txt) - Verify file is in project root (same directory as main.py)

Database Connection Errors

Issue: connection refused or authentication failed

Solutions: - Verify PostgreSQL is running: pg_isready - Check DATABASE_URL format (use postgresql+asyncpg://) - Test connection: psql $DATABASE_URL - Ensure user has database permissions

JWT Token Issues

Issue: Tokens expire immediately or signature invalid

Solutions: - Verify SECRET_KEY is set and consistent - Check ACCESS_TOKEN_EXPIRE_MINUTES value - Don't change SECRET_KEY without invalidating existing tokens - Ensure server clock is accurate

CORS Errors

Issue: Browser blocking requests from frontend

Solutions: - Add frontend URL to BACKEND_CORS_ORIGINS - Use exact URL (include protocol and port) - Check for trailing slashes - Restart server after changes

Best Practices

1. Never commit .env files - Use .env.example for templates
2. Use strong secrets - Generate with openssl rand -hex 32
3. Different secrets per environment - Don't reuse production secrets in dev
4. Minimize DEBUG in production - Set DEBUG=false
5. Use environment variables in CI/CD - Don't store secrets in code
6. Rotate credentials regularly - Especially for production
7. Use database credential storage - For dynamic AWS credentials

Next Steps

• Getting Started Tutorial
• Local Development Guide
• API Reference