django-hq

A developer console for Django projects: which commit is live, when its image was built, when the container came up, what is pending, and how full the disk is.

It answers the question you have at the worst possible moment — what is actually running right now? — and it answers it without a CDN, without a build step and without an external service, because those are the first things to be unavailable when you need to ask.

pip install django-hq

# settings.py
INSTALLED_APPS = [
    ...
    "django.contrib.humanize",   # required: relative timestamps
    "hq",
]

HQ = {
    "SITE_NAME": "Widget",
    "STATUS": {"REPO_URL": "https://github.com/acme/widget"},
}

# urls.py
path("hq/", include("hq.urls")),

That is the whole install. /hq/ is the console, /hq/status/ the status page, and /hq/status/json/ the same facts for anything that reads rather than looks. Everything is superuser-only by default.

Most of the page works immediately. The build facts — commit, version, build number, image timestamp — need the container to have been told them, which is what the /build contract is for.

What it reports

Settings

All optional. HQ is one dict; module settings nest under the module's name.

Console

HQ["STATUS"]

Secrets in those two dumps are never shown. They are reduced to eight hex characters of an HMAC keyed off SECRET_KEY — enough to answer did the container pick up the key I rotated by comparison, and nothing more.

Adding a module

The console is an umbrella; the status page is the first module in it.

from hq.registry import HQModule

class CronModule(HQModule):
    slug = "cron"
    label = "Scheduled jobs"
    icon = "timer"

    def get_urls(self):
        from myapp import urls
        return urls.urlpatterns

    def get_tiles(self, request):
        return [{"label": "Next run", "value": "in 12 min", "modifier": "accent"}]

Then list it: HQ = {"MODULES": ["hq.modules.status.module.StatusModule", "myapp.CronModule"]}. Its views inherit hq.views.HQView to get the console chrome, access gate and never-cache headers. Navigation appears automatically once there is more than one module.

Design notes

• Nothing is fetched from a network. The fifteen interface icons (lucide, ISC) and five brand marks (Simple Icons, CC0) are vendored as inline SVG. The only optional external request is the webfont stylesheet, and FONTS_URL = None removes it.
• A fact that cannot be read becomes None, never an exception. A dead database drops one row rather than taking down the page you opened because the database looked dead.
• The page and the JSON read the same function, so they cannot drift apart. The JSON keys are deliberately not the page's labels: page text goes through gettext and is free to be translated, while timestamps are ISO-8601 with offsets and durations are seconds. Translating the page can never rename a field a script reads.
• hq.modules.status.buildinfo imports nothing from Django and must stay that way. Projects import it from their settings module to label an admin header or a Sentry release, and at that moment django.conf.settings is still being constructed. There is a test that enforces this in a subprocess.

Development

pip install -e ".[test,sentry]"
pytest

The suite mounts the console at /console/ under the namespace console on purpose — every link is reversed from the request rather than hardcoded, and a suite that used the documented hq/ would never notice if that stopped being true.

One check is worth running by hand before a release, because a local checkout cannot catch it:

python -m build --wheel && unzip -l dist/*.whl | grep -E "templates|static"

Templates and static live under the hq package — including each module's, since the app-directories loader only searches installed apps and modules are not apps. If that ever changes, a wheel missing them fails only in a built image, as TemplateDoesNotExist.