django-helsinki-health-endpoints

Reusable Django app providing unified /healthz and /readiness endpoints for City of Helsinki projects.

Features

• /healthz — Kubernetes liveness probe (always returns HTTP 200)
• /readiness — Kubernetes readiness probe with:
  • Application version (read from pyproject.toml)
  • Database connectivity check
  • Sentry release tag

Installation

pip install django-helsinki-health-endpoints

Configuration

1. Add to INSTALLED_APPS

INSTALLED_APPS = [
    # ...
    "helsinki_health_endpoints",
]

2. Include URL patterns

from django.urls import include, path

urlpatterns = [
    path("", include("helsinki_health_endpoints.urls")),
    # ...
]

This registers healthz and readiness endpoints at the root. You can mount them under a prefix if needed:

urlpatterns = [
    path("__", include("helsinki_health_endpoints.urls")),  # => /__healthz, /__readiness
]

You can also register the endpoints individually instead of using include:

from helsinki_health_endpoints.views import healthz, readiness

urlpatterns = [
    path("healthz", healthz),
    path("readiness", readiness),
]

3. Settings

helsinki_health_endpoints reads the following keys from django.conf.settings:

BASE_DIR is typically already defined in your project's settings.py:

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

To expose your Sentry release in the /readiness response, add:

import os

SENTRY_RELEASE = os.environ.get("SENTRY_RELEASE", "")

System checks

helsinki_health_endpoints registers Django system checks that run automatically on startup (or via manage.py check).

Response examples

GET /healthz

HTTP 200

GET /readiness

{
  "status": "ok",
  "version": "1.2.3",
  "release": "theapp@1.2.3",
  "database": "ok"
}

If the database check fails:

HTTP 503

{
  "status": "error",
  "version": "1.2.3",
  "release": "theapp@1.2.3",
  "database": "error"
}

Development

This project uses Hatch for development, testing, and building.

Install Hatch

pip install hatch

Set up the development environment

Hatch manages virtual environments automatically. To create and enter a shell in the default environment:

hatch shell

To install pre-commit hooks (required before committing):

hatch run lint

This will install pre-commit and run all hooks. Alternatively:

pre-commit install

Running tests

Run the full test matrix (all Python × Django version combinations defined in pyproject.toml):

hatch test -a

Run tests for a specific Python version only:

hatch test -i py=3.12

Run tests for a specific Python + Django combination:

hatch test -i py=3.12 -i django=5.2

Pass arguments through to pytest (e.g. run a single test file):

hatch test -- tests/test_views.py -v

The test matrix

The matrix defined in pyproject.toml is:

Each combination gets its own isolated venv (created automatically by hatch on first run, stored in hatch's environment cache).

Manual testing

The repository includes a manage.py pre-configured with the test settings (SQLite in-memory database). You can run it from within the default Hatch environment:

hatch run python manage.py runserver

Or enter the environment shell first and run it directly:

hatch shell
python manage.py runserver

Then hit the endpoints:

curl http://localhost:8000/healthz
curl http://localhost:8000/readiness

Linting

# Run all pre-commit hooks against all files
hatch run lint

# Or run pre-commit directly (after installing hooks)
pre-commit run --all-files

# Run only ruff lint (with autofix)
pre-commit run ruff-check --all-files

# Run only ruff formatter
pre-commit run ruff-format --all-files

License

This project is licensed under the MIT License — see the LICENSE file for details.