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!