Fastro · The Benav Labs FastAPI Boilerplate

Batteries-included FastAPI starter - vertical-slice modules, swappable infrastructure, plugin-ready CLI.

Docs · DeepWiki · Discord

The free, open-source FastAPI foundation. Building a SaaS - AI or not? FastroAI adds payments, entitlements, email & a frontend (plus AI) on top - compare ↓

Features

• Fully async FastAPI + SQLAlchemy 2.0
• Pydantic v2 models & validation
• Server-side sessions + CSRF via crudauth; OAuth (Google wired); API keys
• Annotated type aliases for all FastAPI dependencies
• Rate limiter with per-tier, per-path rules
• FastCRUD for efficient CRUD & pagination
• SQLAdmin-based admin panel (optional, env-toggled)
• Taskiq workers (Redis or RabbitMQ broker)
• Redis or Memcached caching (@cache decorator + provider API)
• Plugin-ready bp CLI - generate compose files, audit env, mount third-party command/feature plugins
• Docker Compose for local / prod / nginx-fronted (generated by the CLI)

Why and When to use it

Perfect if you want:

• A pragmatic starter with auth, CRUD, jobs, caching and rate-limits
• Sensible defaults with the freedom to opt-out of modules
• A foundation that grows - vertical-slice modules + a plugin-aware CLI for code generators
• Docs over boilerplate in this README - depth lives on the docs site

Not a fit if you need a monorepo microservices scaffold - see the docs for pointers.

What you get:

• App: FastAPI app factory, env-aware docs exposure
• Auth: server-side sessions, CSRF, OAuth, API keys
• DB: Postgres + SQLAlchemy 2.0, Alembic migrations with prod-confirm gate
• CRUD: FastCRUD generics
• Caching: decorator + provider API (Redis or Memcached)
• Queues: Taskiq workers (Redis or RabbitMQ)
• Rate limits: per-tier + per-path rules
• Admin: SQLAdmin views (optional, env-toggled)
• CLI: bp tool for compose scaffolding, env audits, and plugin extensions

Fastro vs FastroAI

This boilerplate - Fastro - is the free, open-source foundation: everything you need for a production FastAPI backend. FastroAI is the paid template built on the same foundation for shipping a complete SaaS - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, and a frontend, all wired together. Building an AI product? The PydanticAI agent layer is included too - but every paid feature fits a regular SaaS just as well.

Stick with Fastro if you want a clean, hackable FastAPI backend to build on. Get FastroAI → if you're shipping a SaaS - AI or not - and want billing, entitlements, email, auth, and a frontend ready out of the box.

Repo Layout

This is a uv workspace with two members. One venv at the root covers both.

fastapi-boilerplate/
├── pyproject.toml          # workspace root (uv workspace metadata)
├── backend/                # the deployable application
│   ├── src/                # interfaces/, infrastructure/, modules/
│   ├── pyproject.toml
│   └── Dockerfile          # multi-stage: dev / migrate / prod
└── cli/                    # `bp` - developer/operator tool (never ships in prod)
    └── src/cli/

Quickstart

git clone https://github.com/<you>/FastAPI-boilerplate
cd FastAPI-boilerplate
uv sync --all-packages --all-extras           # one venv at the root, both members installed

Generate a compose file for the deployment shape you want:

uv run bp deploy generate local               # hot-reload dev stack
# or: uv run bp deploy generate prod          # production single-host
# or: uv run bp deploy generate nginx         # production behind nginx

Configure your env (the CLI helps with secrets and validation):

cp backend/.env.example backend/.env
uv run bp env gen-secret                      # print a fresh SECRET_KEY
uv run bp env validate                        # audit .env against the production validator

Bring it up:

docker compose up --build
# → http://127.0.0.1:8000  (Swagger at /docs)

Without Docker (Postgres + Redis required locally):

cd backend
uv run alembic upgrade head
uv run python -m scripts.setup_initial_data   # creates the first admin user + default tier
uv run fastapi dev src/interfaces/main.py     # API
uv run taskiq worker infrastructure.taskiq.worker:default_broker  # in a second terminal

Full setup, env-var reference, and per-environment deployment guides live in the docs.

Common tasks

# generate a fresh production-ready compose file
uv run bp deploy generate prod --workers 8

# audit your .env against the production security validator
uv run bp env validate

# run Alembic migrations
cd backend && uv run alembic revision --autogenerate -m "<msg>" && uv run alembic upgrade head

# run tests
cd backend && uv run pytest

# install bp as a global tool (optional)
uv tool install --editable ./cli

More examples (superuser creation, tiers, rate limits, admin usage, plugin authoring) in the docs.

Contributing

Read contributing.

References

This project was inspired by a few projects, it's based on them with things changed to the way I like (and pydantic, sqlalchemy updated)

• Full Stack FastAPI and PostgreSQL by @tiangolo himself
• FastAPI Microservices by @kludex which heavily inspired this boilerplate
• Async Web API with FastAPI + SQLAlchemy 2.0 for sqlalchemy 2.0 ORM examples
• FastaAPI Rocket Boilerplate for docker compose

License

MIT

Contact

Benav Labs – benav.io, discord server