This is a template Repository for starting a new FastAPI project with Authentication and Users, with Authorization already baked-in.
Documentation for this project is now availiable on it's own page at https://api-template.seapagan.net. This is a work in progress, and when finished will include full usage information and how-to's.
This template versioning has been refactored to start from Version 0.4.0.
The original template was written for my own use and probably promoted to V1.0.0 before it should have been, and there have been many updates and fixes since then.
I will keep the old releases available for those who wish to use them (for a short time). It's better to do this now before more users need to update their projects to future versions.
All releases from now on will also contain a Git patch to upgrade from the
previous version. This will be in the form of a .patch
file which can be
applied to their project using the git apply
command. This will be documented
in the release notes.
Starting from version 0.5.0, the template has been refactored to use SQLAlchemy
2.0 ORM instead of encode/databases
for database access. This allows for a
more flexible and powerful Asynchronous database access but does need a bit of
refactoring for any existing projects. See the documentation for
more information. I will also be adding a migration guide for those who wish to
upgrade their existing projects (time permitting).
If you prefer to continue using the 0.4.x branch, you can find it here.
To use this branch you will need to clone the repository and checkout the
0.4.2
branch.
git clone -b 0.4.2 https://github.com/seapagan/fastapi-template.git
Be aware that this branch will not be maintained and will not receive any updates or bug fixes.
This template is a ready-to-use boilerplate for a FastAPI project. It has the following advantages to starting your own from scratch :
Refresh Token
with 30 day expiry is sent at time of register or login
(never again). This will enable easy re-authentication when the JWT expires
without needing to send username or password again, and should be done
automatically by the Front-End..env
file if that is provided.This template is still in very active development and probably not yet ready for full production use. However, I am currently using it to develop my own projects, which include some production API's without issues. I will update the template as I find bugs or add new features. I will also be adding more documentation as I go. For the moment, if you wish to use it without getting involved in dev, I'd recommend checking out the latest actual Release.
However, the main
branch should be pretty stable as all development is done on
the develop
branch and merged into main
when ready.
The template Requires Python 3.9.0 or higher. I actually develop under Python 3.12.x where x is the latest version available at the time, and migrating to the next patch version as soon as it is released. CI tests are run automatically on Python 3.9, 3.10, 3.11 and 3.12.
This template is free to use but I would request some accreditation. If you do use it in one of your applications, please put a small note in your readme stating that you based your project on this Template, with a link back to this repository. Thank You π
For those who let me know they are using this Template, I'll add links back to your project in this documentation.
If this template saves you time/effort/money, or you just wish to show your appreciation for my work, why not Sponsor my Work or Buy me a Coffee! π
Click the 'Use this template' button at the top of the Repository on GitHub. This will create a new repository in your personal GitHub account (Not a Fork) which you can then Clone and start working on.
It is assumed that you have at least some knowledge of FastAPI to use this template, there are very good Basic and Advanced User Guides on the FastAPI website .
Visit the Installation Instructions for more detailed installation notes, including how to handle the coverage uploader.
Note that when run from docker, the API is exposed on port 8001
instead of
8000
.
Also, unlike before version 0.5.1, it is no longer required to change the
DB_ADDRESS
environment variable when running on docker, this is taken care of
automatically.
:warning: For local use rename
.env.example
to.env
.
It is possible to develop directly on Docker containers :
Using docker compose up
(recommended):
docker compose up
To run and rebuild image (dependency updates):
docker compose up --build
To remove all containers:
docker compose down
Using docker compose run
:
First run migrations:
docker compose run --rm api alembic upgrade head
Run containers:
docker compose run --rm --service-ports api uvicorn --host 0.0.0.0 main:app --reload
To rebuild image (dependency updates):
docker compose build
Running migrations on Docker container is also possible:
docker compose run --rm api alembic upgrade head
Running tests on Docker container is also possible:
docker compose run --rm api pytest
See the TODO.md file for plans.
This project has a test suite for Integration and Unit tests. We use pytest for this.
Currently you need a Postgresql database running for this to work, however SQLite support is planned to be re-added. You can easily set up a Postgresql database using Docker.
Before running the tests, you need to create a dedicated test database, in is assumed that the server, username and password are the same as for the main database.
Edit the setting in .env
to point to the test database:
# Database name to use for testing. This must already exist.
TEST_DB_NAME=api-template-test
You can then migrate this empty database by running:
$ api-admin test setup
Migrating the test database ... Done!
Tests can then be run from the checked out code with:
$ pytest
It is possible to run either the Unit or Integration tests separately using
pytest -m unit
or pytest -m integration
Full tests will be run automatically by GitHub Actions on every new commit pushed up to the remote repository. Code Coverage is also checked and noted after each test suite is run.
To be written
See the BUGS.md file for known bugs.
Meh, at the moment probably no-one except me π. If you do use this in one of your own projects, drop me a message and I'll add your profile and project links here π.
See Contributing for details on how to contribute to this project.
I have enabled Discussions on this repository, so if you have any questions, suggestions or just want to chat about this template, please feel free to start a discussion.