fastapi-auth-starter 0.1.11

A clean architecture FastAPI starter template with authentication, PostgreSQL, and Alembic migrations

FastAPI Auth Starter

A clean architecture FastAPI project starter with PostgreSQL and Alembic migrations.

Quick Start

Create a new project from this template:

# Install the package (globally or in a separate environment)
uv pip install fastapi-auth-starter
# Or use uvx to run without installing:
# uvx fastapi-auth-starter init my-project

# Initialize a new project
fastapi-auth-starter init my-project
# Or initialize in current directory
fastapi-auth-starter init .

Note: The fastapi-auth-starter CLI tool is a scaffolding utility, not a runtime dependency. If you install it in your project's virtual environment and then run uv sync, it will be removed (this is expected behavior). Install it globally or use uvx to avoid this.

See PACKAGING.md for more installation options.

Project Structure

fastapi_auth_starter/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI application entry point
│   ├── api/
│   │   └── v1/
│   │       ├── api.py       # API router aggregation
│   │       └── routes/
│   │           └── health.py  # Health check endpoint
│   ├── core/
│   │   ├── config.py        # Application configuration
│   │   └── database.py      # Database connection and session management
│   ├── models/              # SQLAlchemy database models
│   ├── services/            # Business logic services
│   └── db/                  # Database utilities
├── alembic/                 # Database migration scripts
├── alembic.ini              # Alembic configuration
├── pyproject.toml           # Project dependencies (uv)
└── README.md

Features

• ✅ Clean architecture with separation of concerns
• ✅ FastAPI with async SQLAlchemy
• ✅ PostgreSQL database support
• ✅ Alembic for database migrations
• ✅ Health check endpoint
• ✅ Dependency injection with FastAPI
• ✅ Environment-based configuration

Prerequisites

• Python 3.12+ (3.13 for local dev, 3.12 for Vercel deployment)
• uv package manager
• PostgreSQL database (local or remote)

Setup

1. Install Dependencies

Dependencies are managed with uv. They are automatically installed when you run commands with uv run.

2. Configure Environment Variables

Important: Copy the example environment file and configure your settings:

cp .env.example .env

Then edit .env with your configuration:

# Database Configuration
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/fastapi_auth

# API Configuration (optional - defaults are fine)
API_V1_PREFIX=/api/v1
PROJECT_NAME=FastAPI Auth Starter
VERSION=0.1.0

Note:

• The .env file is gitignored and should not be committed
• The application uses asyncpg for async operations, but Alembic uses psycopg2 for migrations (sync driver)
• All sensitive configuration should be in .env file, not hardcoded

3. Initialize Database

First, ensure PostgreSQL is running and create the database:

createdb fastapi_auth

Or using PostgreSQL client:

CREATE DATABASE fastapi_auth;

4. Run Migrations

# Create initial migration (if needed)
uv run alembic revision --autogenerate -m "Initial migration"

# Apply migrations
uv run alembic upgrade head

Quick Start with Package (For New Projects)

If you want to use this as a starter template for a new project:

# Install the package
uv pip install fastapi-auth-starter

# Initialize a new project
fastapi-auth-starter init my-project

# Or initialize in current directory
fastapi-auth-starter init .

Then follow the setup steps in the new project directory.

Running the Application

Development Server

uv run uvicorn app.main:app --reload

The API will be available at:

• API: http://localhost:8000
• Docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Health Check

Test the health endpoint:

curl http://localhost:8000/api/v1/health

Expected response:

{
  "status": "healthy",
  "message": "Service is running"
}

Development

Adding New Routes

1. Create a new route file in app/api/v1/routes/
2. Import and include the router in app/api/v1/api.py

Example:

# app/api/v1/routes/users.py
from fastapi import APIRouter

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/")
async def get_users():
    return {"users": []}

Then add to app/api/v1/api.py:

from app.api.v1.routes import users
api_router.include_router(users.router)

Adding Database Models

1. Create model in app/models/
2. Import in app/models/__init__.py
3. Import in alembic/env.py (for autogenerate)

Example:

# app/models/user.py
from sqlalchemy import Column, Integer, String
from app.core.database import Base

class User(Base):
    __tablename__ = "users"
    
    id = Column(Integer, primary_key=True)
    email = Column(String, unique=True, index=True)

Creating Migrations

# Auto-generate migration from model changes
uv run alembic revision --autogenerate -m "Description of changes"

# Create empty migration
uv run alembic revision -m "Description of changes"

Applying Migrations

# Apply all pending migrations
uv run alembic upgrade head

# Rollback one migration
uv run alembic downgrade -1

# Rollback to specific revision
uv run alembic downgrade <revision>

Architecture

Layers

• API Layer (app/api/): Route handlers, request/response models
• Service Layer (app/services/): Business logic, domain operations
• Model Layer (app/models/): SQLAlchemy database models
• Core Layer (app/core/): Configuration, database setup, utilities

Dependency Injection

FastAPI's dependency injection is used throughout:

• Database sessions via get_db() dependency
• Configuration via settings object
• Custom dependencies in app/core/dependencies.py (create as needed)

Deployment

Vercel Deployment

1. Install Dev Dependencies Locally:

   uv sync  # Installs all dependencies including dev
   

2. Set Environment Variables in Vercel:

   • Go to your project settings in Vercel
   • Add DATABASE_URL environment variable with your PostgreSQL connection string
   • Format: postgresql+asyncpg://user:password@host:port/database

3. Deploy:

   vercel --prod
   

Note:

• Runtime dependencies don't include psycopg2-binary or alembic (only needed for local migrations)
• Python 3.12 is used (Vercel doesn't support 3.13 yet)
• Make sure to run migrations on your database before deploying

References

• FastAPI Documentation
• SQLAlchemy Async Documentation
• Alembic Documentation
• uv Documentation
• Vercel Python Documentation

License

MIT