311 lines
7.5 KiB
Markdown
311 lines
7.5 KiB
Markdown
# 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](environment-variables.md)** - Configure through `.env` files
|
|
- **[Settings Classes](settings-classes.md)** - Python-based configuration management
|
|
- **[Docker Setup](docker-setup.md)** - Container and service configuration
|
|
- **[Environment-Specific](environment-specific.md)** - Development, staging, and production configs
|
|
|
|
## Quick Start
|
|
|
|
The boilerplate uses environment variables as the primary configuration method:
|
|
|
|
```bash
|
|
# Copy the example file
|
|
cp src/.env.example src/.env
|
|
|
|
# Edit with your values
|
|
nano src/.env
|
|
```
|
|
|
|
Essential variables to set:
|
|
|
|
```env
|
|
# 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:
|
|
```env
|
|
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:
|
|
```python
|
|
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:
|
|
```python
|
|
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
|
|
```env
|
|
SECRET_KEY="your-super-secret-key-here"
|
|
ALGORITHM="HS256"
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
|
REFRESH_TOKEN_EXPIRE_DAYS=7
|
|
```
|
|
|
|
### Database Configuration
|
|
```env
|
|
POSTGRES_USER="your_user"
|
|
POSTGRES_PASSWORD="your_password"
|
|
POSTGRES_SERVER="localhost"
|
|
POSTGRES_PORT=5432
|
|
POSTGRES_DB="your_database"
|
|
```
|
|
|
|
### Redis Services
|
|
```env
|
|
# 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
|
|
```env
|
|
APP_NAME="Your App Name"
|
|
APP_VERSION="1.0.0"
|
|
ENVIRONMENT="local" # local, staging, production
|
|
DEBUG=true
|
|
```
|
|
|
|
### Rate Limiting
|
|
```env
|
|
DEFAULT_RATE_LIMIT_LIMIT=100
|
|
DEFAULT_RATE_LIMIT_PERIOD=3600 # 1 hour in seconds
|
|
```
|
|
|
|
### Admin User
|
|
```env
|
|
ADMIN_NAME="Admin User"
|
|
ADMIN_EMAIL="admin@example.com"
|
|
ADMIN_USERNAME="admin"
|
|
ADMIN_PASSWORD="secure_password"
|
|
```
|
|
|
|
## Environment-Specific Configurations
|
|
|
|
### Development
|
|
```env
|
|
ENVIRONMENT="local"
|
|
DEBUG=true
|
|
POSTGRES_SERVER="localhost"
|
|
REDIS_CACHE_HOST="localhost"
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=60 # Longer for development
|
|
```
|
|
|
|
### Staging
|
|
```env
|
|
ENVIRONMENT="staging"
|
|
DEBUG=false
|
|
POSTGRES_SERVER="staging-db.example.com"
|
|
REDIS_CACHE_HOST="staging-redis.example.com"
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
|
```
|
|
|
|
### Production
|
|
```env
|
|
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:
|
|
|
|
```yaml
|
|
services:
|
|
web:
|
|
env_file:
|
|
- ./src/.env
|
|
environment:
|
|
- DATABASE_URL=postgresql+asyncpg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
|
|
```
|
|
|
|
### Service Overview
|
|
```yaml
|
|
services:
|
|
web: # FastAPI application
|
|
db: # PostgreSQL database
|
|
redis: # Redis for caching/queues
|
|
worker: # Background task worker
|
|
```
|
|
|
|
## Common Configuration Patterns
|
|
|
|
### Feature Flags
|
|
```python
|
|
# 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
|
|
```python
|
|
@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
|
|
```python
|
|
@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
|
|
```bash
|
|
# Generate a secure secret key
|
|
openssl rand -hex 32
|
|
```
|
|
|
|
### Test Configuration
|
|
```python
|
|
# 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
|
|
```bash
|
|
# 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](environment-variables.md)** - Start here
|
|
Learn about all available environment variables, their purposes, and recommended values for different environments.
|
|
|
|
### 2. **[Settings Classes](settings-classes.md)** - Validation layer
|
|
Understand how Python settings classes validate and structure your configuration with type hints and validation rules.
|
|
|
|
### 3. **[Docker Setup](docker-setup.md)** - Container configuration
|
|
Configure Docker Compose services, networking, and environment-specific overrides.
|
|
|
|
### 4. **[Environment-Specific](environment-specific.md)** - 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:
|
|
|
|
1. **[Environment Variables](environment-variables.md)** - Complete reference and examples
|
|
2. **[Settings Classes](settings-classes.md)** - Custom validation and organization
|
|
3. **[Docker Setup](docker-setup.md)** - Service configuration and overrides
|
|
4. **[Environment-Specific](environment-specific.md)** - Production-ready configurations
|
|
|
|
The boilerplate provides sensible defaults - just customize what you need! |