Installation - Wagtail Bakery Demo

This guide covers all methods for installing and running the Wagtail Bakery Demo locally or in the cloud.

If you just want to try out Wagtail quickly, use Gitpod or Docker. For traditional Django development, use venv.

Gitpod Setup

Run the demo in a cloud development environment with zero local setup required.

Prerequisites

GitHub account
Modern web browser

Installation Steps

Launch Workspace

Click the Gitpod button to create a new workspace:

Automatic Setup

Gitpod will automatically execute the following setup (defined in .gitpod.yml):

# Copy local settings template
cp bakerydemo/settings/local.py.example bakerydemo/settings/local.py

# Set environment variables
echo "DJANGO_SETTINGS_MODULE=bakerydemo.settings.dev" > .env

# Install Python dependencies
python -m pip install -r requirements.txt

# Create database schema
python manage.py makemigrations
python manage.py migrate

# Load demo data
python manage.py load_initial_data

# Configure CSRF for Gitpod URLs
echo "CSRF_TRUSTED_ORIGINS = ['https://*.gitpod.io']" >> bakerydemo/settings/local.py

# Start development server
python manage.py runserver 0.0.0.0:8080

Access the Site

The demo will be available in the “Simple Browser” panel. Click the arrow button next to the URL to open it in a full browser tab.

Site: Your Gitpod URL on port 8080
Admin: Add /admin/ to your URL
Credentials: admin / changeme

Gitpod Features

Pre-configured Environment: Python, Node.js, and all dependencies installed
VS Code in Browser: Full IDE experience with Python extensions
Port Forwarding: Automatic HTTPS URLs for your development server
Persistent Workspaces: Your changes are saved between sessions

Docker Setup

Use Docker Compose to run the demo with PostgreSQL and Redis in containers.

Prerequisites

Install Docker and Docker Compose:

Docker Desktop (includes Docker Compose)
Or install Docker Engine and Docker Compose separately

Installation Steps

Clone Repository

git clone https://github.com/wagtail/bakerydemo.git --config core.autocrlf=input
cd bakerydemo

The --config core.autocrlf=input flag prevents line ending issues on Windows.

Build Containers

docker compose up --build -d

This builds and starts three services:

db: PostgreSQL 18.1 database
redis: Redis 8.4 cache
app: Django application with Python 3.12

The -d flag runs containers in the background.

Initialize Database

Wait 10 seconds for PostgreSQL to fully start, 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 see a database connection error, PostgreSQL may still be initializing. Wait 10 more seconds and retry.

Start in Foreground

docker compose up

Now the logs will be visible in your terminal.

Access the Demo

The site is now running:

Frontend: http://localhost:8000/
Admin: http://localhost:8000/admin/
Credentials: admin / changeme

Docker Configuration

The docker-compose.yml configures:

db:
  environment:
    POSTGRES_DB: app_db
    POSTGRES_USER: app_user
    POSTGRES_PASSWORD: changeme
  image: postgres:18.1
  expose:
    - '5432'

Useful Docker Commands

# Follow all logs
docker compose logs -f

# Follow specific service
docker compose logs -f app
docker compose logs -f db

Important: This Docker setup is configured for local testing only and is not intended for production use. Production deployments require additional security hardening, proper secret management, and performance optimization.

Vagrant Setup

Use Vagrant to run the demo in a Ubuntu virtual machine.

Prerequisites

Install the following on your host machine:

Installation Steps

Clone Repository

git clone https://github.com/wagtail/bakerydemo.git
cd bakerydemo

Start Vagrant VM

vagrant up

This command will:

Download the Ubuntu Jammy64 box (if not already cached)
Create and configure the virtual machine
Install Python and all dependencies
Set up the database and load demo data

The first run takes several minutes as Vagrant downloads the box image and provisions the VM.

SSH into VM

vagrant ssh

You’re now inside the virtual machine.

Start Development Server

Inside the SSH session, run:

./manage.py runserver 0.0.0.0:8000

The 0.0.0.0 address is required so the server is accessible from your host machine.

Access the Demo

From your host machine’s browser:

Frontend: http://localhost:8000/
Admin: http://localhost:8000/admin/
Credentials: admin / changeme

Vagrant Configuration

The Vagrantfile configures:

# Ubuntu Jammy 22.04 LTS
config.vm.box = "ubuntu/jammy64"
config.vm.box_version = "~> 20220810.0.0"

# Port forwarding
config.vm.network "forwarded_port", guest: 8000, host: 8000

Vagrant Commands

# Start the VM
vagrant up

# Stop the VM
vagrant halt

# Restart the VM
vagrant reload

# Delete the VM
vagrant destroy

Stopping the Server

Press Ctrl+C in the SSH session to stop the Django server
Type exit to leave the SSH session
Run vagrant halt to stop the VM

Venv Setup

Traditional Django development setup using Python’s built-in virtual environment.

Prerequisites

Python 3.10 or higher
pip (Python package installer)
venv (included with Python 3.3+)

This method is recommended for developers familiar with Django and Python development.

Installation Steps

Create Virtual Environment

python -m venv .venv
source .venv/bin/activate

Your terminal prompt should now show (.venv) indicating the virtual environment is active.

Clone Repository

git clone https://github.com/wagtail/bakerydemo.git
cd bakerydemo

Install Dependencies

pip install -r requirements/development.txt

This installs:

Django 6.0+
Wagtail 7.2+
PostgreSQL adapter (psycopg)
Development tools (debug toolbar, extensions)
All other required packages

Create Configuration Files

cp bakerydemo/settings/local.py.example bakerydemo/settings/local.py
cp .env.example .env

Windows users: use copy instead of cp

These files allow you to customize local settings without affecting version control:

