Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

FastAPI Backend Base

A production-oriented FastAPI backend base with vertical-slice modules, async SQLAlchemy, server-side authentication, API keys, caching, rate limiting, Taskiq workers, Prometheus metrics, OpenTelemetry tracing, Docker, Kubernetes, and Helm.

This repository is intended to be a clean backend foundation for long-lived products. It keeps the stronger modular architecture, tests, authentication, CRUD, admin, and Docker layout from the source base, then adds the strongest production/deployment pieces: Kubernetes manifests, Helm chart, health probes, metrics, and tracing.

What You Get

  • FastAPI application factory with environment-aware settings.
  • Vertical-slice feature modules under backend/src/modules.
  • Async PostgreSQL with SQLAlchemy 2.0 and Alembic.
  • FastCRUD-powered CRUD services and pagination patterns.
  • Session authentication, CSRF, OAuth hooks, and API key module.
  • SQLAdmin admin interface.
  • Redis or Memcached cache provider.
  • Redis or Memcached rate limiter provider.
  • Taskiq background workers with Redis or RabbitMQ brokers.
  • Structured logging and correlation IDs.
  • Prometheus /metrics endpoint.
  • OpenTelemetry setup for FastAPI, SQLAlchemy, Redis, and HTTPX.
  • Docker multi-stage build for dev, migration, and production.
  • bp CLI for Docker Compose generation.
  • Kustomize manifests for development, staging, and production.
  • Helm chart with optional ingress, HPA, migration job, and ServiceMonitor.

Repository Layout

.
├── backend/
│   ├── src/
│   │   ├── interfaces/
│   │   │   ├── main.py              # FastAPI app instance and health endpoints
│   │   │   ├── api/                 # API router composition
│   │   │   └── admin/               # SQLAdmin setup
│   │   ├── modules/
│   │   │   ├── user/                # user routes, schemas, model, CRUD, service
│   │   │   ├── tier/                # user tier module
│   │   │   ├── rate_limit/          # rate-limit rules module
│   │   │   ├── api_keys/            # API key module
│   │   │   └── common/              # shared schemas, errors, utilities
│   │   └── infrastructure/
│   │       ├── app_factory.py       # app creation, middleware, lifespan
│   │       ├── auth/                # auth setup and dependencies
│   │       ├── cache/               # cache providers/backends/decorator
│   │       ├── config/              # environment settings
│   │       ├── database/            # async engine/session/base model
│   │       ├── logging/             # structured logging
│   │       ├── observability/       # Prometheus and OpenTelemetry
│   │       ├── rate_limit/          # global rate-limit middleware/provider
│   │       ├── security/            # production security validator
│   │       └── taskiq/              # task broker and worker entrypoint
│   ├── migrations/                  # Alembic migrations
│   ├── tests/                       # unit and integration tests
│   ├── Dockerfile                   # dev, migrate, prod targets
│   └── .env.example                 # runtime configuration template
├── cli/                             # bp developer/operator CLI
├── docs/                            # technical documentation
├── k8s/                             # Kustomize manifests
├── helm/fastapi-base/               # Helm chart
├── pyproject.toml                   # uv workspace root
└── uv.lock                          # locked workspace dependencies

Runtime Components

flowchart LR
    Client[Client] --> API[FastAPI API]
    API --> Auth[Session/Auth/CSRF]
    API --> DB[(PostgreSQL)]
    API --> Cache[(Redis or Memcached)]
    API --> RateLimiter[Rate Limiter]
    API --> Metrics[/metrics]
    API --> Admin[SQLAdmin]
    API --> Broker[(Redis or RabbitMQ)]
    Broker --> Worker[Taskiq Worker]
    Worker --> DB
    Worker --> Cache
    API --> OTEL[OTLP Collector]
Loading

Quick Start

1. Install Dependencies

From the repository root:

uv sync --all-packages --all-extras
cp backend/.env.example backend/.env

