High-performance Async REST API, in Python. FastAPI + GINO + Arq + Uvicorn (powered by Redis & PostgreSQL).

Get Started


  1. Clone this Repository. git clone
  2. Install Python 3.8 and poetry.
    • Recommended Method: asdf - a universal version manager (think nvm or pyenv)
      • Follow these instructions to install asdf.
      • Run the following commands from the project root:
        • asdf plugin add python
        • asdf plugin add poetry
        • asdf install -- will download & configure this project's Python + poetry setup
      • ~NOTE: your machine must have a system version of Python installed. If you don't, run the following: asdf install python 3.8.2 && asdf global python 3.8.2
    • If you have Python 3.8 and poetry installed already, please feel free to skip.
  3. Install dependencies (poetry install).
  4. Activate pre-commit hooks (in poetry shell, run pre-commit install).
  5. Make a copy of .dist.env, rename to .env. Fill in PostgreSQL, Redis, Sentry (optional) variables.
  6. Generate DB Migrations: in poetry shell, run alembic revision --autogenerate.
    • Apply migrations manually with alembic upgrade head.
    • If using the Dockerfile, migrations are applied at startup.


Run Locally

NOTE: You must have PostgreSQL & Redis running locally.

  1. Make sure PostgreSQL & Redis are running locally.
  2. Run:
    • FastAPI Application:
      • For Active Development (w/ auto-reload): Run locally with poetry run task app
      • For Debugging (compatible w/ debuggers, no auto-reload): Configure debugger to run python app/
    • Background Task Worker:
      • For Active Development: Run poetry run task worker

Run Locally with Docker-Compose.

  1. Make sure Docker is running locally.
  2. Run poetry run task compose-up*.
    • Run poetry run task compose-down to spin down, clean up.

*app/settings/ will run migrations for you before the app starts.

Build Your Application

  • Create routes in /app/routes, import & add them to the ROUTERS constant in /app/
  • Create database models to /app/models/orm, add them to /app/models/orm/migrations/ for migrations
  • Create pydantic models in /app/models/pydantic
  • Store complex db queries in /app/models/orm/queries
  • Store complex tasks in app/tasks.
  • Add / edit globals to /.env, expose & import them from /app/settings/
    • Use any coroutine as a background function: store a reference in the ARQ_BACKGROUND_FUNCTIONS env.
    • Set SENTRY_DSN in your environment to enable Sentry.
  • Define code to run before launch (migrations, setup, etc) in /app/settings/


Core Dependencies

  • FastAPI: touts performance on-par with NodeJS & Go + automatic Swagger + ReDoc generation.
  • GINO: built on SQLAlchemy core. Lightweight, simple, asynchronous ORM for PostgreSQL.
  • Arq: Asyncio + Redis = fast, resource-light job queuing & RPC.
  • Uvicorn: Lightning-fast, asynchronous ASGI server.
  • Optimized Dockerfile: Optimized Dockerfile for ASGI applications, from

Additional Dependencies

  • PostgreSQL: Robust, fully-featured, scalable, open-source.
  • Redis: Fast, simple, broker for the Arq task queue.
  • Pydantic: Core to FastAPI. Define how data should be in pure, canonical python; validate it with pydantic.
  • Alembic: Handles database migrations. Compatible with GINO.
  • SQLAlchemy_Utils: Provides essential handles & datatypes. Compatible with GINO.
  • Sentry: Open-source, cloud-hosted error + event monitoring.
  • Pre-Commit: automatic formatting (black + isort) and linting (flake8).
  • Taskipy: Small, flexible task runner for Poetry.