python-microservice-template

🐍 Python microservice template built with:

• FastAPI
• Uvicorn
• SQLAlchemy
• Alembic
• OpenTelemetry

Prerequisites

uv:

brew install uv

Install

Clone the repository:

git clone https://github.com/remarkablemark/python-microservice-template.git
cd python-microservice-template

Install the dependencies:

uv sync

Authentication

The microservice supports optional bearer token authentication.

Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env and set your bearer tokens:

# Single token
API_KEYS=your-secret-key-here

# Multiple tokens (comma-separated)
API_KEYS=key-1,key-2,key-3

Protected Endpoints

Protected endpoints require an Authorization header with a bearer token:

curl -H "Authorization: Bearer your-secret-key-here" \
  http://127.0.0.1:8000/protected/

When authentication is enabled, the /protected endpoints will be available at:

• GET /protected/ - Basic protected endpoint
• GET /protected/data - Protected endpoint with data

Database

The microservice supports optional database integration using SQLModel and Alembic.

Environment Variables

Copy the example environment file and configure your database:

cp .env.example .env

Edit .env and set your database URL:

# For SQLite (Development)
DATABASE_URL=sqlite:///./app.db

# For PostgreSQL (Production)
# DATABASE_URL=postgresql://user:password@localhost:5432/dbname

Migrations

Create a new migration after modifying models:

uv run alembic revision --autogenerate -m "description"

Apply migrations:

uv run alembic upgrade head

Rollback migration:

uv run alembic downgrade -1

Available Scripts

In the project directory, you can run:

uv run pre-commit install

Installs the pre-commit script.

uv run fastapi dev

Runs the app in development mode:

• Server: http://127.0.0.1:8000
• Documentation: http://127.0.0.1:8000/docs
• OpenAPI: http://127.0.0.1:8000/openapi.json

The server will reload if you make edits.

Alternatively, run with uvicorn directly:

uv run uvicorn app.main:app --reload

uv run fastapi run

Runs the app in production mode.

Alternatively, run with uvicorn directly:

uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

uv run ruff format

Formats the code (replaces Black).

uv run ruff check

Lints the code and checks import sorting (replaces isort).

uv run ruff check --fix

Auto-fixes linting issues and sorts imports.

uv run coverage run -m pytest && uv run coverage report

Runs tests with coverage reporting (fails if coverage is below 100%).

uv run alembic revision --autogenerate -m "message"

Creates a new database migration.

uv run alembic upgrade head

Applies all pending database migrations.

License

MIT