A backend project template with FastAPI, PostgreSQL with asynchronous SQLAlchemy 2.0, Alembic for asynchronous database migration, and Docker.
GPL-3.0 License
This is a template repository aimed to kick-start your project with a setup from a real-world application! This template utilizes the following tech stack:
When the Docker
is started, these are the URL addresses:
http://localhost:8001/docs
http//localhost:8081
The backend API without Docker
can be found in http://localhost:8000/docs
.
Well, the easy answer is Asynchronousity and Speed!
The above-listed technologies are just the main ones. There are other technologies utilized in this project template to ensure that your application is robust and provides the best possible development environment for your team! These technologies are:
Pyenv
to manage the virtual environment for our packages.import
for clarity. Also for Python.My choice for a project development workflow is usually the Trunk-Based Development because of the straightforward approach in the collaboration workflow, hence the name trunk
for the main branch repository instead of master
or main
.
For the backend application:
backend/pyproject.toml
.backend/src/config/settings/base.py
.backend/src/config/events.py
.Account
object table model in backend/src/models/db/account.py
.Account
object schema model in backend/src/models/schemas/account.py
.backend/src/repository/database.py
.backend/src/repository/table.py
backend/src/repository/database.py
.backend/src/repository/events.py
.Account
object in backend/src/repository/crud/account.py
.backend/src/repository/base.py
.backend/src/repository/migration/**
.backend/alembic.ini
.backend/src/api/**
.Account
signup and signin in backend/src/api/routes/authentication.py
.Account
get all, get 1, update, and delete in backend/src/api/routes/account.py
.backend/src/api/endpoints
.backend/src/securities/**
.backend/src/utilities/**
.backend/src/main.py
.For testing, I have prepared the following simple code to kick-start your test-driven development:
backend/tests/conftest.py
.tests/unit_tests/test_src.py
.For the DevOps:
build
job to test the compilation of the source code for the backend application in .github/workflows/ci-backend.yaml
.code-style
with black, isort, flake8, and mypy in .github/workflows/ci-backend.yaml
.PyTest
and an automated test reporting with Codecov
in in .github/workflows/ci-backend.yaml
..github/CODEOWNERS
(Please change the username to your own).YAML
file for an automated semantic commit message in .github/workflows/ci-backend.yaml
.Codecov
in codecov.yaml
YAML
file in .pre-commit-config.YAML
.For containerization:
Docker
configuration that utilizes the latest Python image in backend/Dockerfile
.backend/entrypoint.sh
.Postgres
image for our database server, Adminer
for our database editor, and backend_app
for our backend application's container in docker-compose.yaml
.For the team development environment:
Black
, Isort
, and MyPy
to ensure the conventional commit message before pushing an updated code into the remote repository in .pre-commit-config.YAML
..env.example
. You need to copy these variables and set the values respectively to your need and save them in a new .env
in the root directory.This backend application is setup with Docker
. Nevertheless, you can see the full local setup without Docker
in backend/README.md.
Before setting up the backend app, please create a new directory called coverage
for the testing report purpose:
cd backend && mkdir coverage
Backend app setup:
# Creating VENV
pyenv virtualenv 3.11.0 any_venv_name
pyenv local any_venv_name
# Install dependencies
pip3 install -r requirements.txt
# Test run your backend server
uvicorn src.main:backend_app --reload
Testing with PyTest
:
Make sure that you are in the backend/
directory.
# For testing without Docker
pytest
# For testing within Docker
docker exec backend_app pytest
Pre-Commit
setup:
# Make sure you are in the ROOT project directory
pre-commit install
pre-commit autoupdate
Backend app credentials setup:
If you are not used to VIM or Linux CLI, then ignore the echo
command and do it manually. All the secret variables for this template are located in .env.example
.
If you want to have another name for the secret variables, don't forget to change them also in:
backend/src/config/base.py
docker-compose.yaml
# Make sure you are in the ROOT project directory
touch .env
echo "SECRET_VARIABLE=SECRET_VARIABLE_VALUE" >> .env
CODEOWNERS
setup:
Go to .github/
and open CODEOWNERS
file. This file is to assign the code to a specific team member so you can distribute the weights of the project clearly.
Docker setup:
# Make sure you are in the ROOT project directory
chmod +x backend/entrypoint.sh
docker-compose build
docker-compose up
# Every time you write a new code, update your container with:
docker-compose up -d --build
(IMPORTANT) Database setup:
# (Docker) Generate revision for the database auto-migrations
docker exec backend_app alembic revision --autogenerate -m "YOUR MIGRATION TITLE"
docker exec backend_app alembic upgrade head # to register the database classes
# (Local) Generate revision for the database auto-migrations
alembic revision --autogenerate -m "YOUR MIGRATION TITLE"
alembic upgrade head # to register the database classes
Go to https://about.codecov.io/, and sign up with your github to get the CODECOV_TOKEN
Go to your GitHub and register all the secret variables (look in .env.example) in your repository (settings
$\rightarrow$ (scroll down a bit) Secrets
$\rightarrow$ Actions
$\rightarrow$ New repository secret
)
IMPORTANT: Without the secrets registered in Codecov and GitHub, your CI
will fail and life will be horrible ๐คฎ๐คฌ
IMPORTANT: Remember to always run the container update every once in a while. Without the arguments -d --build
, your Docker
dashboard will be full of junk containers!
.github/
โโโ workflows/
โโโ ci-backend.yaml # A CI file for the backend app that consists of `build`, `code-style`, and `test`
โโโ CODEOWNERS # A configuration file to distribute code responsibility
โโโ semantic.yaml # A configuration file for ensuring an automated semantic commit message
backend/
โโโ coverage/
โโโ src/
โโโ api/
โโโ dependencies/ # Dependency injections
โโโ session.py
โโโrepository.py
โโโ routes/ # Endpoints
โโโ account.py # Account routes
โโโ authentication.py # Signup and Signin routes
โโโ endpoints.py # Endpoint registration
โโโ config/
โโโ settings/
โโโ base.py # Base settings / settings parent class
โโโ development.py # Development settings
โโโ environments.py # Enum with PROD, DEV, STAGE environment
โโโ production.py # Production settings
โโโ staging.py # Test settings
โโโ events.py # Registration of global events
โโโ manager.py # Manage get settings
โโโ models/
โโโ db/
โโโ account.py # Account class for database entity
โโโ schemas/
โโโ account.py # Account classes for data validation objects
โโโ base.py # Base class for data validation objects
โโโ repository/
โโโ crud/
โโโ account.py # C. R. U. D. operations for Account entity
โโโ base.py # Base class for C. R. U. D. operations
โโโ migrations/
โโโ versions/
โโโ env.py # Generated via alembic for automigration
โโโ script.py.mako # Generated via alembic
โโโ base.py # Entry point for alembic automigration
โโโ database.py # Database class with engine and session
โโโ events.py # Registration of database events
โโโ table.py # Custom SQLAlchemy Base class
โโโ security/
โโโ hashing/
โโโ hash.py # Hash functions with passlib
โโโ password.py # Password generator with hash functions
โโโ authorizations/
โโโ jwt.py # Generate JWT tokens with python-jose
โโโ verifications/
โโโ credentials.py # Check for attributes' availability
โโโ utilities/
โโโ exceptions/
โโโ http/
โโโ http_exc_400.py # Custom 400 error handling functions
โโโ http_exc_401.py # Custom 401 error handling functions
โโโ http_exc_403.py # Custom 403 error handling functions
โโโ http_exc_404.py # Custom 404 error handling functions
โโโ database.py # Custom `Exception` class
โโโ password.py # Custom `Exception` class
โโโ formatters/
โโโ datetime_formatter.py # Reformat datetime into the ISO form
โโโ field_formatter.py # Reformat snake_case to camelCase
โโโ messages/
โโโ http/
โโโ http_exc_details.py # Custom message for HTTP exceptions
โโโ main.py # Our main backend server app
โโโ tests/
โโโ end_to_end_tests/ # End-to-end tests
โโโ integration_tests/ # Integration tests
โโโ security_tests/ # Security-related tests
โโโ unit_tests/ # Unit tests
โโโ test_src.py # Testing the src directory's version
โโโ conftest.py # The fixture codes and other base test codes
โโโ Dockerfile # Docker configuration file for backend application
โโโ README.md # Documentation for backend app
โโโ entrypoint.sh # A script to restart backend app container if postgres is not started
โโโ alembic.ini # Automatic database migration configuration
โโโ pyproject.toml # Linter and test main configuration file
โโโ requirements.txt # Packages installed for backend app
.dockerignore # A file that list files to be excluded in Docker container
.gitignore # A file that list files to be excluded in GitHub repository
.pre-commit-config.yaml # A file with Python linter hooks to ensure conventional commit when committing
LICENSE.md # A license to use this template repository (delete this file after using this repository)
README.md # The main documentation file for this template repository
codecov.yaml # The configuration file for automated testing CI with codecov.io
docker-compose.yaml # The main configuration file for setting up a multi-container Docker
You can delete these 3 files (or change its content based on your need):
LICENSE.md
README.md
backend/README.md
Enjoy your development and may your technology be forever useful to everyone ๐๐๐งฌ