FastAPI Lab

A modern FastAPI project using uv for blazing-fast dependency management and just for task automation.

⚡ Quick Start

# Install just (one-time setup)
brew install just

# Setup and run
just setup
just run

# Visit http://localhost:8000/docs

Why This Stack?

• FastAPI: Modern, fast Python web framework with automatic API documentation
• uv: 10-100x faster than pip with automatic virtual environment management
• just: Simple task runner for consistent command execution
• Ruff: Lightning-fast linting and formatting
• Docker: Production-ready containerization with development hot-reload

Prerequisites

• Python 3.14+
• just: brew install just (other platforms)
• uv: Installed automatically by just setup

Setup

# Complete setup (installs uv, dependencies)
just setup

# Or step by step
just install-uv      # Install uv if needed
just install         # Install dependencies

Development

Common Commands

just                 # List all commands
just run             # Run the app (with hot-reload)
just test            # Run tests
just test-cov        # Run tests with coverage
just format          # Format code
just lint            # Check code
just check           # Run all quality checks
just fix             # Format and auto-fix issues
just clean           # Clean cache files

Docker Commands

just docker-dev         # Run in development container
just docker-prod        # Run in production container
just docker-down        # Stop all containers
just docker-build-dev   # Build dev image only
just docker-build-prod  # Build prod image only

Managing Dependencies

just add package-name        # Add production dependency
just add-dev package-name    # Add dev dependency
just remove package-name     # Remove dependency
just update                  # Update all dependencies
just outdated                # Show outdated packages

Try the API

Once running, try these:

# Hello World
curl http://localhost:8000/api/v1/

# Get an item
curl http://localhost:8000/api/v1/items/42?q=test

# Update an item
curl -X PUT http://localhost:8000/api/v1/items/42 \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Item", "price": 99.99}'

API Documentation

• Interactive Docs (Swagger): http://localhost:8000/docs
• Alternative Docs (ReDoc): http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/api/v1/openapi.json

Project Structure

fast-api-lab/
├── app/                        # Application code
│   ├── api/v1/                # API version 1
│   │   ├── endpoints/         # API endpoint modules
│   │   └── router.py          # API router
│   ├── core/                  # Core functionality (events, middleware)
│   ├── schemas/               # Pydantic models
│   ├── services/              # Business logic layer
│   ├── utils/                 # Utility functions
│   ├── config.py              # Application configuration
│   └── main.py                # FastAPI app factory
├── tests/                      # Test suite
│   ├── api/v1/                # API endpoint tests
│   └── conftest.py            # Pytest configuration
├── main.py                     # Application entry point
├── pyproject.toml              # Dependencies and tool configuration
├── uv.lock                     # Locked dependency versions (commit this!)
├── justfile                    # Task runner commands
├── Dockerfile                  # Production container
├── Dockerfile.dev              # Development container (with hot-reload)
├── docker-compose.yml          # Multi-container orchestration
├── .pre-commit-config.yaml     # Pre-commit hooks configuration
└── .github/workflows/ci.yml    # CI/CD pipeline

Docker

Two Docker configurations for different use cases:

Development (with hot-reload)

just docker-dev
# Or: docker compose up

• Uses Dockerfile.dev with all dev tools (just, pre-commit)
• Code mounted as volumes for live reload
• Includes all dev dependencies
• Runs with just run (FastAPI dev mode)

Production (optimized)

just docker-prod
# Or: docker compose --profile prod up api-prod

• Uses Dockerfile (minimal production image)
• Only production dependencies included
• Code baked into the image (no volumes)
• Runs with uv run fastapi run (production mode)

Manual Docker Build

# Development
docker build -f Dockerfile.dev -t fast-api-lab:dev .
docker run -p 8000:8000 -v ./app:/app/app fast-api-lab:dev

# Production
docker build -t fast-api-lab:prod .
docker run -p 8000:8000 fast-api-lab:prod

Configuration

Application settings are configured in app/config.py using Pydantic Settings:

• Supports environment variables via .env file
• Default API prefix: /api/v1
• Configuration: pyproject.toml (dependencies, tool settings)
• Lock file: uv.lock (exact dependency versions - commit this!)

CI/CD

GitHub Actions workflow included (.github/workflows/ci.yml):

• ✅ Automated tests on Ubuntu and macOS
• ✅ Python 3.14 support
• ✅ Linting, type checking, and coverage reporting
• ✅ Codecov integration ready

Troubleshooting

Issue	Solution
just: command not found	brew install just or see installation guide
uv: command not found	Run just setup (installs uv automatically)
Port 8000 already in use	just serve 0.0.0.0 8001
Dependency issues	just clean && just install
Pre-commit hooks failing	just fix (auto-fix) then just check (verify)

Advanced Usage

Using uv directly (instead of just)

uv sync --all-extras         # Install all dependencies
uv run fastapi dev           # Run development server
uv run pytest                # Run tests
uv run ruff format .         # Format code
uv run ruff check . --fix    # Lint and auto-fix
uv run mypy .                # Type check
uv add package-name          # Add production dependency
uv add --dev package-name    # Add dev dependency

Resources

• FastAPI Documentation
• uv Documentation
• just Documentation

Best Practices

• ✅ Run just check before committing
• 🎨 Use just format for consistent code style
• 📦 Always commit uv.lock for reproducible builds
• 🪝 Pre-commit hooks run automatically (configured via .pre-commit-config.yaml)
• 📖 Use /docs for interactive API testing
• 🧪 Write tests for all new features

---

Ready to build something awesome? Start coding! 🚀