https://github.com/remarkablemark/python-microservice-template
🐍 Python microservice template
https://github.com/remarkablemark/python-microservice-template
api fastapi microservice python python3 template uvicorn
Last synced: 3 months ago
JSON representation
🐍 Python microservice template
- Host: GitHub
- URL: https://github.com/remarkablemark/python-microservice-template
- Owner: remarkablemark
- License: mit
- Created: 2026-02-10T02:31:44.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-04-03T02:08:55.000Z (3 months ago)
- Last Synced: 2026-04-03T11:46:03.491Z (3 months ago)
- Topics: api, fastapi, microservice, python, python3, template, uvicorn
- Language: Python
- Homepage:
- Size: 1.88 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
Awesome Lists containing this project
README
# python-microservice-template
[](https://codecov.io/gh/remarkablemark/python-microservice-template)
[](https://github.com/remarkablemark/python-microservice-template/actions/workflows/test.yml)
[](https://github.com/remarkablemark/python-microservice-template/actions/workflows/lint.yml)
🐍 Python microservice template built with:
- [FastAPI](https://fastapi.tiangolo.com/)
- [Uvicorn](https://uvicorn.dev/)
- [SQLAlchemy](https://www.sqlalchemy.org/)
- [Alembic](https://alembic.sqlalchemy.org/)
- [OpenTelemetry](https://opentelemetry.io/)
## Prerequisites
[uv](https://docs.astral.sh/uv/#installation):
```sh
brew install uv
```
## Install
Clone the repository:
```sh
git clone https://github.com/remarkablemark/python-microservice-template.git
cd python-microservice-template
```
Install the dependencies:
```sh
uv sync
```
## Authentication
The microservice supports optional bearer token authentication.
### Environment Variables
Copy the example environment file:
```sh
cp .env.example .env
```
Edit `.env` and set your bearer tokens:
```sh
# 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:
```sh
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:
```sh
cp .env.example .env
```
Edit `.env` and set your database URL:
```sh
# 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:
```sh
uv run alembic revision --autogenerate -m "description"
```
Apply migrations:
```sh
uv run alembic upgrade head
```
Rollback migration:
```sh
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:
```sh
uv run uvicorn app.main:app --reload
```
### `uv run fastapi run`
Runs the app in production mode.
Alternatively, run with uvicorn directly:
```sh
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](https://github.com/remarkablemark/python-microservice-template/blob/master/LICENSE)