Production-ready FastAPI starter template with authentication, encryption, and modern Python best practices.
- FastAPI 0.128+ - Modern, fast web framework with automatic API documentation
- SQLAlchemy 2.0 - Async ORM with full type safety
- PostgreSQL 17 - Robust relational database with psycopg3 driver
- Alembic - Database migration management with custom configuration
- Pydantic 2 - Data validation and settings management
- OAuth 2.0/OpenID Connect - Authentication via Authlib (Auth0 ready)
- Client-side Encryption - AES-GCM encryption for PII (email, phone)
- Secure Sessions - Signed session cookies with HTTPS-only
- Password Hashing - Argon2 for secure credential storage
- Trusted Host Middleware - CSRF protection
- uv - Ultra-fast Python package manager
- Ruff - Lightning-fast linter and formatter
- ty - Type checker for Python 3.13+
- Structlog - Structured JSON logging for observability
- Typer CLI - Modern CLI for database and server management
- Pre-commit hooks - Automated code quality checks
- Docker Compose - Local development environment
- Multi-stage Docker build - Optimized container images
- Health checks - Built-in endpoint for load balancers
- Request tracking - X-Request-Duration header for monitoring
- GZip compression - Automatic response compression
- Multi-worker support - Horizontal scaling capability
- Python 3.13+
- uv package manager
- Docker and Docker Compose (optional, for containerized deployment)
# Install dependencies
uv sync
# Install pre-commit hooks
uv run pre-commit install# Start development server (with auto-reload)
uv run app start
# Or with custom host/port
SERVER_HOST=0.0.0.0 SERVER_PORT=8080 uv run app startThe API will be available at http://localhost:8000 with documentation at http://localhost:8000/docs.
# Start all services (app + PostgreSQL)
docker compose up
# Run in detached mode
docker compose up -d
# View logs
docker compose logs -f app
# Stop services
docker compose down# Create a new migration
uv run app db revision "add users table"
# Apply migrations
uv run app db up
# Revert last migration
uv run app db down
# Revert to specific revision
uv run app db down <revision_id># Lint and auto-fix issues
uv run ruff check --fix .
# Format code
uv run ruff format .
# Type check
uv run ty check .
# Run all pre-commit hooks
uv run pre-commit run --all-files# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=starter --cov-report=html
# Run specific test file
uv run pytest tests/test_file.py
# Run specific test function
uv run pytest tests/test_file.py::test_function_nameConfiguration is managed through environment variables using Pydantic Settings. See starter/settings.py for available options.
- Automatic validation - Pydantic validates all settings on startup
- Type safety - Full type hints for all configuration values
- Computed properties - Encryption keys derived from APP_SECRET
- Environment-based - Different configs for dev/staging/prod
# Application
APP_NAME=starter
APP_API_VERSION=0.1.0
APP_DOMAIN=localhost:8000
APP_SECRET=your-secret-key-here # Used for encryption and session signing
# Database
DATABASE_URL=postgresql+psycopg://user:pass@localhost:5432/dbname
# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
SERVER_WORKERS=1
# OAuth/Authentication
AUTH_DOMAIN=your-auth0-domain.auth0.com
AUTH_CLIENT_ID=your-client-id
AUTH_CLIENT_SECRET=your-client-secret
AUTH_METADATA_URL=https://your-auth0-domain.auth0.com/.well-known/openid-configuration
# Logging
LOG_LEVEL=info
# Environment
ENVIRONMENT=developmentstarter/
├── app.py # FastAPI application factory
├── cli.py # CLI commands (Typer)
├── settings.py # Pydantic settings
├── di.py # Dependency injection providers
├── database/
│ ├── models.py # SQLAlchemy ORM models
│ ├── types.py # Custom types (EncryptedString, Model base)
│ ├── mixins.py # Reusable mixins (Timestamper, SoftDelete)
│ ├── enums.py # Database enumerations
│ └── migrations/ # Alembic migrations
├── routers/ # API route handlers
│ ├── health.py # Health check endpoint
│ └── auth.py # OAuth authentication endpoints
├── models/ # Pydantic models (API schemas)
│ └── health.py # Health check response schema
├── services/ # Business logic services
│ └── encryption.py # AES-GCM encryption service
└── utils/ # Utility modules
├── logging.py # Structured logging configuration
└── middlewares.py # Custom middleware (request duration)
GET /healthReturns the application health status, version, and timestamp.
GET /auth/loginInitiates OAuth login flow with configured identity provider.
GET /auth/callbackOAuth callback handler that processes authentication response and creates session.
GET /auth/logoutClears user session and redirects to home page.
- Create a new branch for your feature
- Make your changes following the code style guidelines
- Run tests and linters
- Submit a pull request
- Async SQLAlchemy - Non-blocking database operations
- Custom types - EncryptedString for transparent PII encryption
- Reusable mixins - TimestamperMixin (created_at, updated_at), SoftDeleteMixin
- UUID primary keys - All models use UUIDs by default
- Automatic table naming - Snake_case convention from class names
- Field-level encryption - AES-GCM encryption for sensitive data
- Deterministic key derivation - Encryption keys from APP_SECRET + salt
- Secure sessions - HTTPS-only cookies with secret key signing
- OAuth 2.0/OIDC - Standards-based authentication
- CORS & Trusted Hosts - Protection against common web attacks
- Structured logging - JSON logs with request context
- Request duration tracking - X-Request-Duration header on all responses
- Health check endpoint - For load balancer integration
- Automatic middleware ordering - Request tracking, compression, CORS, sessions
MIT