Configuration¶

Learn how to configure your FastAPI Boilerplate application for different environments and use cases. Everything is configured through environment variables and Python settings classes.

What You'll Learn¶

Environment Variables - Configure through .env files
Settings Classes - Python-based configuration management
Docker Setup - Container and service configuration
Environment-Specific - Development, staging, and production configs

Quick Start¶

The boilerplate uses environment variables as the primary configuration method:

# Copy the example file
cp src/.env.example src/.env

# Edit with your values
nano src/.env

Essential variables to set:

# Application
APP_NAME="My FastAPI App"
SECRET_KEY="your-super-secret-key-here"

# Database
POSTGRES_USER="your_user"
POSTGRES_PASSWORD="your_password"
POSTGRES_DB="your_database"

# Admin Account
ADMIN_EMAIL="admin@example.com"
ADMIN_PASSWORD="secure_password"

Configuration Architecture¶

The configuration system has three layers:

Environment Variables (.env files)
         ↓
Settings Classes (Python validation)
         ↓
Application Configuration (Runtime)

Layer 1: Environment Variables¶

Primary configuration through .env files:

POSTGRES_USER="myuser"
POSTGRES_PASSWORD="mypassword"
REDIS_CACHE_HOST="localhost"
SECRET_KEY="your-secret-key"

Layer 2: Settings Classes¶

Python classes that validate and structure configuration:

class PostgresSettings(BaseSettings):
    POSTGRES_USER: str
    POSTGRES_PASSWORD: str = Field(min_length=8)
    POSTGRES_SERVER: str = "localhost"
    POSTGRES_PORT: int = 5432
    POSTGRES_DB: str

Layer 3: Application Use¶

Configuration injected throughout the application:

from app.core.config import settings

# Use anywhere in your code
DATABASE_URL = f"postgresql+asyncpg://{settings.POSTGRES_USER}:{settings.POSTGRES_PASSWORD}@{settings.POSTGRES_SERVER}:{settings.POSTGRES_PORT}/{settings.POSTGRES_DB}"

Key Configuration Areas¶

Security Settings¶

SECRET_KEY="your-super-secret-key-here"
ALGORITHM="HS256"
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

Database Configuration¶

POSTGRES_USER="your_user"
POSTGRES_PASSWORD="your_password"
POSTGRES_SERVER="localhost"
POSTGRES_PORT=5432
POSTGRES_DB="your_database"

Redis Services¶

# Cache
REDIS_CACHE_HOST="localhost"
REDIS_CACHE_PORT=6379

# Background jobs
REDIS_QUEUE_HOST="localhost"
REDIS_QUEUE_PORT=6379

# Rate limiting  
REDIS_RATE_LIMIT_HOST="localhost"
REDIS_RATE_LIMIT_PORT=6379

Application Settings¶

APP_NAME="Your App Name"
APP_VERSION="1.0.0"
ENVIRONMENT="local"  # local, staging, production
DEBUG=true

Rate Limiting¶

DEFAULT_RATE_LIMIT_LIMIT=100
DEFAULT_RATE_LIMIT_PERIOD=3600  # 1 hour in seconds

Admin User¶

ADMIN_NAME="Admin User"
ADMIN_EMAIL="admin@example.com"
ADMIN_USERNAME="admin"
ADMIN_PASSWORD="secure_password"

Environment-Specific Configurations¶

Development¶

ENVIRONMENT="local"
DEBUG=true
POSTGRES_SERVER="localhost"
REDIS_CACHE_HOST="localhost"
ACCESS_TOKEN_EXPIRE_MINUTES=60  # Longer for development

Staging¶

ENVIRONMENT="staging"
DEBUG=false
POSTGRES_SERVER="staging-db.example.com"
REDIS_CACHE_HOST="staging-redis.example.com"
ACCESS_TOKEN_EXPIRE_MINUTES=30

Production¶

ENVIRONMENT="production"
DEBUG=false
POSTGRES_SERVER="prod-db.example.com"
REDIS_CACHE_HOST="prod-redis.example.com"
ACCESS_TOKEN_EXPIRE_MINUTES=15
# Use custom ports for security
POSTGRES_PORT=5433
REDIS_CACHE_PORT=6380

Docker Configuration¶

Basic Setup¶

Docker Compose automatically loads your .env file:

services:
  web:
    env_file:
      - ./src/.env
    environment:
      - DATABASE_URL=postgresql+asyncpg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}

Service Overview¶

services:
  web:          # FastAPI application
  db:           # PostgreSQL database  
  redis:        # Redis for caching/queues
  worker:       # Background task worker

Common Configuration Patterns¶

Feature Flags¶

# In settings class
class FeatureSettings(BaseSettings):
    ENABLE_CACHING: bool = True
    ENABLE_ANALYTICS: bool = False
    ENABLE_BACKGROUND_JOBS: bool = True

# Use in code
if settings.ENABLE_CACHING:
    cache_result = await get_from_cache(key)

Environment Detection¶

@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui():
    if settings.ENVIRONMENT == "production":
        raise HTTPException(404, "Documentation not available")
    return get_swagger_ui_html(openapi_url="/openapi.json")

Health Checks¶

@app.get("/health")
async def health_check():
    return {
        "status": "healthy",
        "environment": settings.ENVIRONMENT,
        "version": settings.APP_VERSION,
        "database": await check_database_health(),
        "redis": await check_redis_health()
    }

Quick Configuration Tasks¶

Generate Secret Key¶

# Generate a secure secret key
openssl rand -hex 32

Test Configuration¶

# test_config.py
from app.core.config import settings

print(f"App: {settings.APP_NAME}")
print(f"Environment: {settings.ENVIRONMENT}")
print(f"Database: {settings.POSTGRES_DB}")

Environment File Templates¶

# Development
cp src/.env.example src/.env.development

# Staging  
cp src/.env.example src/.env.staging

# Production
cp src/.env.example src/.env.production

Best Practices¶

Security¶

Never commit .env files to version control
Use different secret keys for each environment
Disable debug mode in production
Use secure passwords and keys

Performance¶

Configure appropriate connection pool sizes
Set reasonable token expiration times
Use Redis for caching in production
Configure proper rate limits

Maintenance¶

Document all custom environment variables
Use validation in settings classes
Test configurations in staging first
Monitor configuration changes

Testing¶

Use separate test environment variables
Mock external services in tests
Validate configuration on startup
Test with different environment combinations

Getting Started¶

Follow this path to configure your application:

1. Environment Variables - Start here¶

Learn about all available environment variables, their purposes, and recommended values for different environments.

2. Settings Classes - Validation layer¶

Understand how Python settings classes validate and structure your configuration with type hints and validation rules.

3. Docker Setup - Container configuration¶

Configure Docker Compose services, networking, and environment-specific overrides.

4. Environment-Specific - Deployment configs¶

Set up configuration for development, staging, and production environments with best practices.

What's Next¶

Each guide provides practical examples and copy-paste configurations:

Environment Variables - Complete reference and examples
Settings Classes - Custom validation and organization
Docker Setup - Service configuration and overrides
Environment-Specific - Production-ready configurations

The boilerplate provides sensible defaults - just customize what you need!