fastapi-template

A template for projects that use the FastAPI framework.

How to use this template

Choose a template branch

Currently these two branches are available:

• develop: Contains a basic FastAPI template using SQLAlchemy and aioredis, including basic logging, optional token authentication, utilities to simplify documentation creation and some demo endpoints, as well as a Dockerfile to create a Docker image and a GitHub Actions workflow to automatically build and push the Docker image to GitHub Container Registry.
• users: Contains everything included in the develop branch and implements basic user management functionality. This includes endpoints for user creation, session management and administration as well as features such as 2FA via TOTP, generic OAuth2 and reCAPTCHA on account creation and/or too many failed login attempts.

Replace TEMPLATE_BRANCH in the next section with the branch you would like to use.

Setup repository

1. Click the Use this template button to generate a new repository
2. git clone your new repository
3. Add this repository as a template remote: git remote add template https://github.com/Defelo/fastapi-template.git && git fetch template
4. Reset your branch to the template branch you would like to use: git reset --hard template/TEMPLATE_BRANCH
5. Force push your branch to GitHub: git push -f

To later update your repository you can just merge the template into your own branch: git fetch template && git merge template/TEMPLATE_BRANCH

Customize template files

1. Adjust name, description, authors, homepage and repository in pyproject.toml
2. Adjust repository url in Dockerfile
3. Adjust docker image tag in docker-compose.yml and .github/workflows/ci.yml
4. (optional) Enable additional platforms for docker buildx in .github/workflows/ci.yml
5. Enable docker push in .github/workflows/ci.yml by removing the "false" #
6. (optional) Adjust .github/workflows/ci.yml to enable automatic deployment by sending an HTTP request to a specific url
7. (optional) If you don't want your dependabot pull requests to be merged automatically, remove the .github/workflows/merge-me.yml workflow
8. (optional) If you want to automatically delete unused docker tags from GHCR:
   1. Adjust repository owner and name in .github/workflows/docker_clean.yml
   2. Uncomment the workflow triggers in .github/workflows/docker_clean.yml
   3. Create a personal access token with delete:packages permissions
   4. Create a new docker-clean environment, allow only develop as deployment branch and create a CR_PAT secret that contains the personal access token

Development

Prerequisites

• Python 3.10
• Poetry + poethepoet
• Git
• Docker + docker-compose (recommended)
• PyCharm Community/Professional (recommended)

Clone the repository

SSH (recommended)

git clone --recursive git@github.com:Defelo/fastapi-template.git

HTTPS

git clone --recursive https://github.com/Defelo/fastapi-template.git

Setup development environment

After cloning the repository, you can setup the development environment by running the following command:

poe setup

This will create a virtual environment, install the dependencies, create a .env file and install the pre-commit hook.

PyCharm configuration

Configure the Python interpreter:

• Open PyCharm and go to Settings ➔ Project ➔ Python Interpreter
• Open the menu Python Interpreter and click on Show All...
• Click on the plus symbol
• Click on Poetry Environment
• Select Existing environment (setup the environment first by running poe setup)
• Confirm with OK

Setup the run configuration:

• Click on Add Configuration... ➔ Add new... ➔ Python
• Change target from Script path to Module name and choose the api module
• Change the working directory to root path ➔ Edit Configurations ➔ Working directory
• In the EnvFile tab add your .env file
• Confirm with OK

Run the API

To run the api for development you can use the api task:

poe api

Poetry Scripts

poe setup           # setup dependencies, .env file and pre-commit hook
poe api             # start api locally
poe test            # run unit tests
poe pre-commit      # run pre-commit checks
  poe lint          # run linter
    poe format      # run auto formatter
      poe isort     # sort imports
      poe black     # reformat code
    poe mypy        # check typing
    poe flake8      # check code style
  poe coverage      # run unit tests with coverage
poe alembic         # use alembic to manage database migrations
poe migrate         # run database migrations
poe env             # show settings from .env file
poe jwt             # generate a jwt with the given payload and ttl in seconds