Edit backend/.env before running the app:

  • Set a strong SECRET_KEY.
  • Set POSTGRES_* for normal local development. The app can also use DATABASE_URL; when present, DATABASE_URL takes priority.
  • Use POSTGRES_SERVER=db when running through Docker Compose, or POSTGRES_SERVER=localhost when running the API directly on your machine.
  • Point CACHE_REDIS_*, RATE_LIMITER_REDIS_*, and TASKIQ_REDIS_* at the Redis instance you are using.
  • For local browser testing without HTTPS, set SESSION_SECURE_COOKIES=false.
  • The settings loader checks /app/.env, then backend/.env, then /.env. In Docker, /app/.env is the common path; in local development, backend/.env is the usual path.

2. Run the API

cd backend
uv run fastapi dev src/interfaces/main.py

Default local endpoints:

  • GET /health
  • GET /health/live
  • GET /health/ready
  • GET /metrics
  • GET /docs
  • GET /redoc
  • GET /openapi.json

In production, API documentation is hidden when ENABLE_DOCS_IN_PRODUCTION=false.

3. Run a Taskiq Worker

In a second terminal:

cd backend
uv run taskiq worker infrastructure.taskiq.worker:default_broker

The worker uses the same environment settings as the API and should be deployed as a separate process/container in production.

Docker Compose

The bp CLI generates Docker Compose stacks.

uv run bp deploy generate local
uv run bp deploy generate prod
uv run bp deploy generate nginx

Then run:

docker compose up --build

Generated stacks include:

  • API container.
  • Taskiq worker container.
  • PostgreSQL.
  • Redis.
  • Migration container for production modes.
  • Optional nginx reverse proxy for nginx mode.

Important: Docker builds use the repository root as build context because the Dockerfile needs both backend/ and the root uv.lock.

Modes:

  • local: development stack with reload-friendly API behavior.
  • prod: single-host production-style stack with API, worker, database, Redis, and migrations.
  • nginx: production-style stack with nginx in front of the API.

Application Startup Flow

flowchart TD
    Start[Process starts] --> ImportMain[Import interfaces/main.py]
    ImportMain --> Settings[Load settings from env/.env]
    Settings --> Security{Production security validation enabled?}
    Security -->|yes| Validate[Validate production secrets, CORS, docs, sessions]
    Security -->|no| Lifespan
    Validate --> Lifespan[App lifespan starts]
    Lifespan --> Threadpool[Configure threadpool tokens]
    Threadpool --> Telemetry[Setup OpenTelemetry if enabled]
    Telemetry --> Tables{CREATE_TABLES_ON_STARTUP?}
    Tables -->|yes| CreateTables[Create tables]
    Tables -->|no| CacheInit
    CreateTables --> CacheInit[Initialize cache provider]
    CacheInit --> RateInit[Initialize rate limiter provider]
    RateInit --> AuthInit[Initialize auth system]
    AuthInit --> Ready[Set initialization_complete]
Loading

Startup notes:

  • Production security validation runs before the application finishes startup when PRODUCTION_SECURITY_VALIDATION_ENABLED=true.
  • CREATE_TABLES_ON_STARTUP=true is convenient for local development, but production should use Alembic migrations and set it to false.
  • initialization_complete is used by readiness checks and rate limiting so traffic is not treated as ready before infrastructure components are initialized.
  • Shutdown closes auth/session resources, cache providers, rate limiter providers, and OpenTelemetry exporters.

Configuration Flow

