🐍 Python MongoDB API Template

A production-ready backend template built with FastAPI, MongoDB, Redis and MinIO, designed for real-world applications.

This project follows well known architecture principles and provides a solid foundation for building scalable APIs with authentication, file storage, caching, observability and Docker support.

---

✨ Key Features

⚡ FastAPI (async) with Motor (MongoDB async driver)

🔐 JWT Authentication (access & refresh tokens)

🧠 Redis integration

• Token blacklist
• Caching support

📦 MinIO object storage

• User attachments & files
• S3-compatible storage

📧 Email service ready (SMTP)

🚦 Rate limiting middleware

📊 Observability

• Prometheus metrics
• Grafana dashboards
• Jaeger tracing

🐳 Full Docker & Docker Compose setup

🩺 Healthcheck endpoint

🧪 Test-ready structure

---

🧰 Tech Stack

• Python 3.11+
• FastAPI
• MongoDB
• Redis
• MinIO
• Docker / Docker Compose
• Prometheus / Grafana / Jaeger

---

⚙️ Requirements

To run locally you need:

• Python 3.11+
• MongoDB
• Redis
• MinIO Storage
• Docker (optional but recommended)
• Make (optional)

---

🚀 Getting Started (Local)

git clone https://github.com/ortiz-python-templates/python-mongodb-api.git
cd python-mongodb-api

python -m venv venv
source venv/bin/activate

pip install -r requirements.txt

---

🔧 Environment Configuration

Copy the example environment file:

cp .env.example .env

Main environment variables:

APP_ENVIRONMENT=development
APP_PORT=5000

# MongoDB
MONGO_URI=mongodb://127.0.0.1:27017
MONGO_DATABASE=python_template_mongodb_api

# Redis
REDIS_URL=redis://localhost:6379

# JWT
JWT_SECRET_KEY=your_secret
JWT_REFRESH_SECRET_KEY=your_refresh_secret
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7

# MinIO
MINIO_ENDPOINT=localhost:9000
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=admin123
MINIO_MAIN_BUCKET=python-mongodb-bucket

---

🐳 Run with Docker (Recommended)

docker compose -f docker/docker-compose.yml up -d

This will start:

• FastAPI API
• MongoDB
• Redis
• MinIO
• Prometheus
• Grafana
• Jaeger

API Docs: 👉 http://localhost:5000/docs

MinIO Console: 👉 http://localhost:9001

Grafana: 👉 http://localhost:3000 (Default user: admin / password: admin)

---

▶️ Run Locally (Without Docker)

make run

or

uvicorn main:app --reload

---

🩺 Healthcheck (Complete and profissional)

GET /health

Response:

{
"status": "ok",
"service": "python-template-mongodb-api",
"version": "1.0.0",
"environment": "development",
"timestamp": "2025-12-18T12:48:14.387926Z",
"uptime_seconds": 166,
"hostname": "ortiz-latitude3379",
"dependencies": {
"mongodb": {
"status": "up",
"latency_ms": 8.79
},
"redis": {
"status": "up",
"latency_ms": 0.85
}
},
"runtime": {
"cpu_percent": 57.8,
"memory_rss_mb": 105.58,
"memory_vms_mb": 1006.89
}
}

---

📂 Project Structure (Simplified)

src/
├── common/        # Configs, middlewares, storage, utils
├── core/          # Controllers, services, repositories
├── models/        # MongoDB models
├── schemas/       # Request / response schemas
├── services/      # Business logic
└── repositories/ # MongoDB query & command repositories

---

📁 File Storage Strategy

Files are stored in MinIO

Database stores only the object_key

Access URLs are generated dynamically (public or signed URLs)

Ready for:

• User avatars
• Attachments
• Documents
• Images

---

🧪 Tests

make test

---

🛠️ Make Commands

make help           # Help
make run            # Run API
make test           # Run tests
make clean_cache    # Clear Python cache
make docker_up      # Start Docker Compose
make docker_down    # Stop Docker Compose

---

📦 Use Cases

This template is suitable for:

• SaaS backends
• Admin dashboards
• Authentication services
• File-heavy systems
• Internal APIs
• Microservices foundations

---

🪪 License

MIT License © 2025 Built and maintained by Ortiz David