bakerydemo: the Wagtail demo project to read rather than to copy

A demo that tells you not to build on it

The Wagtail demo project is a demonstration project for the Wagtail CMS, and the README is unusually clear about its role. The demo site is designed to provide examples of common features and recipes to introduce you to Wagtail development, and beyond the code it lets you explore the admin and editorial interface of the CMS.

Then the sentence that decides how to use it: we do not recommend using this project to start your own site, the demo is intended to be a springboard to get you started, and you are free to copy code from the demo into your own project.

That distinction matters and it is the reason the project exists. A demo that you clone and adapt becomes your project, with its structure, its settings and its debt. A demo that you read gives you the patterns without the inheritance, and the next steps section points at the supported alternative, the wagtail start command, for starting a real project.

The project is the next generation Wagtail demo, born in Reykjavik, and it is maintained as part of the Wagtail organisation, which is why it tracks the framework rather than lagging behind it.

What the demo is actually showing

The README lists the code worth paying attention to, and the list is a curriculum in Wagtail application structure.

There is the division of a project into multiple apps, which is the structural decision most teams get wrong. There are custom content models and contexts in the breads and locations apps, which shows how a domain with its own vocabulary is modelled. There is a typical weblog in the blog app, and an example of a base app used to hold miscellaneous functionality such as a contact form and an about page, which is the pattern for code that does not belong to one domain.

The StandardPage model uses mixins borrowed from other apps, which is how shared page behaviour is done without inheritance from a base class. The snippets system is used to represent bread categories, countries and ingredients, which is the right tool for reference data that is edited in the admin rather than authored as pages. A custom Galleries feature pulls in images used in other content types, and the Ingredients feature on BreadPage is an example of a ManyToMany relationship.

The last item on the list is the one that distinguishes Wagtail from a generic Django CMS: customising the Wagtail admin via wagtail_hooks. A developer reading the demo is expected to read its source, and the admin customisation is where the framework earns its keep.

The venv route, which the README recommends first

If you want to see what Wagtail is all about, the README suggests trying it out locally in a virtual environment, and that is the recommended installation approach for Django itself. The requirements are Python 3.10 or newer, venv, and optionally uv as a faster alternative to venv and pip.

On GNU/Linux or macOS:

# Using Python's venv:
python -m venv .venv
# Or using uv:
uv venv .venv
source .venv/bin/activate

Windows has two activation commands, .venv\Scripts\Activate.ps1 for PowerShell and .venv\Scripts\activate.bat for the command prompt, and the README explains the PowerShell execution policy error that comes up when scripts are disabled on the system, with the two ways around it, using activate.bat in the command prompt or allowing scripts for your user account with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Then the project itself, with pip or uv installing from requirements/development.txt, and then two files that are deliberately outside version control, .env and bakerydemo/settings/local.py, copied from their examples, with a note that cp is for bash and Windows uses copy. The README says no such settings are required for a standard installation, but that warnings will be displayed if these files are not present.

Finally the database and the content, with ./manage.py migrate, ./manage.py load_initial_data and ./manage.py runserver. The demo loads its own bakery content, which is what makes the gallery and the ingredient relationships visible in the admin.

Docker, and the ten second wait

The Docker route exists for readers who are new to Python or Django, and the README suggests it or Vagrant, whichever the reader is more comfortable with, because both resolve common software dependency issues.

The commands are short:

git clone https://github.com/wagtail/bakerydemo.git --config core.autocrlf=input
cd bakerydemo
docker compose up --build -d

The clone flag is the detail to notice, since core.autocrlf=input stops Windows from rewriting line endings in the shell scripts. After the build returns to the prompt, the README asks you to wait ten more seconds for the database setup to complete, and then to run the migrations and the data load inside the container:

docker compose exec app /venv/bin/python manage.py migrate
docker compose exec app /venv/bin/python manage.py load_initial_data

