Install djmvc¶

Install the package¶

pip install --pre djmvc

This installs djmvc with all runtime dependencies including the Bulma UI framework.

Note

The --pre flag is required to install pre-release versions of dependencies (currently django-autocomplete-light>=5.1).

Tip

Want to try djmvc first? See Try the demo for a quick walkthrough of the example project.

For local development (tests, docs, example project):

git clone https://github.com/jpic/djmvc.git
cd djmvc
pip install --pre -e ".[dev,docs]"

Create a Django project¶

django-admin startproject myproject
cd myproject

Configure settings¶

Import the djmvc apps and add Django’s contrib apps:

# myproject/settings.py
import djmvc.settings

INSTALLED_APPS = djmvc.settings.INSTALLED_APPS + [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # your apps with a djmvc.py module:
    # "myapp",
]

djmvc.settings.INSTALLED_APPS includes djmvc core, Bulma UI, authentication, autocomplete (DAL), site search, audit logging, and JSON API. The order ensures dal and dal_alight load before django.contrib.admin.

Configure middleware for the JSON API:

# myproject/settings.py
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "djmvc_api.middleware.BearerCsrfMiddleware",        # Before CsrfViewMiddleware
    "django.middleware.locale.LocaleMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "djmvc_api.middleware.BearerUserMiddleware",         # After AuthenticationMiddleware
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
]

Both Bearer middleware classes are required for API token authentication.

Initialize the database¶

python manage.py migrate
python manage.py createsuperuser

Configure URLs¶

Wire the djmvc site in your project’s urls.py:

# myproject/urls.py
from django.contrib import admin
from django.urls import path
import djmvc

urlpatterns = djmvc.site.build().urlpatterns + [
    path("admin/", admin.site.urls),
]

build() autodiscovers every installed app’s djmvc.py module and builds the routing tree.

Start developing¶

python manage.py runserver

Visit http://localhost:8000/auth/login/ to log in with your superuser credentials.

Next steps¶

Tutorial: Start with Stage 0 — Register a model to create your first model controller.

Reference documentation:

djmvc_api — JSON REST API, Bearer tokens, and Swagger UI
djmvc_dal — Autocomplete for relation fields
djmvc_dal_topbar — Site-wide search in the navbar
djmvc_history — Audit logging and history views
djmvc_auth — Authentication views
djmvc_debug — Route introspection (development only)

Example project: See the full example project settings at djmvc_example/settings.py on GitHub.