This repository offers boilerplate code for initiating a UV-managed, Dockerized FastAPI-PostgreSQL-SQLAlchemy-Alembic project. It includes a pre-commit framework configured with mypy and ruff to ensure consistent code formatting and strict typing. Whether you're building microservices or a larger application, this template streamlines your project setup, allowing you to focus on developing your FastAPI-based microservices with confidence using uv
for package management.
Use this template as a starting point to quickly set up a robust and scalable FastAPI project with PostgreSQL, taking advantage of powerful features like automatic API documentation generation, asynchronous capabilities, and containerization for easy deployment.
- FastAPI framework for building high-performance APIs
- PostgreSQL database integration with SQLAlchemy for efficient data management
- Alembic for seamless database schema migrations
- Pre-commit framework with MyPy and ruff for code formatting and strict typing checks
- CRUD base class for instance with needed model
- Project config file for ease of update configurations
- Utils function in utils.py (client and consumer for RabbitMQ broker for example)
Get started with your FastAPI project in no time using this template repository!
This project uses uv
for package and environment management.
-
Ensure
uv
is installed: If you don't haveuv
installed, follow the instructions at astral.sh/uv/install. -
Create and Activate Virtual Environment: Navigate to the project root and run:
uv venv source .venv/bin/activate
This creates a virtual environment in
.venv/
and activates it. -
Install Dependencies: With the virtual environment active, install the project dependencies (including development tools like
pre-commit
andpytest
):uv sync --all-extras
Alternatively, you can use
uv pip install ".[dev]"
. -
Install Pre-commit Hooks: To ensure code quality and consistency, install the pre-commit hooks:
pre-commit install
This will run linters and formatters automatically before each commit. You can also run them manually on all files:
pre-commit run --all-files
A Makefile
is provided with an init
target that automates the above steps. It will create a virtual environment named venv
(note: not .venv
), install uv
into it if necessary, install dependencies, and set up pre-commit. Positioning in the project root run the following make command:
make init
The project includes a Makefile
to streamline common development tasks. Here are the available commands:
make help
: Displays a list of all availablemake
commands and their descriptions.make init
: Initializes the project. This includes creating a Python virtual environment invenv/
, installinguv
(if not present in the environment's pip), installing all project dependencies usinguv pip install ".[dev]"
, installing pre-commit hooks, and running pre-commit on all files.make lint
: Runs linters and style checks usingpre-commit run --all-files
.make format
: Formats the codebase usingruff format .
.make test
: Executes the test suite usingpytest
(viauv run pytest
).make run
: Starts the FastAPI development server using Uvicorn onhttp://0.0.0.0:8000
with live reloading (uv run uvicorn app.main:app --reload
).make docker-build
: Builds the Docker image for the application, tagging it asbp-fastapi-sqlalchemy-alembic-docker
.make docker-run
: Runs the application in a Docker container in detached mode. It maps port 8000, uses the.env
file from the project root for environment variables, and names the containerbp-fastapi-app
.make alembic-revision MSG="your_message_here"
: Creates a new Alembic database migration. TheMSG
variable is optional; if not provided, it defaults to "new_migration".make alembic-upgrade
: Applies all pending Alembic database migrations, upgrading the database to the latest revision (head
).make clean
: Removes temporary files and build artifacts, including__pycache__
directories,*.pyc
files, test/lint caches (.pytest_cache
,.mypy_cache
,.ruff_cache
), build artifacts (build/
,dist/
,*.egg-info/
), and thevenv/
and.venv/
virtual environment directories.
To use these commands, simply run them from the project's root directory (e.g., make lint
).
This project uses pytest
for testing. To run the tests:
-
Ensure your virtual environment is activated (
source .venv/bin/activate
). -
Run pytest:
pytest
Or, using uv run
(which doesn't require activating the venv first):
uv run pytest
To set up environment variables for local development, follow these steps:
- Create a
.env
file in the root directory of your project. - Add the necessary environment variables to the .env file in the format KEY=VALUE. Adjust the config.py file to insert these variables into the config class instance.
Example .env file:
DB_HOST=localhost
DB_PORT=5432
DB_USER=myuser
DB_PASSWORD=mypassword
For deployment, you'll need to set up environment variables or secrets in your GitHub repository. Here's how to do it:
- Create the required environment variables or secrets in your GitHub repository.
- In the github-actions workflow file locate the env section.
- Insert the environment variables or secrets into the workflow step, providing the necessary values.
Example workflow step:
- name: Deploy
env:
DB_HOST: ${{ vars.DB_HOST }}
DB_PORT: ${{ vars.DB_PORT }}
DB_USER: ${{ secrets.DB_USER }}
DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
run: |
# Add your deployment script here
Please ensure you update this README after implementing an instance of this template. Here are the recommended steps to follow:
In your README's "Introduction and/or Overview" section (or similar), include the following information:
The service is built based on the [UV-Powered FastAPI MS Template](https://github.com/ferdinandbracho/bp_fastAPI-sqlalchemy-alembic-docker). For comprehensive technical details, instructions on how to run, deploy, and any other related considerations, please refer to the documentation provided in the [template repository](https://github.com/ferdinandbracho/bp_fastAPI-sqlalchemy-alembic-docker).
Towards the end of your README, just before the "Contributing" section (if applicable), add links to specific sections of the template repository for Indeed Information:
## Indeed Information
For detailed information on installation and prerequisites, please refer to the [UV-Powered FastAPI MS Template repository](https://github.com/ferdinandbracho/bp_fastAPI-sqlalchemy-alembic-docker).
Contributions are welcome! If you'd like to contribute, please follow these steps:
- Fork the repository.
- Create a new branch for your feature or bug fix.
- Implement your changes.
- Write or update tests as necessary.
- Submit a pull request against the main branch.
Please ensure your code adheres to the project's coding standards and includes appropriate tests.