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",
    "RELEASE": {"REPO_URL": "https://github.com/acme/widget"},
}

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

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

Most of it 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.

One page, made of panels

The console is a single page assembled from modules. Each contributes a panel, a fragment of the JSON, and optionally a few tiles; HQ["MODULES"] decides which appear and in what order.

HQ = {
    "MODULES": [
        "hq.modules.storage.module.StorageModule",     # what you care about most, first
        "hq.modules.release.module.ReleaseModule",
        "hq.modules.runtime.module.RuntimeModule",
    ],
}

A module that is not listed is never computed. This is not merely a display filter: leaving django_settings out means the settings walk never runs, and leaving storage out means nothing walks your media directory.

Settings

All optional. HQ is one dict; module settings nest under the module's slug in upper case.

Console

HQ["RELEASE"]

HQ["STORAGE"]

Secrets in the 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.

Writing a module

from hq.registry import HQModule

class CronModule(HQModule):
    slug = "cron"                 # its key in /hq/json/ too
    label = "Scheduled jobs"
    icon = "timer"                # a key in hq.icons.LUCIDE_ICONS
    width = "half"                # or "full" (the default)

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

    def get_panel(self, request):
        return {"template": "myapp/cron_panel.html", "context": {"jobs": jobs()}}

    def get_json(self, request):
        return {"next_run_seconds": 720}

    def is_available(self, request):
        return bool(settings.CRONTAB_PATH)

Then list it in HQ["MODULES"]. Everything except slug is optional; a module that renders nothing and reports nothing is legal, merely useless.

Two things worth knowing:

• A panel is rendered with its own context and nothing else. It cannot come to depend on something a neighbouring module happened to provide, and so cannot break by being reordered. The flip side: a context of the wrong shape does not raise — a missing key in a Django template is silently falsy, and you get an empty panel. Test for something only your panel produces.
• Collectors are memoised per request via hq.caching.per_request, so answering tiles, panel and JSON in one request costs one read. Decorate yours the same way.

Slugs may not collide with the console's own JSON keys (environment, generated_at); the registry refuses to start rather than let a module shadow one.

Design notes

• Nothing is fetched from a network. The interface icons (lucide, ISC) and 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 collectors, 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.
• hq.modules.release.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 every panel'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.