fastapi-starter

Production-ready FastAPI starter — PostgreSQL, JWT auth, Alembic migrations, Docker, pytest, ruff, mypy. Clone and ship.

---

Features

• ⚡ FastAPI with async support and auto-generated docs (/docs, /redoc)
• 🔐 JWT Authentication — access + refresh tokens, bcrypt password hashing
• 🗄️ PostgreSQL via SQLAlchemy 2.x (sync) with connection pooling
• 🔄 Alembic migrations — auto-generates from models
• 🐳 Docker + docker-compose — one command to run everything
• 🧪 pytest — 8 tests, 81% coverage out of the box
• 🔍 ruff linting + formatting, mypy type checking
• ⚙️ GitHub Actions CI — runs on every push

---

Project Structure

src/app/
├── api/v1/
│   ├── endpoints/
│   │   ├── auth.py        # register, login, refresh, /me
│   │   └── users.py       # CRUD endpoints
│   ├── deps.py            # get_current_user, get_current_superuser
│   └── router.py
├── core/
│   ├── config.py          # pydantic-settings (reads .env)
│   └── security.py        # JWT + bcrypt
├── db/
│   └── session.py         # engine, SessionLocal, get_db()
├── models/
│   └── user.py            # SQLAlchemy User model
├── schemas/
│   └── user.py            # Pydantic request/response schemas
├── services/
│   └── user_service.py    # business logic layer
└── main.py                # FastAPI app + CORS + routes

---

Quick Start

Option 1 — Docker (recommended)

git clone https://github.com/lakshmana64/fastapi-starter.git
cd fastapi-starter
cp .env.example .env
docker-compose up --build

API live at http://localhost:8000/docs

Option 2 — Local

git clone https://github.com/lakshmana64/fastapi-starter.git
cd fastapi-starter
cp .env.example .env          # edit DATABASE_URL to your local Postgres
pip install -e ".[dev]"
alembic upgrade head
uvicorn src.app.main:app --reload

---

API Endpoints

Method	Endpoint	Auth	Description
POST	/api/v1/auth/register	—	Register new user
POST	/api/v1/auth/login	—	Login → access + refresh tokens
POST	/api/v1/auth/refresh	—	Exchange refresh token
GET	/api/v1/auth/me	✅	Get current user
GET	/api/v1/users/	superuser	List all users
GET	/api/v1/users/{id}	✅	Get user by ID
PATCH	/api/v1/users/{id}	✅	Update user
DELETE	/api/v1/users/{id}	superuser	Delete user
GET	/health	—	Health check

---

Development

# Run tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=src --cov-report=term-missing

# Lint
ruff check .

# Type check
mypy src/ --ignore-missing-imports

# Create a migration
alembic revision --autogenerate -m "add new table"
alembic upgrade head

---

Configuration (.env)

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app
SECRET_KEY=your-secret-key-here          # openssl rand -hex 32
DEBUG=false
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
ALLOWED_ORIGINS=["http://localhost:3000"]

---

Built by

lakshmana64 — Python Developer · AI Agent Automation · Bengaluru, IN

---

License

MIT