flowchart TD
    Process[API, worker, migration, or CLI process] --> EnvFile[Load env file]
    EnvFile --> SearchPath["/app/.env, then backend/.env, then /.env"]
    SearchPath --> Settings[Build Settings object]
    Settings --> DirectDB{DATABASE_URL present?}
    DirectDB -->|yes| UseDirect[Use DATABASE_URL]
    DirectDB -->|no| BuildDB[Build URL from POSTGRES_*]
    Settings --> CacheSettings[CACHE_* settings]
    Settings --> RateSettings[RATE_LIMITER_* settings]
    Settings --> TaskSettings[TASKIQ_* settings]
    Settings --> AuthSettings[SECRET_KEY, SESSION_*, CSRF_* settings]
    Settings --> ObservabilitySettings[METRICS_* and OTEL_* settings]
    UseDirect --> Runtime[Runtime components]
    BuildDB --> Runtime
    CacheSettings --> Runtime
    RateSettings --> Runtime
    TaskSettings --> Runtime
    AuthSettings --> Runtime
    ObservabilitySettings --> Runtime
Loading

Configuration rules:

  • Use DATABASE_URL in platforms that already provide a full connection string.
  • Use POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_SERVER, POSTGRES_PORT, and POSTGRES_DB when you want explicit service-name based configuration.
  • Keep CACHE_REDIS_DB, RATE_LIMITER_REDIS_DB, and TASKIQ_REDIS_DB separate when sharing one Redis server.
  • Run uv run bp env validate before production rollout to catch weak secrets and unsafe settings.

HTTP Request Flow

sequenceDiagram
    participant C as Client
    participant M as Middleware Stack
    participant R as API Route
    participant S as Service
    participant D as Database
    participant O as Observability

    C->>M: HTTP request
    M->>O: start metrics/tracing/log context
    M->>M: security headers / CORS / gzip / cache headers
    M->>M: global rate-limit check unless operational path
    M->>R: call route handler
    R->>S: validate input and run business use case
    S->>D: query or mutate data through CRUD/session
    D-->>S: result
    S-->>R: domain result
    R-->>M: response model
    M->>O: record duration/status
    M-->>C: response with headers
Loading

Operational endpoints intentionally bypass rate limiting:

  • /health
  • /health/live
  • /health/ready
  • /docs
  • /redoc
  • /openapi.json
  • the configured metrics endpoint, usually /metrics

The middleware stack is assembled in backend/src/infrastructure/app_factory.py. Request handling is intentionally centralized there so cross-cutting behavior such as security headers, gzip, client cache headers, Prometheus metrics, and global rate limiting is consistent across feature modules.

Authentication Flow

sequenceDiagram
    participant Browser
    participant AuthRoutes as Auth Routes
    participant AuthLib as Auth System
    participant DB as PostgreSQL
    participant SessionStore as Session Store

    Browser->>AuthRoutes: POST /api/v1/auth/login
    AuthRoutes->>AuthLib: validate credentials
    AuthLib->>DB: load user and password hash
    DB-->>AuthLib: user row
    AuthLib->>SessionStore: create server-side session
    AuthLib-->>Browser: Set-Cookie + CSRF token
    Browser->>AuthRoutes: authenticated request with cookie + CSRF header
    AuthRoutes->>AuthLib: resolve current user
    AuthLib->>SessionStore: validate session
    AuthLib->>DB: load current user
    DB-->>AuthRoutes: user context
Loading

Notes:

  • Browser flows use server-side sessions and CSRF protection.
  • API key support lives in backend/src/modules/api_keys.
  • Admin login is separate from normal app login and is controlled by ADMIN_* settings.
  • Session storage can use Redis or in-memory storage through SESSION_BACKEND; Redis is the production-oriented option.
  • Unsafe authenticated browser requests must include the CSRF token when CSRF_ENABLED=true.

API Key Management Flow

sequenceDiagram
    participant User as Authenticated User
    participant Route as /api/v1/api-keys
    participant Service as APIKeyService
    participant DB as PostgreSQL

    User->>Route: POST create key
    Route->>Service: create_api_key(user_id, payload)
    Service->>Service: generate key with prefix and secret
    Service->>Service: hash secret with scrypt
    Service->>DB: store prefix, hash, permissions, limits
    DB-->>Service: created key row
    Service-->>Route: full API key shown once
    Route-->>User: response with api_key
Loading

