FastAPI Base Project

🇧🇷 Português | 🇫🇷 Français | 🇪🇸 Español

A modern, production-ready FastAPI backend template with best practices, Docker support, and comprehensive tooling for rapid development.

🏗️ Project Template

This project was created using the excellent cookiecutter-fastapi-backend template by @nickatnight, which provides a solid foundation for FastAPI applications with best practices and modern tooling.

📚 Documentation

• Architecture - System architecture overview
• Development Guide - Local development guidelines
• Contributing Guide - How to contribute to this project
• Troubleshooting - Common issues and solutions

✨ Features

• FastAPI - Modern, fast web framework for building APIs
• Docker - Containerized development and deployment
• PostgreSQL - Robust relational database with async support
• Redis - Caching and session management
• Celery - Background task processing
• Alembic - Database migration management
• Testing - Comprehensive test suite with pytest
• Code Quality - Pre-commit hooks, linting, and formatting
• Type Safety - Full type hints with mypy validation
• Documentation - Auto-generated API docs with Swagger UI

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Python 3.13+ (for local development)
• uv package manager

Running with Docker (Recommended)

1. Clone the repository:

   git clone https://github.com/GabrielVGS/fastapi-base.git
   cd fastapi-base

2. Copy environment variables:

   cp .env.example .env

3. Start the services:

   make up

4. Access the application:

   • API: http://localhost:8666/v1/
   • Health check: http://localhost:8666/v1/ping
   • Interactive docs: http://localhost:8666/docs
   • Alternative docs: http://localhost:8666/redoc

🛠️ Local Development

Setting up Local Environment

1. Install uv (if not already installed):

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

2. Navigate to the project directory:

   cd fastapi-base/

3. Install dependencies:

   uv sync

4. Install pre-commit hooks:

   make hooks

Database Migrations

Initialize the first migration (project must be running with docker compose up and contain no 'version' files):

make alembic-init

Create new migration file:

make alembic-make-migrations "describe your changes"

Apply migrations:

make alembic-migrate

Migration Workflow

After each migration, you can create new migrations and apply them with:

make alembic-make-migrations "describe your changes"
make alembic-migrate

📋 Environment Variables

Create a .env file based on .env.example:

Application Settings

• PROJECT_NAME - Name of the project (default: fastapi-base)
• VERSION - API version (default: v1)
• DEBUG - Enable debug mode (default: True)
• SECRET_KEY - Secret key for JWT and encryption
• ENV - Environment (dev/staging/production)

Database Configuration

• POSTGRES_USER - PostgreSQL username
• POSTGRES_PASSWORD - PostgreSQL password
• POSTGRES_DB - Database name
• POSTGRES_HOST - Database host (default: localhost)
• POSTGRES_PORT - Database port (default: 5432)
• POSTGRES_URL - Complete database URL (optional, auto-generated if not provided)

Redis Configuration

• REDIS_HOST - Redis host (default: redis)
• REDIS_PORT - Redis port (default: 6379)
• REDIS_URL - Complete Redis URL (optional, auto-generated if not provided)

Optional Settings

• SENTRY_DSN - Sentry error tracking DSN
• LOG_LEVEL - Logging level (default: INFO)
• CACHE_TTL - Cache time-to-live in seconds (default: 60)

🏃 Running the Application

Using Docker Compose (Recommended)

# Build and start all services
make build

# Start services (without building)
make up

# Stop services
make down

# Access container bash
make bash

Local Development (without Docker)

# Ensure PostgreSQL and Redis are running locally
# Update .env with local database/redis connections

# Run the FastAPI application
uv run uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

🔧 Development Workflow

Check the Makefile to view all available commands.

Available Make Commands

# Development
make up          # Start all services with Docker Compose
make down        # Stop all services
make build       # Build and start services
make bash        # Access the main container shell

# Database
make alembic-init              # Initialize first migration
make alembic-make-migrations   # Create new migration
make alembic-migrate          # Apply migrations
make alembic-reset            # Reset database
make init-db                  # Initialize database with sample data

# Code Quality
make test           # Run test suite with coverage
make lint           # Run ruff linter
make black          # Format code with black
make isort          # Sort imports
make mypy           # Type checking
make precommit-run  # Run all pre-commit hooks

# Maintenance
make hooks          # Install pre-commit hooks

Dependencies

By default, dependencies are managed with uv. Please visit the link and install it.

From ./fastapi-base/ you can install all dependencies with:

uv sync

Pre-commit Hooks

The project uses pre-commit hooks to ensure code quality. Install them with:

make hooks

This will install hooks that run automatically before each commit to:

• Format code with black
• Sort imports with isort
• Lint code with ruff
• Check types with mypy
• Run tests

🧪 Testing

Run the complete test suite:

make test

Run specific tests:

# Inside the container
docker compose exec fastapi-base pytest tests/test_specific.py

# Locally (if dependencies installed)
uv run pytest tests/test_specific.py

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for detailed information about:

• Setting up your development environment
• Code style and standards
• Testing requirements
• Pull request process
• Code of conduct

📄 License

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

🛠️ Built With

• FastAPI - Modern, fast web framework
• SQLModel - SQL databases in Python, designed for simplicity
• Alembic - Database migration tool
• Celery - Distributed task queue
• Redis - In-memory data structure store
• PostgreSQL - Advanced open source database
• Docker - Containerization platform
• uv - Fast Python package manager

📚 Additional Resources

• FastAPI Documentation
• SQLModel Documentation
• Docker Documentation
• PostgreSQL Documentation

⭐️ Support

If you found this project useful, please consider:

• Giving it a star ⭐️ on GitHub
• Sharing it with your colleagues
• Contributing to its development
• Reporting issues or suggesting improvements

---

Happy coding! 🚀