A Cookiecutter template that scaffolds production-ready async RESTful API services built with FastAPI, Motor (async MongoDB driver), and uv for fast dependency management. Spin up a fully structured, tested, and containerized backend in seconds.
Each project generated from this template includes:
- Async REST API — high-performance endpoints powered by FastAPI and Uvicorn.
- Async MongoDB CRUD — full Create / Read / Update / Delete operations via Motor.
- Health endpoint —
/healthroute for liveness and readiness checks. - Swagger / OpenAPI docs — auto-generated interactive API documentation at
/docs. - Structured logging — YAML-based logging config with environment-variable overrides and ID masking.
- Custom error handling —
BadRequestandUnprocessableErrorexceptions with RFC 7807-style JSON responses. - Test suite — async tests with pytest and pytest-asyncio covering all CRUD operations and the health endpoint.
- Docker support —
Dockerfileanddocker-compose.ymlincluded. - Makefile shortcuts — one-command test, dev run, image build, and compose up/down.
- uv package manager — 10-100× faster dependency resolution than pip/Poetry.
cookiecutter-fastapi-mongo/
├── cookiecutter.json # Template variables (project name, DB config, etc.)
├── hooks/ # Cookiecutter lifecycle hooks (post-generate setup)
├── {{cookiecutter.project_dir_name}}/ # Template source — rendered into your new project
│ ├── app/ # Application package
│ ├── tests/ # Test suite
│ ├── Dockerfile
│ ├── docker-compose.yml
│ ├── Makefile
│ ├── pyproject.toml
│ └── env.sample
├── website/ # Project website (GitHub Pages)
└── Makefile # Template-level CI targets
<your-project>/
├── app/
│ ├── server.py # FastAPI app factory — registers routes, middleware, lifecycle events
│ ├── error.py # Custom exception classes (BadRequest, UnprocessableError)
│ ├── util.py # Shared utility helpers
│ ├── api/
│ │ ├── health.py # GET /health
│ │ └── v1/
│ │ └── sample_resource.py # Versioned CRUD router
│ ├── models/
│ │ ├── create_sample_resource.py # Request body model
│ │ ├── get_sample_resource.py # Response model
│ │ ├── sample_resource_common.py # Shared field definitions
│ │ └── mongo_model.py # MongoDB document base model
│ ├── dao/
│ │ └── sample_resource.py # Data Access Object — all DB queries live here
│ ├── db/
│ │ └── db.py # Motor client — connect/disconnect lifecycle hooks
│ └── conf/
│ ├── config.py # App settings loaded from environment variables
│ └── logging.yaml # Logging configuration
├── tests/
│ ├── conftest.py
│ ├── mongo_client.py # Test DB client fixture
│ ├── mock_data/ # Fixtures / seed data for tests
│ ├── test_health.py
│ ├── test_create_sample_resource.py
│ ├── test_get_sample_resource.py
│ ├── test_update_sample_resource.py
│ └── test_delete_sample_resource.py
├── Dockerfile
├── docker-compose.yml
├── Makefile
├── pyproject.toml
└── env.sample
HTTP Request
│
▼
FastAPI Router (app/api/)
│ validates request body via Pydantic models (app/models/)
▼
Data Access Object (app/dao/)
│ async Motor queries
▼
MongoDB
│
▼
Pydantic Response Model → JSON Response
| Layer | Path | Responsibility |
|---|---|---|
| Router | app/api/ |
HTTP method binding, request validation, response serialisation |
| Model | app/models/ |
Pydantic schemas for requests, responses, and MongoDB documents |
| DAO | app/dao/ |
All database queries; the only layer that touches Motor/MongoDB |
| DB | app/db/ |
Motor client lifecycle (connect on startup, disconnect on shutdown) |
| Config | app/conf/ |
Environment-variable-driven settings and structured logging |
| Package | Purpose |
|---|---|
| FastAPI | Async web framework |
| Motor | Async MongoDB driver |
| Uvicorn + Gunicorn | ASGI server |
| Pydantic | Data validation (bundled with FastAPI) |
| PyYAML | Logging configuration |
| pytest-asyncio | Async test support |
| uv | Package and virtual-environment management |
| Tool | Install |
|---|---|
| Python 3.10+ | python.org |
| uv | curl -LsSf https://astral.sh/uv/install.sh | sh |
| Cookiecutter | pip install cookiecutter |
| Docker | docs.docker.com |
| GNU Make | Included on macOS/Linux |
Go to the directory where you want your new service, then run:
cookiecutter gh:klee1611/cookiecutter-fastapi-mongoCookiecutter will prompt for project settings (name, DB name, author, etc.), scaffold the project, and automatically install dependencies with uv.
All subsequent commands must be run inside the newly created project directory.
Copy the sample file and edit values to match your environment:
cp env.sample .env
# then edit .envKey variables:
| Variable | Description |
|---|---|
MONGODB_URL |
Full MongoDB connection string |
MONGODB_DBNAME |
Database name |
MAX_CONNECTIONS_COUNT |
Motor connection pool maximum |
MIN_CONNECTIONS_COUNT |
Motor connection pool minimum |
LOG_LEVEL |
Logging level (DEBUG, INFO, WARNING, ERROR) |
TEST_MONGODB_URL |
MongoDB URL used by the test suite |
TEST_DB_NAME |
Separate database used by the test suite |
make testThis spins up a temporary MongoDB container, runs all pytest tests, then tears down the container automatically.
make devStarts a MongoDB container and runs the API server with hot-reload at http://localhost:8888.
Open your browser at http://localhost:8888/docs for the interactive Swagger UI.
make docker-buildmake docker-compose-up # build & start API server + MongoDB
make docker-compose-down # stop & remove containers, volumes, and imagesIf you were using an earlier version of this template that used Poetry, see MIGRATION.md for the uv migration guide.
The project website lives in website/. To publish updates to GitHub Pages:
cd website
npm install
npm run deployThis pushes website/public/ to the gh-pages branch via the gh-pages npm package.
Pull requests are welcome! For significant changes, please open an issue first to discuss the proposal.
- Open a GitHub issue for bugs or feature requests.
- Check existing issues before opening a new one.
If this template saves you time, consider buying the author a coffee:
Happy coding! 🚀