Important behavior:

  • The full API key is returned only once at creation time.
  • The database stores a prefix plus a scrypt hash, not the raw key.
  • APIKeyService.validate_api_key(...) can validate a key, check permissions, and update last_used_at.
  • APIKeyService.record_usage(...) stores usage records for analytics and billing-style reporting.
  • The module provides lifecycle, validation, permission, and usage primitives. If a product needs every route to accept Authorization: Bearer ... or X-API-Key, add a dedicated dependency or middleware that calls validate_api_key(...) for the relevant resource/action.

Database and Service Flow

flowchart TD
    Route[Route in modules/feature/routes.py] --> Schema[Pydantic schema validation]
    Schema --> Service[Service method]
    Service --> Rules[Business rules and permission checks]
    Rules --> CRUD[FastCRUD object]
    CRUD --> Session[AsyncSession]
    Session --> DB[(PostgreSQL)]
    DB --> Session
    Session --> CRUD
    CRUD --> Service
    Service --> ResponseSchema[Response schema]
    ResponseSchema --> Client[JSON response]
Loading

Guidelines:

  • Routes should stay thin.
  • Put business logic in service.py.
  • Put database query plumbing in crud.py.
  • Define table shape in models.py.
  • Define input/output contracts in schemas.py.
  • Use Alembic migrations for schema changes in production.

Rate Limiting Flow

flowchart TD
    Request[Incoming request] --> Skip{Operational path?}
    Skip -->|yes| Route[Continue to route]
    Skip -->|no| User{request.state.user exists?}
    User -->|yes| Tier[Load user tier]
    User -->|no| IP[Use client IP]
    Tier --> Rule[Load path-specific rate-limit rule]
    Rule --> Key[Build ratelimit key]
    IP --> Key
    Key --> Backend[Redis or Memcached backend]
    Backend --> Limited{Exceeded?}
    Limited -->|yes| Error[Raise 429 RateLimitException]
    Limited -->|no| Headers[Set X-RateLimit headers]
    Headers --> Route
Loading

The global middleware is in:

backend/src/infrastructure/rate_limit/middleware.py

The rule management module is in:

backend/src/modules/rate_limit/

Cache Flow

flowchart TD
    Route[GET route or service] --> Decorator[@cache decorator or provider API]
    Decorator --> Key[Build cache key]
    Key --> Backend[Redis or Memcached]
    Backend --> Hit{Cache hit?}
    Hit -->|yes| Cached[Return cached response]
    Hit -->|no| Compute[Run route/service]
    Compute --> Store[Store result with TTL]
    Store --> Response[Return response]
    Mutation[POST/PUT/PATCH/DELETE] --> Invalidate[Invalidate cache key or pattern]
Loading

Use cache for read-heavy data that can tolerate staleness. Keep writes authoritative in PostgreSQL.

Background Task Flow

sequenceDiagram
    participant API as API Route/Service
    participant Broker as Redis/RabbitMQ Broker
    participant Worker as Taskiq Worker
    participant DB as PostgreSQL
    participant External as External Service

    API->>Broker: enqueue task with .kiq(...)
    API-->>API: return 202 or normal response
    Worker->>Broker: consume task
    Worker->>DB: open task-scoped DB session
    Worker->>External: call email/webhook/export service
    Worker->>DB: persist result/status if needed
Loading

Worker entrypoint:

taskiq worker infrastructure.taskiq.worker:default_broker

Taskiq infrastructure:

backend/src/infrastructure/taskiq/
├── app.py
├── brokers.py
├── deps.py
├── registry.py
└── worker.py

Observability Flow

flowchart LR
    Request[HTTP request] --> MetricsMiddleware[MetricsMiddleware]
    MetricsMiddleware --> Prometheus[/metrics]
    Request --> OTel[OpenTelemetry instrumentation]
    OTel --> Collector[OTLP collector]
    Request --> Logger[Structured logger]
    Logger --> Logs[stdout/log aggregator]
    Health[Health probes] --> Kubernetes[Kubernetes]
