FastAPI MongoDB Template | Production-Ready Backend Boilerplate with Cookiecutter

Overview

A production-ready backend boilerplate for building high-performance RESTful APIs using FastAPI and Motor, an asynchronous driver for MongoDB. This template includes health checks, CRUD operations, automatic API documentation, Docker support, and uses Cookiecutter for rapid project generation.

⚠️ Getting Started - Required First Step

1. Install uv (Ultra-fast Python Package Manager)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install Cookiecutter

pip install cookiecutter

3. Choose Your Python Version Branch

We support multiple Python versions with dedicated branches:

uv-python3.10 - Python 3.10 (LTS)
uv-python3.11 - Python 3.11
uv-python3.12 - Python 3.12
uv-python3.13 - Python 3.13
uv-python3.14 - Python 3.14 (Latest)

4. Create Your Project

Execute one of the following commands based on your preferred Python version:

For Python 3.14 (recommended):

cookiecutter gh:klee1611/cookiecutter-fastapi-mongo --checkout uv-python3.14

For Python 3.12:

cookiecutter gh:klee1611/cookiecutter-fastapi-mongo --checkout uv-python3.12

For other versions, replace with: uv-python3.10, uv-python3.11, or uv-python3.13

After project creation, uv will automatically install all dependencies. All subsequent commands must be run inside the newly created project directory.

System Requirements

Python 3.10 - 3.14 (choose your version)
uv - Ultra-fast Python package manager (10-100x faster than pip)
Cookiecutter - Project templating tool
Docker - For containerization
GNU Make - For running build commands

Key Features

High Performance

Asynchronous FastAPI framework
Motor async MongoDB driver
Non-blocking I/O operations
High concurrency support

Developer Experience

Auto-generated Swagger documentation
Pytest with async support
uv for blazing-fast dependency management
Type hints with MyPy

Production Ready

Dockerfile included
Docker Compose configuration
Multi-stage builds
Health check endpoints

Modern Stack

FastAPI 0.115+
Motor 3.6+
MongoDB 4.4+
Python 3.10 - 3.14
uv package manager

Usage Guide

Running Tests

make test

Development Server

make dev

This command starts a MongoDB container and launches the FastAPI development server with hot-reload enabled.

Building Docker Image

make docker-build

Docker Compose

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

Accessing API Documentation

Once the server is running, access the interactive API documentation at: http://localhost:8888/docs

Project Structure

your-project/
├── app/
│   ├── api/           # API endpoints
│   ├── dao/           # Data access layer
│   ├── db/            # Database connection
│   ├── models/        # Pydantic models
│   └── conf/          # Configuration
├── tests/             # Test cases
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
└── Makefile

Contributing

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

Report an Issue Submit a Pull Request

License

This project is licensed under the MIT License. See the LICENSE file for details.