⚡ FastAPI API Template

This template provides a robust starting point for building APIs with FastAPI. It includes user authentication, CRUD operations, JWT token-based authentication, and PostgreSQL integration. The setup is streamlined with Docker and includes comprehensive documentation and testing tools.

📌 Features

• 🔐 User authentication with basic login and Google Auth
• 👥 User management with creation and CRUD operations
• 📄 Example endpoints for Posts, Users, and Votes
• 💓 API healthcheck endpoint
• 🔑 JWT token-based authentication
• ⚙️ Middleware support
• 🌎 CORS configuration
• 📝 Comprehensive Swagger API documentation
• 🐘 PostgreSQL database integration
• 🔒 Field encryption for sensitive data

💾 Installation

Important

Min Python version: 3.14

Clone this repo:

git clone https://github.com/ezeparziale/fastapi-api-template

Create virtual environment:

python -m venv env

Activate environment:

• Windows:

. env/scripts/activate

• Mac/Linux:

. env/bin/activate

Upgrade pip:

python -m pip install --upgrade pip

Install requirements:

pip install -r requirements-dev.txt

Install pre-commit:

pre-commit install

🔧 Config

Create .env file. Check the example .env.example

🌐 Google Auth credentials:

Create your app and obtain your client_id and secret:

https://developers.google.com/workspace/guides/create-credentials

🔒 How to create a secret key:

openssl rand -base64 64

🔐 How to create an encryption key:

To create an encryption key for securing sensitive data, you can use the generate_key.py script provided in the repository. Run the following command:

python generate_key.py

This will generate a secure encryption key.

🚧 Before first run:

Run docker-compose 🐳 to start the database server

docker compose -f "compose.yaml" up -d --build adminer db

and init the database with alembic:

alembic upgrade head

🔑 Create a self-signed certificate with openssl:

openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365

🏃 Run

uvicorn app.main:app --reload --port 8000 --ssl-keyfile key.pem --ssl-certfile cert.pem

🚨 Lint

Run linter and formatter

scripts/lint.sh

scripts/format.sh

🧑‍💻 Coverage

Run coverage

coverage run -m pytest

coverage report --show-missing

coverage html

Or run all in one with:

scripts/coverage.sh

🧪 Test

Run pytest with coverage

coverage run -m pytest

or

scripts/test.sh

🛠️ Alembic

Alembic is used for database migrations. Below are some common commands to manage your database schema.

Autogenerate a revision

To autogenerate a new revision based on the changes detected in your models, run:

alembic revision --autogenerate -m "your message here"

Generate a blank revision

To create a blank revision for custom migrations, run:

alembic revision -m "your message here"

Upgrade the database

To apply the latest migrations and upgrade the database schema, run:

alembic upgrade head

Downgrade the database

To revert the last migration and downgrade the database schema, run:

alembic downgrade -1

After creating a revision, you can edit the generated script to define your custom migrations.

📊 Monitoring

This project includes a complete observability stack using Grafana, Loki, and Promtail.

🚀 Setup

1. Start the monitoring stack:

   docker compose up -d grafana loki promtail

2. Access Grafana: Open http://localhost:3000 in your browser.

   • Default credentials: admin / admin

3. Add Loki Data Source:

   • Go to Connections > Data sources.
   • Click Add data source and select Loki.
   • Set the URL to: http://loki:3100.
   • Click Save & test.

🎚️ Create Dashboard with Variables

To visualize logs efficiently, follow these steps to create a dashboard with a level filter:

1. Create a New Dashboard:
   • Click the + icon > Dashboard.
2. Add a Variable for Log Level:
   • Go to Dashboard Settings (gear icon) > Variables.
   • Click Add variable.
   • Name: level
   • Type: Custom
   • Custom options (Values separated by comma): TRACE,DEBUG,INFO,SUCCESS,WARNING,ERROR,CRITICAL
   • Click Apply.
3. Add a Logs Panel:
   • Add a new Visualization.
   • Select Loki as the data source.
   • Use the following LogQL query:

     {container="app"} | json | record_level_name =~ "$level" | line_format "{{.record_message}}"
     

   • This query filters logs by the app container, parses the JSON format, filters by the selected $level variable, and cleans up the output message.