Loading

Operational endpoints:

  • /metrics: Prometheus text exposition.
  • /health/live: liveness probe, dependency-free.
  • /health/ready: readiness probe, startup completion plus database check.

Related files:

backend/src/infrastructure/observability/
backend/src/interfaces/main.py
backend/src/infrastructure/logging/

Deployment Flow: Docker

flowchart TD
    Build[Docker build from repo root] --> Requirements[Export dependencies from uv.lock]
    Requirements --> Base[Install runtime dependencies]
    Base --> Dev[dev target]
    Base --> Migrate[migrate target]
    Base --> Prod[prod target]
    Dev --> FastapiDev[fastapi dev with reload]
    Migrate --> Alembic[alembic upgrade head]
    Prod --> FastapiRun[fastapi run with WORKERS]
Loading

Build examples:

docker build -f backend/Dockerfile --target dev -t fastapi-base:dev .
docker build -f backend/Dockerfile --target migrate -t fastapi-base:migrate .
docker build -f backend/Dockerfile --target prod -t fastapi-base:prod .

Docker targets:

  • dev: installs development dependencies, copies tests, and runs fastapi dev.
  • migrate: copies Alembic files and runs alembic upgrade head.
  • prod: runs fastapi run interfaces/main.py with the WORKERS environment variable.

Deployment Flow: Kubernetes with Kustomize

flowchart TD
    Image[Build and push image] --> Overlay[Pick k8s overlay]
    Overlay --> Render[kubectl kustomize]
    Render --> Apply[kubectl apply -k]
    Apply --> API[API Deployment]
    Apply --> Worker[Taskiq Worker Deployment]
    Apply --> Service[ClusterIP Service]
    Apply --> PDB[PodDisruptionBudget]
    API --> Probes[/health/live and /health/ready]
    API --> Metrics[/metrics scrape annotation]
Loading

Commands:

kubectl kustomize k8s/overlays/development
kubectl apply -k k8s/overlays/development
kubectl apply -k k8s/overlays/staging
kubectl apply -k k8s/overlays/production

Kustomize deployment behavior:

  • API pods run the production image and expose port 8000.
  • Worker pods run taskiq worker infrastructure.taskiq.worker:default_broker.
  • Config is split into ConfigMap for non-secret values and Secret for sensitive values.
  • Liveness uses /health/live; readiness uses /health/ready.
  • Prometheus scrape annotations target /metrics.

Kustomize files:

k8s/base/
k8s/overlays/development/
k8s/overlays/staging/
k8s/overlays/production/

Deployment Flow: Helm

flowchart TD
    Values[values.yaml or values-prod.yaml] --> Render[helm template]
    Render --> Install[helm upgrade --install]
    Install --> ConfigMap[ConfigMap]
    Install --> Secret[Secret]
    Install --> API[API Deployment]
    Install --> Worker[Worker Deployment]
    Install --> Optional[Ingress/HPA/ServiceMonitor/Migration Job]
Loading

Render:

helm template fastapi-base helm/fastapi-base
helm template fastapi-base helm/fastapi-base -f helm/fastapi-base/values-prod.yaml

Install or upgrade:

helm upgrade --install fastapi-base helm/fastapi-base \
  --namespace production \
  --create-namespace \
  -f helm/fastapi-base/values-prod.yaml

Helm deployment behavior:

  • values.yaml defines the main production-capable defaults.
  • values-prod.yaml overrides replica counts, log level, docs visibility, and OpenTelemetry production settings.
  • secretEnv contains sensitive runtime values such as SECRET_KEY, POSTGRES_PASSWORD, DATABASE_URL, Redis passwords, admin credentials, and OAuth secrets.
  • Optional templates include Ingress, HPA, migration job, PodDisruptionBudget, and ServiceMonitor.
  • Enable migration.enabled=true when you want Helm to run the Alembic migration job as part of a release.

Important Environment Variables