If that fails with a database error, the instruction is to wait ten more seconds and retry, which is an honest description of a race between the database container and the setup step. Finally docker compose up brings the site up properly, and for debugging the README has docker compose logs -f to tail the containers in real time.

One warning stands out and should be read twice. The docker-compose.yml is configured for local testing only and is not intended for production use.

Vagrant, for a disposable machine

The third route needs Vagrant and Virtualbox, and the sequence is to clone the repository, change into the directory, bring the machine up, ssh into it and start the server from inside:

git clone https://github.com/wagtail/bakerydemo.git
cd bakerydemo
vagrant up
vagrant ssh
# then, within the SSH session:
./manage.py runserver 0.0.0.0:8000

The site is then at http://localhost:8000/ and the admin at http://localhost:8000/admin/, with the credentials admin and changeme. To stop the local server you use Ctrl+c, and to stop the Vagrant environment you exit the session and run vagrant halt.

The credentials are worth noting on their own. They are printed in the README for all three install routes, and they are the same for the Docker and venv setups too, which is safe for a local demo and is exactly why the compose file is marked as not for production use.

The three routes cover different situations, and the venv one is the fastest for a reader who already has Python, the Docker one for a reader who wants a reproducible dependency set without thinking about it, and Vagrant for a reader who wants the whole machine thrown away afterwards.

Where the demo is the wrong starting point

The first wrong-tool case, which the README names, is using this project as the base of a new site. The demo carries demo decisions, demo content types and demo settings, and inheriting them means deleting them later, which is more work than starting from wagtail start.

The second is a production deployment. The compose file is documented as local testing only, the admin credentials are published in the README, and the local settings file is a copy of an example. Nothing here is hardened, and the README is clear that it was never meant to be.

The third is a team that wants a reference implementation of production architecture. The demo shows how Wagtail features look, and the apps are arranged to make the features legible rather than to model a real domain. A team with a complicated domain will find the example structure too clean to copy without rethinking it.

There is also the coupling question. The demo tracks Wagtail closely, and it uses the internals, since the README says it is aimed primarily at developers wanting to learn more about the internals of Wagtail and assumes you will be reading its source code. That is a strength for learning and a reason to be careful about copying patterns that depend on internals rather than on the public API.

BSD-3-Clause and a repository that spans four toolchains

The project is licensed BSD-3-Clause, and the repository is not archived, with the last push on 2026-10-15 and the default branch on main. There are no GitHub releases, which makes sense for a demo that is deployed from the branch.

The repository is a good illustration of a Django project that has grown up alongside its tooling. There is a Dockerfile, a docker-compose.yml and a docker-entrypoint.sh for the container route, a Vagrantfile and a vagrant/ directory, a Makefile, a Procfile and a heroku.yml for deployment platforms, a stellar.yaml, a runtime.txt, and a manage.py. The Python side has a requirements.txt and a requirements/ directory, a .python-version, a ruff.toml, and an .env.example alongside the settings example. The front end has a package.json, an eslint config, a stylelint config, a prettier config, a .nvmrc and a .pre-commit-config.yaml.

The package.json is the interesting part for anyone wondering whether this is still a Django project with a bit of JavaScript. The scripts are entirely tooling, with lint:js, lint:css and lint:format, a combined lint, and fix and format variants, and the dev dependencies are eslint with the flat config, the Wagtail stylelint config, prettier and stylelint. There is no front end application to build, which matches a CMS whose admin ships as part of the framework.

The copy at the repository root is readme.md, while the README the project publishes is the same document, and the .git-blame-ignore-revs file is there because a formatting sweep would otherwise rewrite every line of history.

Editorial conclusion

Adopt bakerydemo as a reading project, clone it, run it locally and read the source when you need to see how a Wagtail application is structured across apps, snippets and admin hooks. Do not adopt it as the base of a new site, because the README explicitly advises against that and tells you to use wagtail start instead. Before you rely on any pattern from it, check that the example still matches the Wagtail version you are on, and remember that the compose file is for local testing only and is not intended for production.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. wagtail/bakerydemo on GitHub