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.

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

• 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

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

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

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.

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 manager
• ruff - advanced linter and formatter
• pre-commit - runs linter on each commit

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

• 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