Skip to main content
Django + Dramatiq . Self-hosted . Open source

Django Dramatiq Dashboard

Run Dramatiq inside a Django app and you have working background jobs. Run Dramatiq with z4j and you also have a dashboard, persistent history, the task controls this adapter can execute safely, scheduler integration, RBAC with invitations, and a tamper-evident audit log. z4j is one container or one Python process; the agent is one pip extra in your existing Django venv.

Django + Dramatiq works the same way every other Django + queue combo works under z4j: pip install the framework adapter with the engine extra, set four environment variables, restart your worker. z4j stays where you put it (homelab, on-prem, or cloud); the agent always reaches out.

Install z4j Django integration details Dramatiq adapter details
install

Install z4j alongside Django + Dramatiq

1. Install the brain

bash 
pip install z4j && z4j serve

First boot prints a setup URL to stderr. Open it, create the first admin, and mint a token + HMAC secret for this agent.

2. Add the agent to your Django venv

bash 
pip install z4j-django[dramatiq]

3. Wire it into Django

python 
# settings.py
INSTALLED_APPS += ["z4j_django"]

Z4J = {
    "brain_url":   env("Z4J_BRAIN_URL"),
    "token":       env("Z4J_TOKEN"),
    "hmac_secret": env("Z4J_HMAC_SECRET"),
    "project_id":  env("Z4J_PROJECT_ID"),
    "agent_name":  env("Z4J_AGENT_NAME", default=None),
}
# That's it. No CELERY_APP, no Z4J_DEV_MODE, no dev_mode kwarg.
# Auto-detect checks the documented candidate layouts. Add CELERY_APP when
# none of those candidates resolves your application.

What you get

  • Persistent Dramatiq task history in Postgres or SQLite
  • Adapter-advertised controls: submit_task, retry_task (complete replacement inputs), purge_queue
  • Scheduler integration via apscheduler; available controls depend on that scheduler adapter
  • RBAC with invitations and password reset
  • HMAC-chained tamper-evident audit log
  • Notifications: email, Slack, Telegram, webhook
License

z4j-django and z4j-dramatiq are Apache 2.0. Importing them into your Django app does not affect your application's licensing. z4j is AGPL-3.0-or-later, isolated in its own process.

Dramatiq actions exposed

What the dashboard can actually do

Native actions

  • submit_task
  • retry_task (complete replacement inputs)
  • purge_queue
  • cancel_task (pending only; requires [abort] and real Abortable middleware)

Event capture

Z4JMiddleware, Dramatiq's blessed observability hook.

Reconciliation

Reports unknown; the brain's event-derived snapshot remains authoritative.

other Django stacks

Django with a different engine

Django +

Django Celery Dashboard

The industry standard, covered end-to-end.
Django +

Django RQ Dashboard

Lightweight Redis queue, fully instrumented.
Django +

Django Huey Dashboard

Lightweight Redis/SQLite queue, first-class.
Django +

Django arq Dashboard

Async Redis queue for FastAPI-era Python.
Django +

Django taskiq Dashboard

Broker-agnostic async task framework.
Dramatiq on other frameworks

Same engine, different framework

+ Dramatiq

Flask Dramatiq Dashboard

Flask extension pattern. One line to install.
+ Dramatiq

FastAPI Dramatiq Dashboard

Lifespan-hook integration for async stacks.

Start using Django Dramatiq Dashboard

Self-hosted, open source, no SaaS, no telemetry. z4j runs anywhere Python or Docker runs.

Install z4j Read the docs