dj-control-room-base

dj-control-room-base is a core library for Django Control Room panels. It provides the shared primitives that every panel needs: settings management, CSS injection, permission enforcement, admin sidebar integration, template context helpers, and MCP-style panel tools.

Official Django Control Room panels ship with this package as a dependency and build on these APIs rather than reimplementing them panel by panel.

Optionally, the package can also be mounted as a full panel in its own right: it ships a bundled design system reference UI and example patterns that are useful when building or theming new panels.

• Official site: djangocontrolroom.com
• Control Room app: dj-control-room
• Docs: django-control-room.github.io/dj-control-room-base

What this library provides

• Centralized CSS and permissions - a single PanelConfig object per panel drives CSS injection, staff/group/superuser checks, and settings merging across built-in, panel, hub, and project layers.
• Admin sidebar integration - PanelPlaceholderModel and BasePanelAdmin give any panel a sidebar entry with no extra migrations.
• Template context helpers - panel_config.get_context(request, ...) returns a ready-to-use context with CSS and Django admin variables included.
• Entry-point discovery - panels register with the hub via a PanelPlugin subclass and a pyproject.toml entry point.
• Internal panel scaffold - python manage.py dcr_startpanel <name> creates a minimal project panel app (dcr_-prefixed). For publishable panel repos, use the Cookiecutter template.
• Panel tools - optional, permission-scoped callables the dj-control-room hub aggregates for AI agent and in-admin chat integrations.
• Theme adapters - stylesheets that match panels to django-unfold, django-jazzmin, django-grappelli, django-admin-interface, or django-admin-dracula, auto-selected from INSTALLED_APPS when THEME_AUTO_DETECT is enabled (default). Known unsupported skins get a general-light or general-dark pin instead of following OS color-scheme alone.

See the full documentation for configuration options and a guide to building your own panel on this library.

Requirements

• Python 3.9+
• Django 4.2+ (tested in CI across Django 4.2, 5.2, and 6.0)

Quick start

pip install dj-control-room-base

# settings.py
INSTALLED_APPS = [
    ...
    "dj_control_room_base",
]

# urls.py
urlpatterns = [
    path("admin/dj-control-room-base/", include("dj_control_room_base.urls")),
    path("admin/", admin.site.urls),
]

python manage.py migrate
python manage.py runserver

Open /admin/ and sign in. A DJ CONTROL ROOM BASE entry appears in the sidebar and links to the panel at /admin/dj-control-room-base/.

See Installation for the complete walkthrough, Configuration for CSS/permission settings and theme adapters, and Building Panels for a guide to building your own panel on this library.

Contributing

git clone https://github.com/django-control-room/dj-control-room-base.git
cd dj-control-room-base
make install
make test_local

See Contributing for Docker setup, coverage, and the full Makefile reference.

License

MIT. See LICENSE.