Backend FastAPI and MongoDB - Project Template

This is a backend boilerplate designed for high-performance RESTful APIs using FastAPI and Motor, an asynchronous driver for MongoDB. It includes a health API for service health checking, basic CRUD operations for a sample resource, Swagger API documentation, and Docker support. Additionally, this boilerplate uses Cookiecutter, allowing for easy creation of new backend services.

Features

A new backend project created with this boilerplate provides:

• Asynchronous high-performance RESTful APIs built upon FastAPI framework.
• Asynchronous CRUD operations for a sample resource built upon Motor driver for MongoDB, providing high performance and efficiency.
• API documentation with Swagger UI.
• API testing with pytest and pytest-asyncio.
• Dockerfile for containerization and docker-compose support.
• Easy creation of new backend services with cookiecutter.
• Fast and modern package management with uv.
• Health API for service health checking.
• Easy configuration with environment variables.
• Easy testing, develop running, docker build, docker-compose up and down with Makefile.
• Proper logging with ID masking.

🚀 New: Migrated to uv!

This template now uses uv for blazing-fast dependency management (10-100x faster than Poetry)!

Existing users: See MIGRATION.md for migration guide.

Prerequisites

• Python 3.10+
• uv - Install with: curl -LsSf https://astral.sh/uv/install.sh | sh
• Cookiecutter - Install with: pip install cookiecutter
• Docker installed
• GNU Make

Getting Started

⚠️ IMPORTANT: Create A New Service First

You must execute this command before any other usage.
With Cookiecutter, you don't have to fork this project to create a new service.

Go to the directory where you want to place your new backend project, and run:

cookiecutter gh:klee1611/cookiecutter-fastapi-mongo

After the project folder is created, all packages required will be installed automatically with uv.
All subsequent steps below should be run inside the newly created project directory.

Edit Environment Variables

Edit the .env file within the project folder.

Run Tests

make test

Build Docker Image

make docker-build

Docker-compose

make docker-compose-up
make docker-compose-down

Run Service Locally

make dev

This will create a MongoDB container as well.

Check Swagger API Document

Go to http://localhost:8888/docs.

Website Deployment

The project website is located in the website/ directory. To deploy updates to GitHub Pages:

cd website
npm install
npm run deploy

This will deploy the website/public/ directory to the gh-pages branch using the gh-pages npm package.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

💬 Feedback & Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check existing issues for solutions
• Review the troubleshooting section above

☕ Support This Project

If you find this project helpful, consider supporting its development:

Or visit: https://www.buymeacoffee.com/klee1611

Happy coding! 🚀