Skip to main content
This guide will walk you through setting up a local development environment for the Wagtail Bakery Demo project.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.10 or higher
  • pip (Python package installer)
  • Git
  • venv (Python virtual environment)

​
Installation Methods

The Bakery Demo supports multiple installation methods. Choose the one that best fits your workflow:

venv Setup

Traditional Python virtual environment setup

Docker Setup

Containerized development environment

Gitpod Setup

Cloud-based development environment

Vagrant Setup

VM-based development environment

​
Setup with venv

This is the recommended approach for developers familiar with Python and Django development.
1

Clone the Repository

Clone the Wagtail Bakery Demo repository to your local machine:
git clone https://github.com/wagtail/bakerydemo.git
cd bakerydemo
2

Create Virtual Environment

Create and activate a Python virtual environment:On macOS/Linux:
python -m venv .venv
source .venv/bin/activate
On Windows (cmd.exe):
python -m venv .venv
.venv\Scripts\activate.bat
On Windows (PowerShell):
python -m venv .venv
.venv\Scripts\Activate.ps1
3

Install Dependencies

Install the required Python packages:
pip install -r requirements/development.txt
This installs all necessary packages including:
  • Django 6.0+
  • Wagtail 7.2+
  • Development tools (ruff, djhtml, curlylint)
  • Extensions (django-debug-toolbar, django-extensions)
4

Configure Environment Files

Create local configuration files from the provided examples:
cp bakerydemo/settings/local.py.example bakerydemo/settings/local.py
cp .env.example .env
local.py - Local Django settings overridesThe bakerydemo/settings/local.py file is loaded by dev.py and allows you to override any settings without committing them to version control. By default, it’s empty:
# Override settings here
You can add custom settings like database configurations, API keys, or debug settings here..env - Environment variablesThe .env file contains Content Security Policy (CSP) directives for testing Wagtail’s CSP compatibility. These are commented out by default:
# CSP_DEFAULT_SRC="'self'"
# CSP_SCRIPT_SRC="'self', 'report-sample'"
# CSP_STYLE_SRC="'self', 'report-sample'"
# CSP_IMG_SRC="'self', blob:, i.ytimg.com, www.gravatar.com"
# CSP_CONNECT_SRC="'self', releases.wagtail.org"
# CSP_FRAME_SRC="'self', www.youtube.com"
Wagtail is not fully compatible with strict CSP policies yet. Only uncomment these for testing purposes.
5

Initialize Database

Run migrations to create the database schema:
./manage.py migrate
This creates a SQLite database file named bakerydemodb in your project root.
6

Load Initial Data

Load the demo data including pages, images, and snippets:
./manage.py load_initial_data
This command:
  • Copies media files to the configured storage
  • Removes auto-generated default Site and Page instances
  • Loads fixture data from bakerydemo/base/fixtures/bakerydemo.json
  • Updates the search index
  • Rebuilds the references index
7

Start the Development Server

Launch the Django development server:
./manage.py runserver
The site will be available at:Login credentials: admin / changeme

​
Setup with Docker

This docker-compose.yml is configured for local testing only and is not intended for production use.
1

Install Docker

Ensure you have Docker and Docker Compose installed:
2

Clone and Build

Clone the repository and build the containers:
git clone https://github.com/wagtail/bakerydemo.git --config core.autocrlf=input
cd bakerydemo
docker compose up --build -d
3

Setup Database

Wait 10 seconds for the database to initialize, then run:
docker compose run app /venv/bin/python manage.py migrate
docker compose run app /venv/bin/python manage.py load_initial_data
If you encounter a database error, wait another 10 seconds and retry.
4

Start Services

Start the application:
docker compose up
Access the site at http://localhost:8000/
Debugging Docker: To view container logs in real-time: 
docker compose logs -f

​
Setup with Gitpod

The fastest way to try Wagtail Bakery Demo without local installation:
1

Launch Gitpod

Click the button to open a pre-configured development environment:Open in Gitpod
Requires a GitHub account
2

Access the Site

Once Gitpod loads and the preview appears in the “Simple Browser” panel, click the arrow button next to the URL to open in a new tab.Navigate to /admin/ and login with admin / changeme

​
Setup with Vagrant

For developers who prefer VM-based development:
1

Install Dependencies

Install the required tools:
2

Launch VM

git clone https://github.com/wagtail/bakerydemo.git
cd bakerydemo
vagrant up
vagrant ssh
3

Start Server

Inside the SSH session:
./manage.py runserver 0.0.0.0:8000
Access at http://localhost:8000/
To stop: Use Ctrl+c to stop the server, exit to leave SSH, then vagrant halt.

​
Database Configuration

By default, the project uses SQLite for development. You can configure a different database using environment variables.

​
PostgreSQL Setup

Set the DATABASE_URL environment variable: 
export DATABASE_URL="postgres://user:password@localhost:5432/bakerydemo"
Or add it to your .env file: 
DATABASE_URL=postgres://user:password@localhost:5432/bakerydemo
When using PostgreSQL, django.contrib.postgres is automatically added to INSTALLED_APPS.

​
Development Settings

The project uses a layered settings structure: 
bakerydemo/settings/
├── base.py          # Core settings
├── dev.py           # Development overrides
├── production.py    # Production settings
├── test.py          # Test settings
└── local.py         # Your local overrides (not in version control)

​
Key Development Settings

From bakerydemo/settings/dev.py: 
DEBUG = True
EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"
WAGTAILADMIN_BASE_URL = "http://localhost:8000"
ALLOWED_HOSTS = ["*"]

​
Custom Settings

Add your overrides to bakerydemo/settings/local.py: 
# Enable Django Debug Toolbar
INSTALLED_APPS += ['debug_toolbar']
MIDDLEWARE += ['debug_toolbar.middleware.DebugToolbarMiddleware']
INTERNAL_IPS = ['127.0.0.1']

# Custom API keys
GOOGLE_MAP_API_KEY = "your-api-key-here"

​
Verifying Your Setup

After installation, verify everything works: 
curl http://localhost:8000/

​
Default Users

The demo data includes several user accounts for testing:
UsernamePasswordRolePurpose
adminchangemeSuperuserFull admin access
editorchangemeEditorContent editing
moderatorchangemeModeratorContent moderation
germanchangemeSuperuserGerman language UI
arabicchangemeSuperuserArabic language UI
inactivechangemeSuperuserInactive account (testing)

​
Next Steps

Now that your environment is set up:

Management Commands

Learn about available management commands

Customization Guide

Customize the demo for your needs

Contributing

Contribute to the project

Project Structure

Understand the codebase organization

​
Troubleshooting

Specify a different port:
./manage.py runserver 8080
Reset the database:
rm bakerydemodb
./manage.py migrate
./manage.py load_initial_data
Reinstall dependencies:
pip install -r requirements/development.txt
Make the file executable:
chmod +x manage.py

Build docs developers (and LLMs) love

Get started for freeTalk to us