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.
-
You can use this project as a template for your own project
-
Clone the repository:
git clone https://github.com/gearbox/fastapi_template.git
-
Install the UV packet manager following the Instruction (standalone version is recommended)
-
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
-
Activate the virtual environment:
source .venv/bin/activate
-
Run
pre-commit install
in the project root directory.This way commands
ruff check --fix
andruff format
will run after each commit using configuration from thepyproject.toml
-
Run the below commands in the project root directory:
ruff check --fix ruff format
Make sure you have Docker and Docker Compose installed.
-
Navigate to the project directory:
cd fastapi_template
-
Run the application using the following command:
docker-compose up --build
This command will build the Docker images and start the application.
-
Stop the application:
docker-compose down
- 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.
- 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
- Using Fastapi:
- Initialize alembic (already done it, so you can skip this step):
alembic init backend/databases/migrations
- Edit
alembic.ini
file and set thesqlalchemy.url
to your database URL or use theenv.py
file to set it dynamically from the app settings (already done it). There is a Base model inbackend/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 theenv.py
file, so you can create migrations based on your models.
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).
uv
- packet and dependancies managerruff
- advanced linter and formatterpre-commit
- runs linter on each commit
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 |
-
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
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