diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f7aa9b2..2b48fb4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -61,9 +61,10 @@ jobs: run: | python -m pip install --upgrade pip pip install -r requirements-dev.txt + pip install pytest-cov - name: Run pytest - run: pytest -v --tb=short + run: pytest -v --tb=short --cov=app --cov-report=xml --cov-report=html --cov-report=term-missing typecheck: name: Type check (mypy) @@ -86,7 +87,7 @@ jobs: pip install -r requirements-dev.txt - name: Run mypy - run: mypy app tests || true # non-blocking until types are fully clean + run: mypy app tests security: name: Security scan (pip-audit) diff --git a/README.md b/README.md index f2534a0..55b9358 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230?style=flat-square)](https://docs.astral.sh/ruff/) [![GitHub release](https://img.shields.io/github/v/release/mohit-tanwar-dev/python-backend?style=flat-square)](https://github.com/mohit-tanwar-dev/python-backend/releases) +[![Code Coverage](https://img.shields.io/badge/coverage-XX%25-red?style=flat-square)](./htmlcov/index.html) + FastAPI scaffold with health endpoint, structured logging, env-driven config, pytest suite, ruff/mypy, and GitHub Actions CI. ## Stack @@ -49,6 +51,27 @@ python-backend/ └── SECURITY.md ``` +## Development Workflow + +For local development, it's recommended to use a virtual environment. The project uses `ruff` for linting and formatting, and `mypy` for type checking. `pre-commit` hooks are configured to ensure code quality before commits. + +### Local Setup + +```bash +# Install pre-commit hooks +pre-commit install +``` + +### Running Linters and Type Checks + +```bash +ruff check . +ruff format --check . +mypy app tests +``` + +These checks are also run in the CI pipeline. + ## Quick start ```bash @@ -75,6 +98,26 @@ docker build -t python-backend:latest . docker run --rm -p 8000:8000 --env-file .env python-backend:latest ``` +## Production Deployment + +For production deployments, it is recommended to use a production-ready ASGI server like Gunicorn with Uvicorn workers. Below are examples for running the application in a production environment. + +### Gunicorn with Uvicorn Workers + +```bash +gunicorn -w 4 -k uvicorn.workers.UvicornWorker app.main:app --bind 0.0.0.0:8000 +``` + +This command starts Gunicorn with 4 Uvicorn worker processes, binding to all network interfaces on port 8000. + +### Health Check Path + +The application provides a health check endpoint at `/health` (or `/api/v1/health` for the versioned API) that can be used by load balancers or container orchestration systems to verify the application's status. + +## Logging Configuration + +The application uses structured logging, configured via `app/core/logging.py`. The log level can be controlled using the `APP_LOG_LEVEL` environment variable (e.g., `INFO`, `DEBUG`, `WARNING`, `ERROR`). Logs are typically output to `stdout` and `stderr`, making them suitable for containerized environments and centralized logging solutions. + ## Configuration Settings loaded from environment variables or `.env`. All have defaults. @@ -103,6 +146,10 @@ CI runs all of the above on Python 3.11 and 3.12. See [CONTRIBUTING.md](CONTRIBUTING.md). Fork, branch from `main`, open a PR. +## Release Process + +Releases are managed via GitHub releases. A new release can be cut by creating a new tag (e.g., `v1.0.0`). The CI/CD pipeline is configured to automatically build and publish artifacts upon a new tag. Changelog conventions are maintained in `CHANGELOG.md`. + ## Changelog See [CHANGELOG.md](CHANGELOG.md). diff --git a/pytest.ini b/pytest.ini index bcbff56..14be0e7 100644 --- a/pytest.ini +++ b/pytest.ini @@ -5,3 +5,6 @@ python_classes = Test* python_functions = test_* asyncio_mode = auto addopts = -v --tb=short --strict-markers + +[pytest-cov] +addopts = --cov=app --cov-report=xml --cov-report=html --cov-report=term-missing