fastapi-async-sqlmodel-boilerplate

🎯 Project Goals

• Leverage the power of FastAPI for building high-performance APIs.
• Implement asynchronous programming wherever applicable for optimal performance.
• Integrate Redis for caching, rate limiting, and improving data access speed.
• Utilize Celery for handling background tasks asynchronously with full async/await support.
• Implement a robust logging system to track and manage application events efficiently.
• Manage database migrations seamlessly using Alembic.
• Develop comprehensive and fully asynchronous tests for API endpoints using pytest-asyncio and testcontainers for isolated PostgreSQL instances.
• Implement using SQLModel to streamline the interaction between the database and the API.
• Adopt Repository and Service patterns for clean separation of concerns and enhanced testability.
• Write isolated unit tests for services (with mocked repositories) and integration tests for repositories.
• Provide a fully containerized development environment with Docker Compose (PostgreSQL, Redis).
• Ensure cross-platform compatibility for local development on both Linux and Windows (including Celery worker concurrency and async event loop handling).
• Provide a CLI tool for easy project execution and management (e.g., setup.py extension).
• Provide diverse deployment options (e.g., Kubernetes, cloud-specific services) to ensure flexibility and accessibility.

📋 Prerequisites

Before you begin, ensure you have the following prerequisites installed and configured:

• PostgreSQL: Set up a PostgreSQL database.
• Redis: Install and configure a Redis server.
• Python: Make sure to have Python 3.11 or a newer version installed on your system.
• Poetry: Install Poetry for managing dependencies.

Installing Poetry

Poetry is a dependency manager for Python. Follow the steps below to install Poetry version 1.7.1 (required):

1. Open a terminal.

2. Run the following command to install Poetry using pip:

   pip install poetry==1.7.1
   

3. Verify the installation by running:

   poetry --version
   

   This should display Poetry (version 1.7.1). If you have a different version installed, please uninstall and reinstall the correct version:

   pip uninstall poetry
   pip install poetry==1.7.1
   

Using Docker Compose (Alternative Setup)

If you prefer to use Docker containers for development, you can easily set up PostgreSQL and Redis using Docker Compose:

1. Ensure you have Docker and Docker Compose installed on your system.

2. From the root directory of the project, run the following command to start PostgreSQL and Redis containers:

   docker compose --env-file backend/.env -f development/compose/infra-only/docker-compose.yml \
     --project-name fastapi-async-sqlmodel-boilerplate up -d
   

3. Verify the services are running:

   docker compose --project-name fastapi-async-sqlmodel-boilerplate ps
   

4. To stop the services:

   docker compose --project-name fastapi-async-sqlmodel-boilerplate down
   

Note: The command uses environment variables from backend/.env, so ensure that file is properly configured before running the containers.

Now that the prerequisites are met, you can begin working on your project. Choose either the manual setup or Docker Compose based on your preference.

For a complete overview of all development modes, see the Development Guide.

🤖 Running the Project CLI

To streamline the usage of this boilerplate, we've provided a convenient CLI tool. From the root project directory, execute the following steps:

1. Clone the repository, running the following command:

git clone https://github.com/joaoflaviosantos/fastapi-async-sqlmodel-boilerplate.git

2. Navigate to the cloned repository:

cd fastapi-async-sqlmodel-boilerplate

3. Run the setup (CLI tool) command:

python3 setup.py

This command automates various setup tasks, making it easier to get started with the project.

For more details for a manual setup, please refer to the Backend README section.

For more details about load testing setup and usage, please refer to the Locust Guide.

📚 Documentation

🌐 Reference Projects

• FastAPI Boilerplate by Igor Magalhães
• FastAPI Alembic SQLModel Async by Jonathan Vargas
• FastAPI do zero by Dunossauro

Feel free to use this boilerplate as a starting point for your own projects, and adapt it based on your specific requirements and use cases. Happy coding! 🌟