Batteries-included FastAPI starter with production-ready defaults, optional modules, and clear docs.

📚 Docs · 🧠 DeepWiki · 💬 Discord

• ⚡️ Fully async FastAPI + SQLAlchemy 2.0
• 🧱 Pydantic v2 models & validation
• 🔐 JWT auth (access + refresh), cookies for refresh
• 👮 Rate limiter + tiers (free/pro/etc.)
• 🧰 FastCRUD for efficient CRUD & pagination
• 🧑‍💼 CRUDAdmin: minimal admin panel (optional)
• 🚦 ARQ background jobs (Redis)
• 🧊 Redis caching (server + client-side headers)
• 🐳 One-command Docker Compose
• 🚀 NGINX & Gunicorn recipes for prod

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
• Docs over boilerplate in README - depth lives in the 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: JWT access/refresh, logout via token blacklist
• DB: Postgres + SQLAlchemy 2.0, Alembic migrations
• CRUD: FastCRUD generics (get, get_multi, create, update, delete, joins)
• Caching: decorator-based endpoints cache; client cache headers
• Queues: ARQ worker (async jobs), Redis connection helpers
• Rate limits: per-tier + per-path rules
• Admin: CRUDAdmin views for common models (optional)

This is what we've been using in production apps. Several applications running in production started from this boilerplate as their foundation - from SaaS platforms to internal tools. It's proven, stable technology that works together reliably. Use this as the foundation for whatever you want to build on top.

Building an AI SaaS? Skip even more setup with FastroAI - our production-ready template with AI integration, payments, and frontend included.

Use the template on GitHub, create your repo, then:

git clone https://github.com/<you>/FastAPI-boilerplate
cd FastAPI-boilerplate

Quick setup: Run the interactive setup script to choose your deployment configuration:

./setup.py

Or directly specify the deployment type: ./setup.py local, ./setup.py staging, or ./setup.py production.

The script copies the right files for your deployment scenario. Here's what each option sets up:

Best for: Development and testing

Copies:

• scripts/local_with_uvicorn/Dockerfile → Dockerfile
• scripts/local_with_uvicorn/docker-compose.yml → docker-compose.yml
• scripts/local_with_uvicorn/.env.example → src/.env

Sets up Uvicorn with auto-reload enabled. The example environment values work fine for development.

Manual setup: ./setup.py local or copy the files above manually.

Best for: Staging environments and load testing

Copies:

• scripts/gunicorn_managing_uvicorn_workers/Dockerfile → Dockerfile
• scripts/gunicorn_managing_uvicorn_workers/docker-compose.yml → docker-compose.yml
• scripts/gunicorn_managing_uvicorn_workers/.env.example → src/.env

Sets up Gunicorn managing multiple Uvicorn workers for production-like performance testing.

Manual setup: ./setup.py staging or copy the files above manually.

Best for: Production deployments

Copies:

• scripts/production_with_nginx/Dockerfile → Dockerfile
• scripts/production_with_nginx/docker-compose.yml → docker-compose.yml
• scripts/production_with_nginx/.env.example → src/.env

Sets up NGINX as reverse proxy with Gunicorn + Uvicorn workers for production.

Manual setup: ./setup.py production or copy the files above manually.

Start your application:

docker compose up

Access your app:

• Local: http://127.0.0.1:8000 (auto-reload enabled) → API docs
• Staging: http://127.0.0.1:8000 (production-like performance)
• Production: http://localhost (NGINX reverse proxy)

Create your first admin user:

docker compose run --rm create_superuser

Run database migrations (if you add models):

cd src && uv run alembic revision --autogenerate && uv run alembic upgrade head

Test background jobs:

curl -X POST 'http://127.0.0.1:8000/api/v1/tasks/task?message=hello'

Or run locally without Docker:

uv sync && uv run uvicorn src.app.main:app --reload

Full setup (from-scratch, .env examples, PostgreSQL & Redis, gunicorn, nginx) lives in the docs.

Create src/.env and set app, database, JWT, and environment settings. See the docs for a copy-pasteable example and production guidance.

https://benavlabs.github.io/FastAPI-boilerplate/getting-started/configuration/

• ENVIRONMENT=local|staging|production controls API docs exposure
• Set ADMIN_* to enable the first admin user

# run locally with reload (without Docker)
uv sync && uv run uvicorn src.app.main:app --reload

# run Alembic migrations
cd src && uv run alembic revision --autogenerate && uv run alembic upgrade head

# enqueue a background job (example endpoint)
curl -X POST 'http://127.0.0.1:8000/api/v1/tasks/task?message=hello'

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

Read contributing.

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

MIT

Benav Labs – benav.io, discord server