Golden Path: Backend Python FastAPI
Template for async FastAPI (Python 3.11+) services with hexagonal architecture, deployed on Cloud Run. It ships a reference Flights CRUD API that illustrates the patterns to extend when creating a new microservice.
Repository
GitLab: templates/template-python-cr
Detailed technical reference for the template: FastAPI Template.
Stack
| Component | Value |
|---|---|
| Language | Python 3.11+ |
| Framework | FastAPI (async) |
| Dependency manager | uv (recommended) or pip |
| Architecture | Hexagonal (domain / services / infrastructure) |
| Persistence | PostgreSQL (SQLModel + SQLAlchemy async, asyncpg) |
| Migrations | Alembic (migrate.py) with seed data |
| Runtime | Cloud Run |
| Observability | OpenTelemetry (opentelemetry-instrument) |
Features
- Automatic OpenAPI — interactive docs at
/docs. - JWT authentication — Bearer token validation against Azure AD JWKS (
aud,exp,iss). - Schema management — schema sync on startup + Alembic migrations.
- Cloud Run ready —
Dockerfile, ERB deploy templates, and CI via ANDES pipelines.
Reference API (Flights)
| Method | Path | Auth |
|---|---|---|
GET | /health | No |
POST | /flights | JWT |
GET | /flights | JWT |
GET | /flights/{id} | JWT |
PATCH | /flights/{id} | JWT |
DELETE | /flights/{id} | JWT |
Local development requirements
- Python 3.11+
- PostgreSQL (local or remote)
- uv or
pip - Docker (optional, for container builds)
- Azure AD app registration (for JWT-protected endpoints)
# Install dependencies and run
uv sync
uvicorn main:app --reload --host 0.0.0.0 --port 8080
Interactive documentation becomes available at http://localhost:8080/docs.