ENVIRONMENT=production
DEBUG=false
SECRET_KEY=change-me-with-a-strong-secret

POSTGRES_USER=postgres
POSTGRES_PASSWORD=change-me
POSTGRES_DB=postgres
POSTGRES_SERVER=postgres
POSTGRES_PORT=5432
POSTGRES_SYNC_PREFIX=postgresql://
POSTGRES_ASYNC_PREFIX=postgresql+asyncpg://
# Optional. When set, this overrides the POSTGRES_* values above.
DATABASE_URL=postgresql+asyncpg://postgres:change-me@postgres:5432/postgres
CREATE_TABLES_ON_STARTUP=false

CACHE_ENABLED=true
CACHE_BACKEND=redis
CACHE_REDIS_HOST=redis
CACHE_REDIS_PORT=6379
CACHE_REDIS_DB=0
CACHE_REDIS_PASSWORD=

RATE_LIMITER_ENABLED=true
RATE_LIMITER_BACKEND=redis
RATE_LIMITER_FAIL_OPEN=true
DEFAULT_RATE_LIMIT_LIMIT=100
DEFAULT_RATE_LIMIT_PERIOD=60
RATE_LIMITER_REDIS_HOST=redis
RATE_LIMITER_REDIS_PORT=6379
RATE_LIMITER_REDIS_DB=1
RATE_LIMITER_REDIS_PASSWORD=

SESSION_BACKEND=redis
SESSION_SECURE_COOKIES=true
CSRF_ENABLED=true
TRUSTED_PROXY_HOPS=1

TASKIQ_ENABLED=true
TASKIQ_BROKER_TYPE=redis
TASKIQ_REDIS_HOST=redis
TASKIQ_REDIS_PORT=6379
TASKIQ_REDIS_DB=3
TASKIQ_REDIS_PASSWORD=

METRICS_ENABLED=true
METRICS_ENDPOINT=/metrics

OTEL_ENABLED=false
OTEL_SERVICE_NAME=fastapi-base
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

Adding a New Feature Module

Use the existing modules as the template:

backend/src/modules/widget/
├── __init__.py
├── routes.py
├── dependencies.py
├── schemas.py
├── models.py
├── crud.py
└── service.py

Recommended flow:

  1. Define the SQLAlchemy model in models.py.
  2. Define Pydantic schemas in schemas.py.
  3. Create the FastCRUD object in crud.py.
  4. Put business logic in service.py.
  5. Add route dependencies in dependencies.py.
  6. Add endpoints in routes.py.
  7. Include the router from interfaces/api.
  8. Generate an Alembic migration.
  9. Add focused unit/integration tests.

Quality Checks

uv sync --all-packages --all-extras
uv run ruff check backend/src cli/src backend/tests
cd backend && uv run pytest

Some integration tests may require Docker, PostgreSQL, or Testcontainers.

Production Checklist

  • Replace every CHANGE_ME secret.
  • Generate a strong SECRET_KEY.
  • Set ENVIRONMENT=production.
  • Set CREATE_TABLES_ON_STARTUP=false.
  • Run Alembic migrations before rollout.
  • Restrict CORS_ORIGINS.
  • Keep docs disabled in production unless protected.
  • Use HTTPS and secure cookies.
  • Use separate API and worker deployments.
  • Pin Docker image tags.
  • Enable /metrics scraping if Prometheus is available.
  • Enable OTEL_ENABLED=true only after an OTLP collector is ready.
  • Keep /health/live, /health/ready, and /metrics unauthenticated for orchestration.

Useful Commands

# App
cd backend
uv run fastapi dev src/interfaces/main.py

# Worker
cd backend
uv run taskiq worker infrastructure.taskiq.worker:default_broker

# CLI
uv run bp --help
uv run bp deploy generate local
uv run bp env validate

# Kustomize
kubectl kustomize k8s/overlays/production

# Helm
helm template fastapi-base helm/fastapi-base -f helm/fastapi-base/values-prod.yaml

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages