{"id":18438657,"url":"https://github.com/seapagan/fastapi-template","last_synced_at":"2025-04-04T17:05:21.198Z","repository":{"id":62107388,"uuid":"550350069","full_name":"seapagan/fastapi-template","owner":"seapagan","description":"A Configurable template for a FastAPI application, with Authentication, User integration, Admin pages and a snappy CLI to control it all!","archived":false,"fork":false,"pushed_at":"2025-03-24T14:05:39.000Z","size":15689,"stargazers_count":177,"open_issues_count":5,"forks_count":13,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-28T16:08:03.161Z","etag":null,"topics":["alembic","api-keys","async","async-test","asynchronous","fastapi","jwt","jwt-authentication","postgresql","pytest","python","sqladmin","sqlalchemy","sqlalchemy2","template"],"latest_commit_sha":null,"homepage":"https://api-template.seapagan.net","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seapagan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"seapagan","patreon":null,"open_collective":null,"ko_fi":"grantramsay","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"buy_me_a_coffee":"seapagan"}},"created_at":"2022-10-12T16:00:02.000Z","updated_at":"2025-03-28T02:36:57.000Z","dependencies_parsed_at":"2024-02-06T14:13:58.711Z","dependency_job_id":"f7fcab94-1f41-4d4a-bc5b-bf2941dbb309","html_url":"https://github.com/seapagan/fastapi-template","commit_stats":null,"previous_names":[],"tags_count":26,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seapagan%2Ffastapi-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seapagan%2Ffastapi-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seapagan%2Ffastapi-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seapagan%2Ffastapi-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seapagan","download_url":"https://codeload.github.com/seapagan/fastapi-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217174,"owners_count":20903008,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alembic","api-keys","async","async-test","asynchronous","fastapi","jwt","jwt-authentication","postgresql","pytest","python","sqladmin","sqlalchemy","sqlalchemy2","template"],"created_at":"2024-11-06T06:21:03.387Z","updated_at":"2025-04-04T17:05:21.151Z","avatar_url":"https://github.com/seapagan.png","language":"Python","readme":"# FastAPI Application Template \u003c!-- omit in toc --\u003e\n\n![GitHub Release](https://img.shields.io/github/v/release/seapagan/fastapi-template)\n[![Ruff](https://github.com/seapagan/fastapi-template/actions/workflows/ruff.yml/badge.svg)](https://github.com/seapagan/fastapi-template/actions/workflows/ruff.yml)\n[![Tests](https://github.com/seapagan/fastapi-template/actions/workflows/tests.yml/badge.svg)](https://github.com/seapagan/fastapi-template/actions/workflows/tests.yml)\n[![Code Coverage](https://app.codacy.com/project/badge/Coverage/82085ec100b64e73bea63b5942371e94)](https://app.codacy.com/gh/seapagan/fastapi-template/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_coverage)\n[![Code Quality](https://app.codacy.com/project/badge/Grade/82085ec100b64e73bea63b5942371e94)](https://app.codacy.com/gh/seapagan/fastapi-template/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![pages-build-deployment](https://github.com/seapagan/fastapi-template/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/seapagan/fastapi-template/actions/workflows/pages/pages-build-deployment)\n\nThis is a template Repository for starting a new\n[FastAPI](https://fastapi.tiangolo.com/) project with Authentication and Users,\nwith Authorization already baked-in.\n\n\u003c!-- Full documentation is now availiable on it's own page [here][doc]. Please visit\nthis for full usage information, how-to's and more. --\u003e\n\nDocumentation for this project is now availiable on it's own page at\n[https://api-template.seapagan.net][doc]. This is a work in progress, and when\nfinished will include full usage information and how-to's.\n\n- [Important note on Versioning](#important-note-on-versioning)\n- [Changes from version 0.4.x](#changes-from-version-04x)\n- [Functionality](#functionality)\n- [Installation](#installation)\n- [Docker](#docker)\n  - [Develop on containers](#develop-on-containers)\n  - [Migrations on containers](#migrations-on-containers)\n  - [Testing on containers](#testing-on-containers)\n- [Planned Functionality and Known Bugs](#planned-functionality-and-known-bugs)\n- [Testing](#testing)\n- [Code Quality](#code-quality)\n- [Who is Using this Template?](#who-is-using-this-template)\n- [Contributing](#contributing)\n- [GitHub Discussions](#github-discussions)\n\n## Important note on Versioning\n\nThis template versioning has been refactored to start from **Version 0.4.0**.\n\nThe original template was written for my own use and probably promoted to V1.0.0\nbefore it should have been, and there have been many updates and fixes since\nthen.\n\nI will keep the old releases available for those who wish to use them (for a\nshort time). It's better to do this now before more users need to update their\nprojects to future versions.\n\nAll releases from now on will also contain a Git patch to upgrade from the\nprevious version. This will be in the form of a `.patch` file which can be\napplied to their project using the `git apply` command. This will be documented\nin the release notes.\n\n## Changes from version 0.4.x\n\nStarting from version 0.5.0, the template has been refactored to use SQLAlchemy\n2.0 ORM instead of `encode/databases` for database access. This allows for a\nmore flexible and powerful Asynchronous database access but does need a bit of\nrefactoring for any existing projects. See the [documentation][breaking] for\nmore information. I will also be adding a migration guide for those who wish to\nupgrade their existing projects (time permitting).\n\nIf you prefer to continue using the 0.4.x branch, you can find it\n[here][legacy-branch].\n\nTo use this branch you will need to clone the repository and checkout the\n`0.4.2` branch.\n\n```console\ngit clone -b 0.4.2 https://github.com/seapagan/fastapi-template.git\n```\n\nBe aware that this branch will not be maintained and will not receive any\nupdates or bug fixes.\n\n## Functionality\n\nThis template is a ready-to-use boilerplate for a FastAPI project. It has the\nfollowing advantages to starting your own from scratch :\n\n- Baked-in User database and management. Routes are provided to\n  add/edit/delete/search or ban (and unban) Users.\n- Postgresql Integration, using SQLAlchemy ORM, no need for raw SQL queries\n  (unless you want to!). All database usage is Asynchronous. [Alembic][alembic]\n  is used to control database migrations.\n- Register and Login routes provided, both of which return a JWT token to be\n  used in all future requests. JWT Token expires 120 minutes after issue.\n- JWT-based security as a Bearer Token to control access to all your routes.\n- `API Keys` are fully implemented and can be used by registered users instead\n  of the JTW. These will **not expire** at present though adding expiry is a\n  future plan. API keys are passed using the `X-API-Key` header.\n- A `Refresh Token` with 30 day expiry is sent at time of register or login\n  (never again). This will enable easy re-authentication when the JWT expires\n  without needing to send username or password again, and should be done\n  automatically by the Front-End.\n- A clean layout to help structure your project.\n- An optional **Admin site** to manage users and API keys. This uses the\n  `sqladmin` package to give you an easy way to manage your database.\n- Uses the python logger for info/warning/error logging - tying transparently in\n  to the `uvicorn` logger.\n- **A command-line admin tool**. This allows to configure the project metadata\n  very easily, add users (and make admin), and run a development server. This\n  can easily be modified to add your own functionality (for example bulk add\n  data) since it is based on the excellent [Typer][typer] library.\n- Easily batch-add random test users to the database for testing/development\n  purposes using the CLI or seed the database with pre-set users from a CSV\n  file.\n- Database and Secrets are automatically read from Environment variables or a\n  `.env` file if that is provided. The CLI can generate and set the JTW Secret\n  and Admin pages encryption keys.\n- User email is validated for correct format on creation (however no checks are\n  performed to ensure the email or domain actually exists).\n- Control permitted CORS Origin through Environment variables.\n- Manager class set up to send emails to users, and by default an email is sent\n  when new users register. The content is set by a template (currently a basic\n  placeholder). This email has a link for the user to confirm their email\n  address - until this is done, the user cannot user the API.\n- Docker and Compose file set up to develop and test this API using Docker\n\n**This template is still in very active development and probably not yet ready\nfor full production use. However, I am currently using it to develop my own\nprojects, which include some production API's without issues. I will update the\ntemplate as I find bugs or add new features. I will also be adding more\ndocumentation as I go. For the moment, if you wish to use it without getting\ninvolved in dev, I'd recommend checking out the latest actual\n[Release][latest-release].**\n\nHowever, the `main` branch should be pretty stable as all development is done on\nthe `develop` branch and merged into `main` when ready.\n\nThe template **Requires Python 3.9.0** or higher. I actually develop under\nPython 3.13.x where x is the latest patch version available at the time, and\nmigrating to the next patch version as soon as it is released. CI tests are run\nautomatically on the latest patch levels of Python 3.9 to 3.13.\n\nThis template is free to use but I would request some accreditation. If you do\nuse it in one of your applications, or even some of the unique code from the\ntemplate, or you learn something from it, please put a small note in your readme\nor blog post/whatever stating that you used this Template or code therein, with\na link back to this repository. Thank You 😊\n\nFor those who let me know they are using this Template, I'll add links back to\nyour project in this documentation.\n\nIf this template saves you time/effort/money, or you just wish to show your\nappreciation for my work, why not [Sponsor my Work][sponsor] or [Buy me a\nCoffee!][coffee] 😃\n\n## Installation\n\nClick the 'Use this template' button at the top of the Repository on GitHub.\nThis will create a new repository in your personal GitHub account (Not a Fork)\nwhich you can then Clone and start working on.\n\nIt is assumed that you have at least some knowledge of [FastAPI][fastapi] to use\nthis template, there are very good [Basic][tut-basic] and\n[Advanced][tut-advanced] User Guides on the FastAPI website .\n\nVisit the [Installation Instructions][install] for more detailed installation\nnotes, including how to handle the coverage uploader.\n\n## Docker\n\nNote that when run from docker, the API is exposed on port `8001` instead of\n`8000`.\n\nAlso, unlike before version 0.5.1, it is no longer required to change the\n`DB_ADDRESS` environment variable when running on docker, this is taken care of\nautomatically.\n\n### Develop on containers\n\n\u003e :warning: For local use rename `.env.example` to `.env`.\n\nIt is possible to develop directly on Docker containers :\n\n**Using `docker compose up` (recommended):**\n\n```console\ndocker compose up\n```\n\nTo run and rebuild image (dependency updates):\n\n```console\ndocker compose up --build\n```\n\nTo remove all containers:\n\n```console\ndocker compose down\n```\n\n**Using `docker compose run`:**\n\nFirst run migrations:\n\n```console\ndocker compose run --rm api alembic upgrade head\n```\n\nRun containers:\n\n```console\ndocker compose run --rm --service-ports api uvicorn --host 0.0.0.0 main:app --reload\n```\n\nTo rebuild image (dependency updates):\n\n```console\ndocker compose build\n```\n\n### Migrations on containers\n\nRunning migrations on Docker container is also possible:\n\n```console\ndocker compose run --rm api alembic upgrade head\n```\n\n### Testing on containers\n\nRunning tests on Docker container is also possible:\n\n```console\ndocker compose run --rm api pytest\n```\n\n## Planned Functionality and Known Bugs\n\nSee the [TODO.md](TODO.md) file for plans and known issues.\n\n## Testing\n\nThis project has a test suite for Integration and Unit tests. We use\n[pytest][pytest] for this.\n\nCurrently you need a Postgresql database running for this to work, however\nSQLite support is planned to be re-added. You can easily set up a Postgresql\ndatabase using Docker.\n\nBefore running the tests, you need to create a dedicated test database, in is\nassumed that the server, username and password are the same as for the main\ndatabase.\n\nEdit the setting in `.env` to point to the test database:\n\n```ini\n# Database name to use for testing. This must already exist.\nTEST_DB_NAME=api-template-test\n```\n\nYou can then migrate this empty database by running:\n\n```console\n$ api-admin test setup\nMigrating the test database ... Done!\n```\n\nTests can then be run from the checked out code with:\n\n```console\n$ pytest\n```\n\nIt is possible to run either the Unit or Integration tests separately using\n`pytest -m unit` or `pytest -m integration`\n\nFull tests will be run automatically by **GitHub Actions** on every new commit\npushed up to the remote repository. Code Coverage is also checked and noted\nafter each test suite is run.\n\n## Code Quality\n\n`To be written`\n\n## Who is Using this Template?\n\nMeh, at the moment probably no-one except me 😆. If you do use this in one of\nyour own projects, drop me a message and I'll add your profile and project links\nhere 😃.\n\n## Contributing\n\nSee [Contributing][contrib] for details on how to contribute to this project.\n\n## GitHub Discussions\n\nI have enabled [Discussions][discussions] on this repository, so if you have any\nquestions, suggestions or just want to chat about this template, please feel\nfree to start a discussion.\n\n[doc]: https://api-template.seapagan.net\n[contrib]: https://api-template.seapagan.net/contributing/\n[breaking]: https://api-template.seapagan.net/important/\n[install]: https://api-template.seapagan.net/usage/installation/\n[latest-release]: https://github.com/seapagan/fastapi-template/releases/latest\n[discussions]: https://github.com/seapagan/fastapi-template/discussions\n[legacy-branch]: https://github.com/seapagan/fastapi-template/tree/0.4.2\n[sponsor]: https://github.com/sponsors/seapagan\n[coffee]: https://www.buymeacoffee.com/seapagan\n[alembic]: https://github.com/sqlalchemy/alembic\n[typer]: https://typer.tiangolo.com/\n[fastapi]: https://fastapi.tiangolo.com/\n[pytest]: https://docs.pytest.org\n[tut-basic]: https://fastapi.tiangolo.com/tutorial/\n[tut-advanced]: https://fastapi.tiangolo.com/advanced/\n","funding_links":["https://github.com/sponsors/seapagan","https://ko-fi.com/grantramsay","https://buymeacoffee.com/seapagan","https://www.buymeacoffee.com/seapagan"],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseapagan%2Ffastapi-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseapagan%2Ffastapi-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseapagan%2Ffastapi-template/lists"}