FastAPI Production Archetype

Description

This is a FastAPI project archetype for production-ready applications. It provides a structure for building scalable and maintainable applications with FastAPI following Domain Driven Design (DDD) principles, best Docker practices, and a set of tools for development, testing, and deployment with the best code quality tools available.

Table of Contents

• FastAPI Production Archetype
  • Description
  • Table of Contents
  • Contributing
  • Generate a New Project
  • Security and User Management
  • Background Tasks
  • Getting Started
    • Built With
    • Prerequisites
    • Running the App
      • Terminal
      • VSCode
      • Docker
    • Development
  • Roadmap

Contributing

Check the contributing documentation for more information.

Generate a New Project

This repository doubles as a Cookiecutter template: it generates a standalone project with this exact structure, best practices and tooling preconfigured, depending on the published fastapi-crud-base library for the generic CRUD layer.

uvx cookiecutter gh:n0nuser/fastapi-archetype --directory cookiecutter

You will be prompted for a project name, description, author and versions; everything else (structure, CI, Docker, Spectral ruleset, migrations) comes ready out of the box.

Security and User Management

Registration, JWT authentication, password reset and role-based access control ship by default via fastapi-users. See docs/security.md for endpoints, configuration and how to protect your own endpoints with current_user / current_superuser.

Background Tasks

Heavy work is offloaded to Celery workers over a Redis broker, with Flower monitoring at port 5555. See docs/celery.md.

Getting Started

Built With

Development:

• Python 3: The programming language used.
• uv: A fast tool for dependency management and packaging in Python.
• FastAPI: A modern, fast (high-performance), web framework for building APIs with Python based on standard Python type hints.
• Pydantic: Data validation and settings management using Python type annotations.
• HTTPX: A fully featured HTTP client for Python 3, which provides sync and async APIs, and support for both HTTP/1.1 and HTTP/2.

Security:

• fastapi-users: Registration, JWT authentication and user management. See docs/security.md.

Background Tasks:

• Celery: Distributed task queue for heavy workloads.
• Flower: Web UI for monitoring Celery. See docs/celery.md.

Development Tools:

• Pre-Commit: A framework for managing and maintaining multi-language pre-commit hooks.
• Ruff: An extremely fast linter and formatter (linting, style checks, and security rules) for Python.

Databases:

• SQLAlchemy: The Python SQL Toolkit and Object-Relational Mapping (ORM) library.
• PostgreSQL: A powerful, open-source object-relational database system.
• Alembic: A database migrations tool for SQLAlchemy. See our Alembic documentation.

Deployment:

• Uvicorn: A lightning-fast ASGI server implementation, using uvloop and httptools.
• Docker: A set of platform as a service (PaaS) products that use OS-level virtualization to deliver software in packages called containers.
• Docker-Compose: A tool for defining and running multi-container Docker applications.
• Traefik / Nginx: Optional reverse proxy overlays with automatic HTTPS (Traefik).
• Prometheus: Metrics exposed at /metrics via prometheus-fastapi-instrumentator.
• OpenTelemetry: Opt-in distributed tracing (OTEL_ENABLED=true).
• Redis: Opt-in response caching (CACHE_ENABLED=true).

Testing:

• Pytest: A framework that makes it easy to write simple and scalable tests.
• Pytest-Cov: Coverage reporting with a configurable CI floor.
• Spectral: OpenAPI specification linting in CI and pre-commit.
• Cookiecutter: This repository doubles as a project template (see Generate a New Project).

Prerequisites

• Python 3.12 or higher
• uv: uv is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. For documentation refer to uv or to a little guide we made here.
• Docker: Docker is a set of platform as a service (PaaS) products that use OS-level virtualization to deliver software in packages called containers. For documentation refer to Docker.

Running the App

You need to have the environment set up with uv by using uv sync and the dependencies will be installed. After that, you can start the application.

Terminal

To start the application, run the following command:

uvicorn src.app:app --reload --port 8000

This will start the application on port 8000. You can change the port by changing the --port argument.

VSCode

In VSCode you can use the Run button on the top right corner of the editor to start the application as the launch.json file is already set up.

Docker

Also, you can use the docker-compose to start the application with the following command:

cd docker
docker-compose up

If you don't know how to use Docker, you can check the Docker documentation and our deployment documentation.

Development

Important

Be sure to:

• Run pre-commit install to install the pre-commit hooks. This will run the linters and formatters before you commit your code. If you don't have pre-commit installed in your system, you can install it with pip install pre-commit.
• Check the project structure documentation for more information.
• Check the recommended extensions documentation for more information.
• Check the contributing documentation for more information.
• Check the deployment documentation for more information.

Testing

Most of the suite is marked as integration because it exercises real Postgres behaviour. Start the ephemeral test database first:

docker compose -f docker/docker-compose.test.yml up -d db-test

Then run everything with coverage:

uv run pytest --cov=src --cov-report=term-missing

The database connection is configured through TEST_DATABASE_URL (defaults to the compose instance on port 5433). CI spins up its own Postgres service container, so no extra setup is needed there.

Roadmap

See the open issues for a full list of proposed features (and known issues).