Installation¶

Django Cast can be installed as a standalone project or integrated into an existing Django application.

Prerequisites¶

Before you begin, ensure you have:

Python 3.11 or higher
Django 4.2 or higher
Wagtail 7.0 or higher
uv (recommended) or pip
ffmpeg (optional, for video/audio processing)

New Project Setup¶

The fastest way to start with django-cast is using the django-cast-quickstart command:

# Create a new directory for your project
mkdir myproject
cd myproject

# Create virtual environment and install django-cast
uv venv
uv pip install django-cast

# Create a new django-cast project
uv run django-cast-quickstart mysite

This command will:

Create a complete Django project structure
Configure all required settings
Run database migrations
Collect static files (including JavaScript for galleries and audio players)
Create a superuser account (username: user, password: password)
Start the development server
Open your browser to the Wagtail admin interface

Warning

The default credentials (user/password) are for development only. Always change them before deploying to production!

Command Options¶

The quickstart command supports several options:

# Default: Creates superuser with user/password
uv run django-cast-quickstart mysite

# Prompt for custom superuser credentials
uv run django-cast-quickstart mysite --interactive-superuser

# Skip superuser creation
uv run django-cast-quickstart mysite --no-superuser

After Quickstart¶

Once the server is running, you can:

Access the Wagtail admin at http://localhost:8000/cms/
Access the Django admin at http://localhost:8000/admin/
View your site at http://localhost:8000/

Integrating Into Existing Projects¶

This section explains how to add django-cast to an existing Django project.

Note

If you’re starting a new project, use the quickstart method above instead, which automates most of these steps.

Installation¶

Install django-cast in your virtual environment:

pip install django-cast
# or with uv
uv pip install django-cast

Configure Django¶

Settings¶

Add the required apps and middleware to your Django settings:

# settings.py
from cast import CAST_APPS, CAST_MIDDLEWARE

INSTALLED_APPS = [
    # Your existing Django apps...
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "django.contrib.sites",  # Required by django-cast
] + CAST_APPS  # Adds all django-cast required apps

MIDDLEWARE = [
    # Your existing middleware...
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
] + CAST_MIDDLEWARE  # Adds Wagtail and other required middleware

Note

CAST_APPS includes django-cast itself plus its required runtime apps: Wagtail, Django REST Framework, django-filter, django-htmx, comments support, django-vite, and their dependencies.

CAST_MIDDLEWARE includes the django-cast-required request middleware: HTMX support and Wagtail’s redirect middleware.

Required Settings¶

Add these essential settings:

# Wagtail settings
WAGTAIL_SITE_NAME = "My Site"
WAGTAILADMIN_BASE_URL = "http://localhost:8000"

# Site ID for django.contrib.sites
SITE_ID = 1

# Media files (user uploads)
MEDIA_ROOT = BASE_DIR / "media"
MEDIA_URL = "/media/"

# Wagtail image model
WAGTAILIMAGES_IMAGE_MODEL = "cast.Image"

Optional Settings¶

Configure additional features as needed:

# Image renditions
CAST_IMAGE_FORMATS = ["jpeg", "avif"]  # Modern image formats

# Responsive image slots
CAST_REGULAR_IMAGE_SLOT_DIMENSIONS = [
    (1110, 740),
]

# Comments
COMMENTS_APP = "cast.comments"
CAST_COMMENTS_EXCLUDE_FIELDS = ("email", "url", "title")

Each tuple defines a layout slot. django-cast generates multiple responsive renditions per slot for different pixel densities and serves them through srcset.

django-cast does not require a custom authentication backend by default. If your project already uses django-allauth or other authentication packages, keep your existing auth settings; django-cast integrates with Django’s normal user model and Wagtail admin permissions.

URL Configuration¶

Update your main URL configuration:

# urls.py
from django.contrib import admin
from django.urls import include, path
from django.conf import settings
from django.conf.urls.static import static
from cast import cast_and_wagtail_urls

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include(cast_and_wagtail_urls)),  # Includes all Cast and Wagtail URLs
]

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Database Setup¶

Create and run migrations:

python manage.py migrate
python manage.py createsuperuser

Static Files¶

django-cast includes JavaScript for galleries and audio players. Collect static files:

python manage.py collectstatic

Create Initial Content¶

Start the development server:
```
python manage.py runserver
```
Log into the Wagtail admin at http://localhost:8000/cms/
Delete any default pages
Create a HomePage at the root
Create a Blog as a child of the HomePage

Advanced Integration¶

Custom Templates¶

Override Cast templates by creating your own in your project’s template directory:

templates/
└── cast/
    ├── blog_list_page.html
    ├── post.html
    └── ...

Custom Settings Module¶

For complex projects, create a separate settings module:

# settings/cast.py
# All django-cast specific settings
CAST_IMAGE_FORMATS = ["jpeg", "avif"]
# ... other Cast settings

# settings/__init__.py
from .base import *
from .cast import *

Testing the Integration¶

Verify your installation:

# Check if models are available
python manage.py shell
>>> from cast.models import Blog, Post
>>> Blog.objects.all()

Next Steps¶

Creating Your First Blog¶

Log into the Wagtail admin
Navigate to Pages in the sidebar
Click Add child page at the root level
Choose Blog as the page type
Fill in the blog details and publish

Creating Your First Post¶

Navigate to your blog page in the admin
Click Add child page
Choose Post as the page type
Add your content using the rich text editor
Optionally add images, galleries, or audio/video
Publish your post

Further Configuration¶

Customize templates in templates/cast/
Configure additional settings (see Settings)
Set up a production database (PostgreSQL recommended)
Configure media file storage for production (see Media Handling)
Deploy to your hosting provider (see Deployment)