FastAPI PostgreSQL Template

A modern, production-ready FastAPI template with PostgreSQL, Redis, and comprehensive authentication & authorization.

🌟 Features

• Modern Stack:

  • FastAPI for high-performance async API
  • PostgreSQL with SQLAlchemy 2.0 and Alembic
  • Redis for caching
  • Docker & Docker Compose setup

• Authentication & Authorization:

  • Role-based access control (RBAC)
  • Permission-based authorization
  • JWT authentication
  • Secure password hashing

• Project Structure:

  • Modular application structure
  • Repository pattern implementation
  • Service layer for business logic
  • Clean separation of concerns

• Developer Experience:

  • Comprehensive type hints
  • Automatic API documentation
  • Docker development environment
  • Easy-to-use CLI commands

• Production Ready:

  • Health checks
  • Logging setup
  • Error handling
  • Database migrations
  • Security best practices

🚀 Quick Start

1. Clone the repository:

   git clone https://github.com/o4codes/fastapi-postgres-template.git
   cd fastapi-postgres-template

2. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configurations

3. Start with Docker:

   docker-compose up -d

   Access the API at http://localhost:8000/api/docs

4. Without Docker (local development):

   # Create virtual environment
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Install dependencies
   pip install -r requirements.txt
   
   # Run migrations
   alembic upgrade head
   
   # Start the application
   uvicorn app.main:app --reload

🏗️ Project Structure

.
├── app/
│   ├── api/                    # API modules
│   │   ├── authentication/     # Authentication module
│   │   ├── authorization/      # Authorization module
│   │   └── users/             # Users module
│   ├── commons/               # Shared utilities
│   │   ├── models.py          # Base models
│   │   ├── repository.py      # Base repository
│   │   └── schemas.py         # Base schemas
│   ├── configs/              # Configuration
│   └── main.py              # Application entry point
├── deployments/             # Deployment configurations
├── migrations/             # Database migrations
└── tests/                 # Test suite

🔒 Authentication & Authorization

The template includes a comprehensive RBAC system:

• Roles: Group permissions for easier management
• Permissions: Fine-grained access control
• Users: Associated with roles for authorization

Example usage:

# Protect an endpoint with permissions
@router.post("/items")
async def create_item(
    item: ItemCreate,
    user: User = Depends(get_current_user),
    has_permission: bool = Depends(require_permission("item:create"))
):
    return await service.create_item(item)

🛠️ Development

Running Tests

pytest

Running Migrations

# Create a new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback migration
alembic downgrade -1

Code Quality

# Run linting
flake8 .

# Run type checking
mypy .

📚 API Documentation

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc
• OpenAPI JSON: http://localhost:8000/api/openapi.json

🔧 Configuration

Key configuration options in .env:

# PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=fastapi_db

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# Application
DEBUG=false
JWT_SECRET_KEY=your-secret-key

🚢 Deployment

The template includes Docker configurations for easy deployment:

# Build and start services
docker-compose -f docker-compose.yml up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📜 License

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

✨ Acknowledgments

• FastAPI for the amazing framework
• SQLAlchemy for the ORM
• Alembic for database migrations
• Pydantic for data validation