A modern, production-ready FastAPI template with built-in features for rapid development and deployment.
- FastAPI - Modern, fast web framework for building APIs with automatic OpenAPI documentation
- FastAPI Pundra - Productivity companion for FastAPI (global exception handling, OpenAPI schema discovery,
auto_bind_routerfor API modules) - Auto Route Discovery - Routers under
app.apiare discovered and mounted automatically
- PostgreSQL - Default target database (connection built from settings;
psycopg2-binarydriver) - SQLAlchemy - SQL toolkit and ORM
- Alembic - Database migration management and version control
- Pydantic - Request/response models and validation
- Pydantic Settings - Typed configuration from environment variables (
app/config/settings.py) - Schema Layer - Organized schemas under
app.schemaswith OpenAPI discovery - Custom Serializers - Flexible data transformation under
app/serializers
- TaskIQ - Async task queue for background jobs
- taskiq-redis - Redis broker for TaskIQ
- Task Scheduling - Sample scheduled tasks and scheduler scripts under
scripts/
- JWT Authentication - Bearer tokens via
fastapi-pundraJWT utilities - Authorization Middleware - Validates JWT on protected routes; public routes are configured in
EXCLUDE_PATHS(app/config/authorization.py) - Path Rules - Prefix, segment-wildcard, and exact path matching for public routes (
app/lib/auth_path_utils.py)
- HTTPX - Async-friendly HTTP client; shared helpers in
app/lib/httpx_client.py
- UV - Python package manager and lockfile (
uv.lock) - Pytest - Tests with
pytest-asyncio,pytest-cov, factories (factory-boy/faker), andapp/tests/conftest.py - Ruff - Linter/formatter (
ruff.toml; also run via pre-commit) - Pre-commit - Git hooks (install with
uv run pre-commit-installor useuv run lintto run hooks on all files) - Docker - Sample app Dockerfile and supervisor config under
docker/
- Email -
fastapi-mail, Jinja2 templates, and premailer/inline CSS underapp/templates/mails/ - SQL File Management - Raw SQL files under
app/sql_files/ - Structured Logging - Loguru-based logging (
app/utils/logger.py)
- Python 3.12 or higher
- UV package manager (recommended)
- PostgreSQL (or adjust
db_*settings in.envto match your database)
Clone the repository and install dependencies:
# Install dependencies
uv sync
# Install with development dependencies (recommended for development)
uv sync --extra devNote: The
--extra devflag installs testing tools, Ruff, pre-commit, and related dev dependencies.
Create your environment configuration:
# Copy the example environment file
cp .env.example .env
# Edit .env: database host/user/password/name, SSL mode, project port, test DB URL, etc.
# Settings are loaded in app/config/settings.py (Pydantic Settings).This project uses Alembic for database schema management and migrations.
Initialize and upgrade your database:
# Run database migrations
uv run db-upgrade
# Create a new database revision (message in quotes)
uv run db-revision "Initial database setup"Start the development server:
# Development: auto-reload (port from settings, default 8000)
uv run start-server-dev
# Production-style: no reload
uv run start-serverThe API will be available at (host/port depend on your settings; defaults shown):
- API: http://localhost:8000
- Interactive Docs: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
# Install pre-commit hooks (once per clone)
uv run pre-commit-install
# Run the full lint pipeline (pre-commit on all files)
uv run lint
# Tests with coverage (project script enforces coverage thresholds)
bash scripts/test.sh
# Or run pytest directly (see pyproject.toml for default pytest options)
uv run pytestDefined in pyproject.toml under [project.scripts]:
| Command | Purpose |
|---|---|
uv run start-server |
Run the app with Uvicorn (no reload) |
uv run start-server-dev |
Run with reload |
uv run db-upgrade |
alembic upgrade head |
uv run db-revision "message" |
alembic revision --autogenerate |
uv run lint |
Run pre-commit on all files |
uv run pre-commit-install |
pre-commit install |
├── _docs/ # Extra documentation (see below)
├── alembic/ # Alembic env and migration versions
├── app/
│ ├── api/ # HTTP routes (auto-bound from app.api)
│ │ ├── v1/
│ │ │ ├── task_schedule_sample.py
│ │ │ └── user.py
│ │ ├── health.py
│ │ ├── root_index.py
│ │ └── router.py
│ ├── config/ # Settings, CORS, authorization lists
│ │ ├── authorization.py # EXCLUDE_PATHS (JWT not required)
│ │ ├── cors.py
│ │ └── settings.py # Pydantic Settings / env
│ ├── lib/
│ │ ├── auth_path_utils.py # Public-path matching for middleware
│ │ ├── database.py # Engine, session, Base
│ │ ├── dot_env_loader.py
│ │ ├── httpx_client.py
│ │ └── tskq/ # TaskIQ broker, scheduler helpers, invoker
│ ├── middleware/
│ │ └── authorization_middleware.py
│ ├── models/
│ │ └── users.py
│ ├── schemas/
│ │ └── user_schema.py
│ ├── serializers/
│ │ └── user_serializer.py
│ ├── services/
│ │ ├── scheduler_service.py
│ │ └── user_service.py
│ ├── sql_files/users/ # Example raw SQL
│ ├── tasks/ # TaskIQ task modules
│ ├── templates/ # Jinja (e.g. mail HTML)
│ ├── tests/ # pytest: unit/, integration/, factories/, fixtures/
│ ├── utils/
│ │ ├── base.py
│ │ └── logger.py # Loguru setup
│ ├── cli.py # db-upgrade, db-revision, lint, pre-commit-install
│ ├── main.py # FastAPI app factory
│ └── taskiq.py # TaskIQ app/broker wiring
├── docker/
│ ├── config/supervisor/
│ └── dockerfiles/
├── scripts/ # test.sh, lint.sh, format.sh, taskiq-*.sh, deploy.sh, etc.
├── .coveragerc
├── .pre-commit-config.yaml
├── alembic.ini
├── pyproject.toml
├── ruff.toml
├── uv.lock
└── README.md
Note
This project requires Python 3.12 or higher.