FastAPI Boilerplate

FastAPI Boilerplate is a minimal template for creating FastAPI applications with a clean project structure and best practices.

---

Table of Contents

• Overview
• Getting Started
  • Local Development
  • Running the API
  • Testing
  • Code Quality
• Build and run
• Environment Variables
• License

Overview

The FastAPI Boilerplate is a minimal and production-ready template for quickly setting up FastAPI applications. It provides a clean and organized project structure with best practices to help you get started with building APIs efficiently. This boilerplate includes:

• Modular Structure: Organized into clear directories for routes, schemas, core configurations, etc.
• Environment Variables: Easily configurable settings through environment variables, ensuring flexibility in various environments (development, staging, production).
• Testing Support: Built-in testing framework using pytest to ensure reliable and robust applications.
• Pre-commit Hooks: Automatic code formatting and linting before each commit to maintain code quality.
• Docker Support: Preconfigured Docker setup for containerized deployments, making it easier to deploy the app anywhere.
• Extensibility: The structure is designed to be easily extended with additional functionality, allowing developers to customize it for their specific needs.

Whether you're building a simple REST API or a complex microservice, this boilerplate serves as a solid foundation for your FastAPI projects.

Getting Started

Local Development

To set up the project locally, follow these steps:

1. Clone this repository:

   git clone https://github.com/sotberd/fastapi-boilerplate.git

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate

3. Install the development dependencies:

   pip install -r requirements.dev.txt

Running the API

To start the API server, run:

fastapi dev --host 0.0.0.0 --port 8000

You can then use the following curl commands to interact with the API:

curl -X GET http://localhost:8000/api/v1/health

Testing

Testing is crucial for maintaining the reliability of the API. This project uses pytest for testing.

./scripts/test.sh

open htmlcov/index.html

Code Quality

To maintain code quality, this project uses pre-commit hooks. These hooks can automatically format and lint your code before commits.

1. Install pre-commit hooks:

   pre-commit install

2. Run pre-commit hooks:

   pre-commit run --all-files

3. Formatting:

   To automatically format your code, use the following script:

   ./scripts/format.sh

Build and Run

This project uses Docker for containerization, simplifying deployment across various environments.

1. Build the Docker image:

   docker build -t fastapi-boilerplate .

2. Run the Docker container for the API:

   docker run -d -p 8000:8000 fastapi-boilerplate fastapi run --host 0.0.0.0 --port 8000

   ℹ️ The API will be accessible at http://localhost:8000.

Environment Variables

To configure the behavior of the API, you can use the following environment variables:

• DEBUG: Enable or disable debug mode. Default is True.
• APP_NAME: Name of the application. Default is "FastAPI Boilerplate".
• API_V1_STR: API versioning string. Default is "/api/v1".
• DOCS_URL: URL for the Swagger documentation. Default is "/docs".
• REDOC_URL: URL for the ReDoc documentation. Default is "/".
• OPENAPI_JSON_PATH: Path to the OpenAPI spec file. Default is "./openapi.json".
• VERSION: API version. Default is "1.0.0".
• BACKEND_CORS_ORIGINS: A JSON-formatted list of allowed CORS origins, e.g., ["http://localhost:3000"]. Default is an empty list [].
• API_KEY_NAME: The name of the header for the API key. Default is "X-API-KEY".
• API_KEYS: A list of allowed API keys for authentication. Default is an empty list [].

These variables can be set in your environment or passed as part of your Docker configuration.

License

This project is licensed under the terms of the MIT.