Deploying Wagtail

Introduction

Wagtail is an open-source content management system built on Django, combining the power of a full-featured framework with an elegant, user-friendly interface. Used by organizations like Google, NASA, and Mozilla, Wagtail excels at structured content management with its innovative StreamField for flexible page layouts.

Key highlights of Wagtail:

• StreamField: Flexible content blocks for building dynamic page layouts
• Intuitive Admin: Modern, user-friendly admin interface for content editors
• Django Foundation: Built on Django with full access to the Python ecosystem
• Image Management: Built-in image library with focal point cropping
• Document Management: Organize and serve documents with access control
• Search: Elasticsearch or database-backed search functionality
• Multi-Site: Manage multiple websites from a single installation
• Revision History: Full content versioning and rollback capabilities
• Workflow: Customizable publishing workflows for editorial teams
• API Ready: Built-in REST and GraphQL API options

This guide walks through deploying Wagtail on Klutch.sh using Docker, configuring the CMS, and building your first site.

Why Deploy Wagtail on Klutch.sh

Deploying Wagtail on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Wagtail without complex orchestration. Push to GitHub, and your CMS deploys automatically.

Persistent Storage: Attach persistent volumes for media files and database. Your content survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure content management.

GitHub Integration: Connect your Wagtail project directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your site’s traffic and content volume.

Prerequisites

Before deploying Wagtail on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Wagtail project
• Basic familiarity with Docker, Python, and Django concepts
• A PostgreSQL database (recommended for production)

Preparing Your Repository

Create a Wagtail project and Dockerfile for deployment.

Repository Structure

wagtail-site/
├── Dockerfile
├── requirements.txt
├── manage.py
├── mysite/
│   ├── __init__.py
│   ├── settings/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── production.py
│   ├── urls.py
│   └── wsgi.py
├── home/
│   ├── models.py
│   └── templates/
└── .dockerignore

Creating the Dockerfile

FROM python:3.11-slim

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV DJANGO_SETTINGS_MODULE=mysite.settings.production

# Install system dependencies
RUN apt-get update && apt-get install -y \
    libpq-dev \
    gcc \
    libjpeg-dev \
    zlib1g-dev \
    libwebp-dev \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt gunicorn

# Copy project files
COPY . .

# Create media and static directories
RUN mkdir -p /app/media /app/static

# Collect static files
RUN python manage.py collectstatic --noinput

# Expose port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/')" || exit 1

# Run with gunicorn
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "3", "mysite.wsgi:application"]

Creating requirements.txt

wagtail>=5.2
Django>=4.2
psycopg2-binary
whitenoise
django-storages
boto3
pillow

Production Settings

Create mysite/settings/production.py:

from .base import *
import os

DEBUG = False

SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')

ALLOWED_HOSTS = os.environ.get('DJANGO_ALLOWED_HOSTS', '').split(',')

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME'),
        'USER': os.environ.get('DB_USER'),
        'PASSWORD': os.environ.get('DB_PASSWORD'),
        'HOST': os.environ.get('DB_HOST'),
        'PORT': os.environ.get('DB_PORT', '5432'),
    }
}

# Static files
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'
STATIC_ROOT = '/app/static'

# Media files
MEDIA_ROOT = '/app/media'
MEDIA_URL = '/media/'

# Security
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
CSRF_TRUSTED_ORIGINS = [f"https://{host}" for host in ALLOWED_HOSTS]

Environment Variables Reference

Variable	Required	Default	Description
DJANGO_SECRET_KEY	Yes	-	Django secret key
DJANGO_ALLOWED_HOSTS	Yes	-	Comma-separated allowed hosts
DB_HOST	Yes	-	PostgreSQL host
DB_PORT	No	5432	PostgreSQL port
DB_NAME	Yes	-	Database name
DB_USER	Yes	-	Database username
DB_PASSWORD	Yes	-	Database password

Deploying Wagtail on Klutch.sh

Set Up PostgreSQL Database

Deploy a PostgreSQL instance on Klutch.sh or use an external database service. Create a database for Wagtail.

Generate a Secret Key

Generate a secure Django secret key:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Push Your Repository to GitHub

Initialize your repository and push to GitHub with your Wagtail project.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “wagtail-site” or “cms”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Wagtail project.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8000

Set Environment Variables

Add the following environment variables:

Variable	Value
DJANGO_SECRET_KEY	Your generated secret key
DJANGO_ALLOWED_HOSTS	your-app-name.klutch.sh
DB_HOST	Your PostgreSQL hostname
DB_NAME	wagtail
DB_USER	Your database username
DB_PASSWORD	Your database password

Attach Persistent Volumes

Add the following volume:

Mount Path	Recommended Size	Purpose
/app/media	20 GB	Uploaded images and documents

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision an HTTPS certificate.

Run Database Migrations

After deployment, run migrations and create a superuser via the container console or startup script.

Access Wagtail Admin

Once deployment completes, access the admin at https://your-app-name.klutch.sh/admin/.

Building Your Site

Creating Page Types

Define custom page types in home/models.py:

from wagtail.models import Page
from wagtail.fields import StreamField
from wagtail.admin.panels import FieldPanel
from wagtail import blocks
from wagtail.images.blocks import ImageChooserBlock

class HomePage(Page):
    body = StreamField([
        ('heading', blocks.CharBlock(form_classname="title")),
        ('paragraph', blocks.RichTextBlock()),
        ('image', ImageChooserBlock()),
    ], use_json_field=True)

    content_panels = Page.content_panels + [
        FieldPanel('body'),
    ]

Using StreamField

StreamField enables flexible content layouts:

• Define reusable content blocks
• Mix and match blocks on each page
• Nest blocks within blocks (StructBlock, ListBlock)

Managing Images

1. Navigate to Images in the admin sidebar
2. Upload images to the library
3. Set focal points for responsive cropping
4. Use images across multiple pages

User Management

Creating Editors

1. Go to Settings > Users
2. Add users with appropriate roles
3. Assign group permissions

Editorial Workflow

Configure moderation workflows:

1. Create workflow stages (Draft, Review, Publish)
2. Assign reviewers to stages
3. Enable workflow on page types

Troubleshooting

Static Files Not Loading

• Verify collectstatic ran during build
• Check STATIC_URL and STATICFILES_STORAGE settings
• Ensure whitenoise is configured correctly

Media Uploads Failing

• Verify volume mount is correct
• Check file permissions
• Review MEDIA_ROOT configuration

Database Connection Issues

• Verify database credentials
• Check network connectivity
• Ensure database exists and is accessible

Additional Resources

• Wagtail Official Website
• Wagtail Documentation
• Wagtail GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Wagtail on Klutch.sh gives you a powerful, flexible CMS backed by Django’s robust ecosystem. The combination of Wagtail’s StreamField editing and Klutch.sh’s deployment simplicity means you can quickly build sophisticated websites with an intuitive content management experience.