Skip to main content

Getting Started

Added in 1.0.1

This page is the shortest path from an empty Django project to a working Chassis Admin: package install, app order, a custom AdminSite, and one ModelAdmin with options.

Installation​

pip install django-chassis

Put 'django_chassis' before 'django.contrib.admin' so package templates overlay the stock Admin:

INSTALLED_APPS = [
    'django_chassis',
    'django.contrib.admin',
    # ...
]

If this order is reversed, Django loads stock Admin templates first and the Chassis shell will not appear.

A Chassis site registers stock Users and Groups (no product roles), admin sessions, login attempts, and the Admin journal. Add the session and audit middleware after authentication; see Users and access.

Create an AdminSite​

ChassisAdminSiteMixin must come before AdminSite in the MRO.

from django.contrib.admin import AdminSite
from django.urls import path
from django.utils.translation import gettext_lazy as _

from django_chassis.mixins import ChassisAdminSiteMixin


class CustomAdminSite(ChassisAdminSiteMixin, AdminSite):
    chassis_brand_name = _('My project')
    chassis_brand_logo_static_path = 'img/logo.png'


admin_site = CustomAdminSite(name='admin')

Mount that instance in urls.py instead of admin.site.urls:

from django.urls import path

from myproject.admin import admin_site

urlpatterns = [path('admin/', admin_site.urls)]

Create a ModelAdmin​

ChassisAdminMixin must come before ModelAdmin. Capabilities are collected in the options list — frozen dataclasses, not ad-hoc template forks.

from django.contrib.admin import ModelAdmin

from django_chassis.mixins import ChassisAdminMixin
from django_chassis.options import RowActionsOption, SearchOption

from catalog.models import Book


class BookAdmin(ChassisAdminMixin, ModelAdmin):
    options = [SearchOption(fields=['title', 'isbn']), RowActionsOption()]


admin_site.register(Book, BookAdmin)

RowActionsOption() without arguments adds a view button in the last changelist column. The first column is not a link by default (chassis_link_first_column = False).

Optional worker extras​

Changed in 1.0.19

Import and export files are stored in STORAGES['media']. Background processing is optional:

pip install 'django-chassis[dramatiq]'
# or / либо
pip install 'django-chassis[celery]'

See Import and export backends before enabling a worker provider in production.

To run a WSGI project under Gunicorn (optional):

Changed in 1.0.20 
pip install 'django-chassis[gunicorn]'
python manage.py run_gunicorn --port=8000 --workers=2

See Settings and checks.

ASGI and combined extras​

Added in 1.0.20 
pip install 'django-chassis[uvicorn,dramatiq]'
python manage.py run_uvicorn --host 127.0.0.1 --port 8000 --workers 1 --reload
# All optional runtimes: Gunicorn, Uvicorn, Dramatiq and Celery
pip install 'django-chassis[all]'

The base package has no web-server or external-worker dependency. Multiple extras combine their dependencies. [uvicorn] installs uvicorn[standard], including WebSocket and reload support; [dramatiq] installs the existing Dramatiq adapter's runtime. Configure ASGI_APPLICATION, the worker broker and storage in your project. Broker-specific packages such as dramatiq-postgres and PostgreSQL drivers are application dependencies. Installing extras does not start servers/workers or activate import/export. See Settings and checks.

  1. How it works — who resolves options on a request.
  2. Admin site — brand, sidebar, pages, dashboard.
  3. ModelAdmin — the options list and Settings.
  4. Options catalog — every field of every option.

See also​