Skip to content

gearbox/fastapi_template

Repository files navigation

Logo

FastAPI template

Purpose

This template tends to follow best practices and patterns, and it can be used to reduce writing boilerplate code and start project asap or as a starting point in learning FastAPI framework.

Quick start guide

  1. You can use this project as a template for your own project

  2. Clone the repository:

    git clone https://github.com/gearbox/fastapi_template.git
  3. Install the UV packet manager following the Instruction (standalone version is recommended)

  4. Install the project dependancies Run the below commands in the project root directory:

    uv venv
    uv sync

    For developers it is recommended to install the dev dependencies as well:

    uv sync --group dev
  5. Activate the virtual environment: source .venv/bin/activate

Using ruff linter

  • Automatic run using pre-commit

    Run pre-commit install in the project root directory.

    This way commands ruff check --fix and ruff format will run after each commit using configuration from the pyproject.toml

  • Manual run

    Run the below commands in the project root directory:

    ruff check --fix
    ruff format

Starting the application

Using Docker and Docker-compose

Make sure you have Docker and Docker Compose installed.

  1. Navigate to the project directory:

    cd fastapi_template
  2. Run the application using the following command:

    docker-compose up --build

    This command will build the Docker images and start the application.

  3. Stop the application:

    docker-compose down

Running application locally

  1. Make sure you have PostgreSQL and Redis installed and running. You can use Docker to run these services if you don't have them installed locally.
  2. Run the application:
    • Using Fastapi:
      fastapi run backend/asgi.py --proxy-headers --port 80
    • Using Gunicorn:
      gunicorn -w 1 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:80 --timeout 180 --access-logfile - --error-logfile - backend.asgi:app

Setup alembic

  1. Initialize alembic (already done it, so you can skip this step):
    alembic init backend/databases/migrations
  2. Edit alembic.ini file and set the sqlalchemy.url to your database URL or use the env.py file to set it dynamically from the app settings (already done it). There is a Base model in backend/databases/models, it has common CRUD methods implemented. You can use it as a base class for your own models. It is already imported in the env.py file, so you can create migrations based on your models.

Architecture

It uses:

  • uvicorn as an Async Server Gateway Interface,
  • loguru as a logging system with a prebuilt logs template,
  • fastapi as a main framework,
  • pydantic for data validation,
  • pydantic-settings for the app settings which also support .env file with OS env variables.
  • postgresql as a database,
  • sqlalchemy as an ORM,
  • alembic for migrations,
  • redis as a cache,

Application is split into schemas, routers and managers, which are contained in separate packages. routers package is used for creating endpoints, managers contains business-logic for endpoints. We have a separate errors.py file for custom error handlers, dependencies.py file to maintain dependencies and settings.py to maintain app's settings. logger.py is used to maintain loguru tuning and initial setup and loguru logs template is in settings.py. You can put .env file in the root of the app's folder (.env.sample is included).

Dev-tools

  • uv - packet and dependancies manager
  • ruff - advanced linter and formatter
  • pre-commit - runs linter on each commit

Endpoints

There are several endpoints which could be used directly or as an example:

Endpoint URL Description
/ Is set to show Swagger (OpenAPI) documentation, same as /docs
/docs Default FastAPI Swagger (OpenAPI) documentation endpoint
/redoc Default FastAPI Redoc documentation endpoint
/healthcheck Endpoint that could be used to check if App is up and healthy.
It returns the app uptime and start date and time, db and redis health status
/info Sample endpoint that uses token authorisation method

Using Alembic for Migrations

  • To create a new migration:

    alembic revision --autogenerate -m "Your migration message"
  • To apply migrations:

    alembic upgrade head
  • To downgrade migrations:

    alembic downgrade -1

    or

    alembic downgrade base
    
  • To view the current migration status:

    alembic current

Seeding the Database

To populate the database with initial data, it easy to use the seeds module using the following command:

python -m backend.seeds.seed <table_name> <action>

Replace <table_name> with the name of the table you want to seed (e.g., users, pets, friends). You can write your own seeders in the backend/seeds/data directory using the provided sample.

Replace <action> with the desired action (supporting seed, clear, status).

For example:

  • to seed the users table, run:
    python -m backend.seeds.seed users seed
  • to clear the users table, run:
    python -m backend.seeds.seed users clear
  • to check the status of the users table, run:
    python -m backend.seeds.seed users status

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Packages

No packages published