Bootstrap python service

This is an example implementation of a python application applying concepts from Clean Architecture and SOLID principles.

• The repository classes are isolated behind interfaces, enforcing the Interface Segregation principle and the Inversion of Control design pattern
• The application frameworks are decoupled from the domain logic
• The storage layer is decoupled from the domain logic

This template provides out of the box some commonly used functionalities:

• API Documentation using FastAPI
• Async tasks execution using Dramatiq
• Repository pattern for databases using SQLAlchemy and SQLAlchemy bind manager
• Database migrations using Alembic (configured supporting both sync and async SQLAlchemy engines)
• Authentication and Identity Provider using ORY Zero Trust architecture
• Example CI/CD deployment pipeline for GitLab (The focus for this repository is still GitHub but, in case you want to use GitLab 🤷)
• [TODO] Producer and consumer to emit and consume events using CloudEvents format on Confluent Kafka

Documentation

The detailed documentation is available:

• Online on GitHub pages
• Offline by running make docs after installing dependencies with make dev-dependencies

How to use

Create your GitHub repository using this template (The big green Use this template button). Optionally tweak name and authors in the pyproject.toml file, however the metadata are not used when building the application, nor are referenced anywhere in the code.

Before running any commands, install uv:

• On Mac (using brew): brew install uv

Using Docker:

• make containers: Build containers
• docker compose run --rm dev make migrate: Run database migrations
• docker compose up dev: Run HTTP application with hot reload
• docker compose up dramatiq-worker: Run the dramatiq worker
• docker compose run --rm test: Run test suite

Locally:

• make migrate: Run database migrations
• make install-dependencies: Install requirements
• make dev-dependencies: Install dev requirements
• make update-dependencies: Updates requirements
• make migrate: Run database migrations
• make dev: Run HTTP application with hot reload
• make test: Run test suite

Other commands for development

• make check: Run tests, code style and lint checks
• make fix: Run tests, code style and lint checks with automatic fixes (where possible)

Multistage dockerfile configuration

Python docker image tend to become large after installing the application requirements (the slim base is ~150 MB uncompressed), therefore it's important to spend efforts to minimise the image size, even if it produces a slightly more complex multistage Dockerfile.

The following setup makes sure the production image will keep to a minimal size ("only" 360MB):

• 150MB base image
• 210MB python installed dependencies

Using the following pipeline the "test" image is instead ~850MB, more than 400MB that would end up as a cost in traffic on each image pull.