local.py - Django settings overrides
.env - Environment variables

Set Up Database

./manage.py migrate
./manage.py load_initial_data

Windows users: use python manage.py instead of ./manage.py

The default configuration uses SQLite, so no database installation is required.

Start Development Server

./manage.py runserver

The server will start at:

Frontend: http://127.0.0.1:8000/
Admin: http://127.0.0.1:8000/admin/
Credentials: admin / changeme

Project Dependencies

Key packages from requirements/base.txt:

Django>=6.0,<6.1
wagtail>=7.2,<7.3
python-dotenv>=1.2.1,<2
dj-database-url>=3.1.0,<4

Configuration Files

The demo uses several configuration files:

File	Purpose	Required
`bakerydemo/settings/local.py`	Local Django settings overrides	No, but recommended
`.env`	Environment variables (secrets, URLs)	No, but recommended
`bakerydemo/settings/base.py`	Base Django configuration	Yes
`bakerydemo/settings/dev.py`	Development settings	Yes
`bakerydemo/settings/production.py`	Production settings	Yes

Warnings will be displayed if local.py and .env are not present, but they’re not strictly required for basic functionality.

Using PostgreSQL Locally

To use PostgreSQL instead of SQLite:

Install PostgreSQL

Install PostgreSQL for your platform:

Ubuntu/Debian: sudo apt install postgresql postgresql-contrib
macOS: brew install postgresql
Windows: Download from postgresql.org

Create Database

# Create user and database
createuser -P bakerydemo_user
createdb -O bakerydemo_user bakerydemo_db

Update .env

Add to your .env file:

DATABASE_URL=postgres://bakerydemo_user:yourpassword@localhost/bakerydemo_db

Install PostgreSQL Adapter

pip install psycopg[binary]

Django Management Commands

# Create migrations
./manage.py makemigrations

# Apply migrations
./manage.py migrate

# Create superuser
./manage.py createsuperuser

Troubleshooting

Database Connection Issues

PostgreSQL connection refused

Docker: Wait 10-15 seconds after docker compose up for PostgreSQL to initialize.Local: Ensure PostgreSQL is running:

# Linux
sudo systemctl status postgresql

# macOS
brew services list

# Windows
# Check Services app for "postgresql" service

Database 'app_db' does not exist

You need to run migrations first:

docker compose run app /venv/bin/python manage.py migrate

Import Errors

ModuleNotFoundError

Ensure your virtual environment is activated and dependencies are installed:

source .venv/bin/activate  # or appropriate activation for your OS
pip install -r requirements/development.txt

ImportError: No module named 'wagtail'

The virtual environment may not be activated, or Wagtail isn’t installed:

pip install wagtail

Port Already in Use

Address already in use: 0.0.0.0:8000

Another service is using port 8000. Either stop that service or use a different port:

./manage.py runserver 8001

For Docker:

# Edit docker-compose.yml and change ports to:
ports:
  - '8001:8000'

Docker Issues

docker compose command not found

You may have an older version of Docker. Try:

docker-compose up --build -d

Or update Docker Desktop to the latest version.

Permission denied on Linux

Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Static Files Issues

Static files not loading

Collect static files:

./manage.py collectstatic --noinput

For Docker:

docker compose run app /venv/bin/python manage.py collectstatic --noinput

Testing Different Wagtail Versions

The demo’s main branch works with both the latest stable Wagtail release and the development version. To test specific versions:

# Clone and checkout a specific version tag
git clone https://github.com/wagtail/bakerydemo.git
cd bakerydemo
git checkout v6.4  # or v6.3, v6.2, etc.

Available version tags:

v6.4 - Compatible with Wagtail 6.4
v6.3 - Compatible with Wagtail 6.3
v6.2 - Compatible with Wagtail 6.2
v6.1 - Compatible with Wagtail 6.1

See the complete tags list for older releases.

Next Steps

Explore the Code

Read through the source code to understand how Wagtail applications are structured. Pay special attention to models, blocks, and hooks.

Try the Features

Log into /admin/ and experiment with creating pages, uploading images, and using StreamField.

Read Wagtail Docs

Visit docs.wagtail.org to learn more about Wagtail’s features and best practices.

Start Your Project

Ready to build your own site? Use wagtail start to create a new project from scratch.

Get Started

Core Concepts

Content Types

Features

Deployment

Development

​Gitpod Setup

​Prerequisites

​Installation Steps

​Gitpod Features

​Docker Setup

​Prerequisites

​Installation Steps

​Docker Configuration

​Useful Docker Commands

​Vagrant Setup

​Prerequisites

​Installation Steps

​Vagrant Configuration

​Vagrant Commands

​Stopping the Server

​Venv Setup

​Prerequisites

​Installation Steps

​Project Dependencies

​Configuration Files

​Using PostgreSQL Locally

​Django Management Commands

​Troubleshooting

​Database Connection Issues

​Import Errors

​Port Already in Use

​Docker Issues

​Static Files Issues

​Testing Different Wagtail Versions

​Next Steps

Explore the Code

Try the Features

Read Wagtail Docs

Start Your Project

Build docs developers (and LLMs) love

Gitpod Setup

Prerequisites

Installation Steps

Gitpod Features

Docker Setup

Prerequisites

Installation Steps

Docker Configuration

Useful Docker Commands

Vagrant Setup

Prerequisites

Installation Steps

Vagrant Configuration

Vagrant Commands

Stopping the Server

Venv Setup

Prerequisites

Installation Steps

Project Dependencies

Configuration Files

Using PostgreSQL Locally

Django Management Commands

Troubleshooting

Database Connection Issues

Import Errors

Port Already in Use

Docker Issues

Static Files Issues

Testing Different Wagtail Versions

Next Steps