README.md

FastAPI Template

This repo is kind of a template I use when starting up new FastAPI projects:

• easy local development
  • environment with configured postgres
  • script to lint code with ruff and ruff format
• SQLAlchemy with slightly configured alembic
  • async SQLAlchemy engine
  • pessimistic connection pooling configuration (link)
  • migrations set in easy to sort format (YYYY-MM-DD_slug)
  • migrations are formated with ruff
• global pydantic model with
  • explicit timezone setting during JSON export
• some configs for production
  • gunicorn with dynamic workers configuration (stolen from @tiangolo)
  • Dockerfile optimized for small size and fast builds with a non-root user
  • JSON logs
  • sentry for deployed envs
• and some other extras like global exceptions, sqlalchemy keys naming convention, shortcut scripts for alembic, etc.

Local Development

Setup just

MacOS:

brew install just

Debian/Ubuntu:

apt install just

Others: link

Setup poetry

pip install poetry

Other ways: link

Setup Postgres (16.3)

just up

Copy the environment file and install dependencies

1. cp .env.example .env
2. poetry install

Run the uvicorn server

With default settings:

just run

With extra configs (e.g. logging file)

just run --log-config logging.ini

Linters

Format the code with ruff --fix and ruff format

just lint

Migrations

• Create an automatic migration from changes in src/database.py

just mm *migration_name*

• Run migrations

just migrate

• Downgrade migrations

just downgrade downgrade -1  # or -2 or base or hash of the migration

Deployment

Deployment is done with Docker and Gunicorn. The Dockerfile is optimized for small size and fast builds with a non-root user. The gunicorn configuration is set to use the number of workers based on the number of CPU cores.

Example of running the app with docker compose:

docker compose -f docker-compose.prod.yml up -d --build