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.
- 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
/metricsendpoint. - OpenTelemetry setup for FastAPI, SQLAlchemy, Redis, and HTTPX.
- Docker multi-stage build for dev, migration, and production.
bpCLI for Docker Compose generation.- Kustomize manifests for development, staging, and production.
- Helm chart with optional ingress, HPA, migration job, and ServiceMonitor.
.
├── 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
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]
From the repository root:
uv sync --all-packages --all-extras
cp backend/.env.example backend/.envEdit backend/.env before running the app:
- Set a strong
SECRET_KEY. - Set
POSTGRES_*for normal local development. The app can also useDATABASE_URL; when present,DATABASE_URLtakes priority. - Use
POSTGRES_SERVER=dbwhen running through Docker Compose, orPOSTGRES_SERVER=localhostwhen running the API directly on your machine. - Point
CACHE_REDIS_*,RATE_LIMITER_REDIS_*, andTASKIQ_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, thenbackend/.env, then/.env. In Docker,/app/.envis the common path; in local development,backend/.envis the usual path.
cd backend
uv run fastapi dev src/interfaces/main.pyDefault local endpoints:
GET /healthGET /health/liveGET /health/readyGET /metricsGET /docsGET /redocGET /openapi.json
In production, API documentation is hidden when ENABLE_DOCS_IN_PRODUCTION=false.
In a second terminal:
cd backend
uv run taskiq worker infrastructure.taskiq.worker:default_brokerThe worker uses the same environment settings as the API and should be deployed as a separate process/container in production.
The bp CLI generates Docker Compose stacks.
uv run bp deploy generate local
uv run bp deploy generate prod
uv run bp deploy generate nginxThen run:
docker compose up --buildGenerated stacks include:
- API container.
- Taskiq worker container.
- PostgreSQL.
- Redis.
- Migration container for production modes.
- Optional nginx reverse proxy for
nginxmode.
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.
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]
Startup notes:
- Production security validation runs before the application finishes startup when
PRODUCTION_SECURITY_VALIDATION_ENABLED=true. CREATE_TABLES_ON_STARTUP=trueis convenient for local development, but production should use Alembic migrations and set it tofalse.initialization_completeis 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.
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
Configuration rules:
- Use
DATABASE_URLin platforms that already provide a full connection string. - Use
POSTGRES_USER,POSTGRES_PASSWORD,POSTGRES_SERVER,POSTGRES_PORT, andPOSTGRES_DBwhen you want explicit service-name based configuration. - Keep
CACHE_REDIS_DB,RATE_LIMITER_REDIS_DB, andTASKIQ_REDIS_DBseparate when sharing one Redis server. - Run
uv run bp env validatebefore production rollout to catch weak secrets and unsafe settings.
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
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.
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
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.
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
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 updatelast_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 ...orX-API-Key, add a dedicated dependency or middleware that callsvalidate_api_key(...)for the relevant resource/action.
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]
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.
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
The global middleware is in:
backend/src/infrastructure/rate_limit/middleware.py
The rule management module is in:
backend/src/modules/rate_limit/
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]
Use cache for read-heavy data that can tolerate staleness. Keep writes authoritative in PostgreSQL.
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
Worker entrypoint:
taskiq worker infrastructure.taskiq.worker:default_brokerTaskiq infrastructure:
backend/src/infrastructure/taskiq/
├── app.py
├── brokers.py
├── deps.py
├── registry.py
└── worker.py
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]
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/
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]
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 runsfastapi dev.migrate: copies Alembic files and runsalembic upgrade head.prod: runsfastapi run interfaces/main.pywith theWORKERSenvironment variable.
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]
Commands:
kubectl kustomize k8s/overlays/development
kubectl apply -k k8s/overlays/development
kubectl apply -k k8s/overlays/staging
kubectl apply -k k8s/overlays/productionKustomize 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
ConfigMapfor non-secret values andSecretfor 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/
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]
Render:
helm template fastapi-base helm/fastapi-base
helm template fastapi-base helm/fastapi-base -f helm/fastapi-base/values-prod.yamlInstall or upgrade:
helm upgrade --install fastapi-base helm/fastapi-base \
--namespace production \
--create-namespace \
-f helm/fastapi-base/values-prod.yamlHelm deployment behavior:
values.yamldefines the main production-capable defaults.values-prod.yamloverrides replica counts, log level, docs visibility, and OpenTelemetry production settings.secretEnvcontains sensitive runtime values such asSECRET_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=truewhen you want Helm to run the Alembic migration job as part of a release.
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:4317Use 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:
- Define the SQLAlchemy model in
models.py. - Define Pydantic schemas in
schemas.py. - Create the FastCRUD object in
crud.py. - Put business logic in
service.py. - Add route dependencies in
dependencies.py. - Add endpoints in
routes.py. - Include the router from
interfaces/api. - Generate an Alembic migration.
- Add focused unit/integration tests.
uv sync --all-packages --all-extras
uv run ruff check backend/src cli/src backend/tests
cd backend && uv run pytestSome integration tests may require Docker, PostgreSQL, or Testcontainers.
- Replace every
CHANGE_MEsecret. - 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
/metricsscraping if Prometheus is available. - Enable
OTEL_ENABLED=trueonly after an OTLP collector is ready. - Keep
/health/live,/health/ready, and/metricsunauthenticated for orchestration.
# 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