django-deploy-probes 0.2.1

Deployment probe endpoints for Django applications.

django-deploy-probes

Production-ready HTTP deployment probe endpoints for Django applications.

Use django-deploy-probes for CI/CD deployment validation, Docker health checks, Kubernetes probes, blue-green deployments, and rollback checks.

Documentation

• Documentation site
• Basic setup
• Endpoint reference
• Security options
• Docker integration
• Docker Compose integration
• Kubernetes probes
• GitHub Actions deployment validation

Install

pip install django-deploy-probes

Optional extras:

pip install "django-deploy-probes[redis]"
pip install "django-deploy-probes[celery]"
pip install "django-deploy-probes[openapi]"
pip install "django-deploy-probes[all]"

Quick Start

INSTALLED_APPS = [
    "django_deploy_probes",
]

from django.urls import include, path

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

Verify:

curl -f http://localhost:8000/healthz
curl -f http://localhost:8000/readyz
curl -f http://localhost:8000/version

Custom check messages are hidden by default. If you enable EXPOSE_CHECK_MESSAGES=True, do not include secrets or sensitive values in those messages.

Security checks use REMOTE_ADDR by default. If probes are accessed through a trusted reverse proxy, configure TRUSTED_PROXY_NETWORKS and CLIENT_IP_HEADER to resolve the original client IP safely.

Storage checks use Django storage aliases, so the same probe can validate local filesystems, S3-compatible backends, and any custom storage backend wired through STORAGES.

Common settings

DEPLOY_PROBES = {
    "SERVICE_NAME": "my-django-app",
    "ENVIRONMENT": "prod",
    "VERSION": "1.2.0",
    "READY_CHECKS": ["database", "redis", "celery", "storage"],
    "STARTUP_CHECKS": ["migrations"],
    "READY_CUSTOM_CHECKS": [],
    "STARTUP_CUSTOM_CHECKS": [],
    "DATABASES": ["default"],
    "STORAGE": {
        "default": {
            "CHECK": "exists",
            "PATH": "probes/ready.txt",
        },
        "s3_media": {
            "CHECK": "write",
            "PREFIX": "deploy-probes",
        },
    },
    "REDIS": {
        "default": {
            "LOCATION": "redis://localhost:6379/0",
            "TIMEOUT": 1.0,
        },
    },
    "CELERY": {
        "BROKER": True,
        "WORKERS": False,
        "RESULT_BACKEND": False,
        "TIMEOUT": 1.0,
    },
    "DETAIL_LEVEL": "none",
    "INCLUDE_CHECK_DURATIONS": False,
    "REQUIRE_READY_CHECKS": False,
    "REQUIRE_STARTUP_CHECKS": False,
    "EXPOSE_CHECK_MESSAGES": False,
    "INTERNAL_IP_ONLY": False,
    "INTERNAL_IP_NETWORKS": [
        "127.0.0.1/32",
        "::1/128",
        "10.0.0.0/8",
        "172.16.0.0/12",
        "192.168.0.0/16",
    ],
    "TRUSTED_PROXY_NETWORKS": [],
    "CLIENT_IP_HEADER": None,
}

STORAGE supports two practical modes:

• CHECK="exists": verify that a known probe object exists.
• CHECK="write": create and delete a temporary object to verify write access.

For S3, exists is safer when you already manage a sentinel object like probes/ready.txt. Use write when you want to validate bucket write/delete permissions during readiness checks.

Development

uv sync --dev
uv run pytest -q
uv run mkdocs build --strict

Publishing is handled by .github/workflows/publish.yml when a GitHub release is published. Documentation is deployed to GitHub Pages from main by .github/workflows/docs.yml.