wagtail / bakerydemo

Next generation Wagtail demo, born in Reykjavik

Wagtail demo project

This is a demonstration project for the amazing Wagtail CMS.

The demo site is designed to provide examples of common features and recipes to introduce you to Wagtail development. Beyond the code, it will also let you explore the admin / editorial interface of the CMS.

Note we do not recommend using this project to start your own site - the demo is intended to be a springboard to get you started. Feel free to copy code from the demo into your own project.

Wagtail Features Demonstrated in This Demo

This demo is aimed primarily at developers wanting to learn more about the internals of Wagtail, and assumes you'll be reading its source code. After browsing the features, pay special attention to code we've used for:

• Dividing a project up into multiple apps
• Custom content models and "contexts" in the "breads" and "locations" apps
• A typical weblog in the "blog" app
• Example of using a "base" app to contain misc additional functionality (e.g. Contact Form, About, etc.)
• "StandardPage" model using mixins borrowed from other apps
• Example of customizing the Wagtail Admin via wagtail_hooks
• Example of using the Wagtail "snippets" system to represent bread categories, countries and ingredients
• Example of a custom "Galleries" feature that pulls in images used in other content types in the system
• Example of creating ManyToMany relationships via the Ingredients feature on BreadPage
• Lots more

Document contents

• Installation
• Next steps
• Contributing
• Other notes

Installation

• Gitpod
• Vagrant
• Docker
• Virtualenv

If you want to see what Wagtail is all about, we suggest trying it out through Gitpod. If you want to set up Wagtail locally instead, and you're new to Python and/or Django, we suggest you run this project on a Virtual Machine using Vagrant or Docker (whichever you're most comfortable with). Both Vagrant and Docker will help resolve common software dependency issues. Developers more familiar with virtualenv and traditional Django app setup instructions should skip to Setup with virtualenv.

Setup with Gitpod

Set up a development environment and run this demo website with a single click (requires a Github account):

Once Gitpod has fully started, and a preview of the bakery website has appeared in the "Simple Browser" panel, click the arrow button to the right of the URL bar to open the website in a new tab. Go to /admin/ and login with admin / changeme.

Setup with Vagrant

Dependencies

• Vagrant
• Virtualbox

Installation

Once you've installed the necessary dependencies run the following commands:

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 demo site will now be accessible at http://localhost:8000/ and the Wagtail admin interface at http://localhost:8000/admin/.

Log into the admin with the credentials admin / changeme.

Use Ctrl+c to stop the local server. To stop the Vagrant environment, run exit then vagrant halt.

Setup with Docker

Dependencies

• Docker
• Docker Compose

Installation

Run the following commands:

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

After this command completes and returns to the command prompt, wait 10 more seconds for the database setup to complete. 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 this fails with a database error, wait 10 more seconds and re-try. Finally, run:

docker compose up

The demo site will now be accessible at http://localhost:8000/ and the Wagtail admin interface at http://localhost:8000/admin/.

Log into the admin with the credentials admin / changeme.

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

Debugging

To tail the logs from the Docker containers in realtime, run:

docker compose logs -f

Setup with Virtualenv

You can run the Wagtail demo locally without setting up Vagrant or Docker and simply use Virtualenv, which is the recommended installation approach for Django itself.

Dependencies

• Python 3.7, 3.8, 3.9, 3.10 or 3.11
• Virtualenv
• VirtualenvWrapper (optional)

Installation

With PIP and virtualenvwrapper installed, run:

mkvirtualenv wagtailbakerydemo
python --version

Confirm that this is showing a compatible version of Python 3.x. If not, and you have multiple versions of Python installed on your system, you may need to specify the appropriate version when creating the virtualenv:

deactivate
rmvirtualenv wagtailbakerydemo
mkvirtualenv wagtailbakerydemo --python=python3.9
python --version

Now we're ready to set up the bakery demo project itself:

cd ~/dev [or your preferred dev directory]
git clone https://github.com/wagtail/bakerydemo.git
cd bakerydemo
pip install -r requirements/development.txt

Next, we need to create the files .env and bakerydemo/settings/local.py, which provide a place for local configuration settings that need to be kept outside of version control. No such settings are required for a standard installation, but warnings will be displayed if these files are not present:

cp bakerydemo/settings/local.py.example bakerydemo/settings/local.py
cp .env.example .env
# `cp` is used for bash. Windows Command Prompt uses `copy`

To set up your database and load initial data, run the following commands:

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

Log into the admin with the credentials admin / changeme.

Next steps

Hopefully after you've experimented with the demo you'll want to create your own site. To do that you'll want to run the wagtail start command in your environment of choice. You can find more information in the getting started Wagtail CMS docs.

Contributing

If you're a Python or Django developer, fork the repo and get stuck in! If you'd like to get involved you may find our contributing guidelines a useful read.

Preparing this archive for distribution

If you change content or images in this repo and need to prepare a new fixture file for export, do the following on a branch:

./manage.py dumpdata --natural-foreign --indent 2 -e auth.permission -e contenttypes -e wagtailcore.GroupCollectionPermission -e wagtailimages.rendition -e sessions -e wagtailsearch.indexentry -e wagtailsearch.sqliteftsindexentry -e wagtailcore.referenceindex -e wagtailcore.pagesubscription > bakerydemo/base/fixtures/bakerydemo.json
prettier --write bakerydemo/base/fixtures/bakerydemo.json

Please optimize any included images to 1200px wide with JPEG compression at 60%. Note that media/images is ignored in the repo by .gitignore but media/original_images is not. Wagtail's local image "renditions" are excluded in the fixture recipe above.

Make a pull request to https://github.com/wagtail/bakerydemo

Other notes

Local configuration files

The bakerydemo/settings/local.py file can be used to store local Django settings such as database connection details that need to be kept outside of version control.

Additionally, various settings can be controlled through environment variables. The django-dotenv package is used to load these variables from a .env file in the project root.

Note on demo search

Because we can't (easily) use ElasticSearch for this demo, we use wagtail's native DB search. However, native DB search can't search specific fields in our models on a generalized Page query. So for demo purposes ONLY, we hard-code the model names we want to search into search.views, which is not ideal. In production, use ElasticSearch and a simplified search query, per https://docs.wagtail.org/en/stable/topics/search/searching.html.

Sending email from the contact form

The following setting in base.py and production.py ensures that live email is not sent by the demo contact form.

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

In production on your own site, you'll need to change this to:

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'

and configure SMTP settings appropriate for your email provider.

Testing Content-Security-Policy compliance in Wagtail

Bakerydemo is set up in such a way that it can be used to test Content-Security-Policy compatibility in Wagtail. It uses django-csp to generate the appropriate CSP HTTP header.

By default, django-csp is not enabled since Wagtail isn't fully compatible yet. Set the CSP_DEFAULT_SRC environment variable in your .env file to set the default policy. An example can be found in .env.example.

Testing against different versions of Wagtail

The main branch of this demo is designed to work with both the latest stable release and the latest main branch (development version) of Wagtail. To run the demo against a specific version of Wagtail, we have created git tags for the latest commits that work with each feature release.

• v5.1
• v5.0
• v4.2
• v4.1
• v4.0
• v3.0
• v2.16

The tags point to the last commit just before the requirements were updated to the next Wagtail version. For example, the v4.2 tag points to the commit just before the bakerydemo was updated to use Wagtail 5.0. This ensures that the tagged demo code contains the latest updates possible for the supported version.

There were no updates to the demo between Wagtail 4.1 and 4.2, so the v4.1 and v4.2 tags point to the same commit.

Users included in demo data

The demo data includes users with different roles and preferences. You can use these users to quickly test the permission system in Wagtail or how localization is handled in the admin interface.

Username	Password	Superuser	Groups	Preferred language	Timezone	Active
admin	changeme	Yes	None	undefined	undefined	Yes
editor	changeme	No	Editors	undefined	undefined	Yes
moderator	changeme	No	Moderators	undefined	undefined	Yes
inactive	changeme	yes	None	undefined	undefined	No
german	changeme	yes	None	German	Europe/Berlin	Yes
arabic	changeme	yes	None	Arabic	Asia/Beirut	Yes

Ownership of demo content

All content in the demo is public domain. Textual content in this project is either sourced from Wikimedia (Wikipedia for blog posts, Wikibooks for recipes) or is lorem ipsum. All images are from either Wikimedia Commons or other copyright-free sources.

bakerydemo's Issues

Show blog author bylines (and avatars?) on BlogIndex and BlogPage

Style blog index page

Use header includes on LocationIndexPage and BreadsIndexPage

Totally my fault, I forgot to use these despite having them from BlogIndexPage.

Validation on long lat co-ordinates

Putting in anything other than the expected format for long lat co-ordinate into the editor will give an IndexError list index out of range error.

A long lat will normally be something like 64.127146, -21.880038. Co-ordinates that aren't valid (e.g. 10391293939, -1238929101) will avoid the error, but putting in abc or 123 -123 etc. will create the error.

Regex on the field?

Demonstrate ManyToMany

Wagtail 1.9 now supports true ManyToMany relations. This is a pretty big deal and erases a long-standing limitation. I know it's late in the game but can we think of a way to demonstrate this important feature?

About page

WagtailBakery admin menu item

We are surfacing the People snippet under WagtailBakery. But People and the other three snippet models are already present under Snippets. Do we want to move all snippets under WagtailBakery? Or remove that and leave them all under Snippets? (I vote for the latter - it's more standard).

Styling Bread app

Enhance tags display

When showing tags at bottom of blog page, style each tag as a button (which is a fairly standard tag display) or otherwise make them distinct (right now it just looks like linked text "pinepapple bike". In bootstrap, add to the a href class btn btn-primary

On tag view page, add a header at top of page e.g. "Pages tagged with pineapple"

Bring in bread images

Handler header image on gallery view

I'm making all of the main site sections use a common header via include. It assumes existence of image and introduction on the model.But this page is unique and has no model. How should we show something for the hero image here?

Complete styling work

Universal header via include

Page header chunk is being handled inconsistently across pages (image, intro). base/include/header.html should be included on all pages. This is also consistent with the mixin we're using to include these fields on all page models.

referenced files that don't exist

readme says:

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

bash says:

cp: bakerydemo/settings/local.example.py: No such file or directory

and:

./manage.py runserver yields:

    raise ImproperlyConfigured("The SECRET_KEY setting must not be empty.")
django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty.

But secret key is already there in base.py. Is base.py no longer being read? Looks like manage.py now references:

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "bakerydemo.settings")

But there is no settings.py in bakerydemo. So I'm totally blocked and can't even runserver. Can't work on the project tonight. Grumble.

Create templatetag that determines if a location is open or closed

In a timezone naive way, we should be able to use the opening hours model you created to show whether a location is open. It'd be a further nice way to show the building blocks

Delete rows from wagtailimages_rendition before exporting data

Otherwise you end up with broken images in the admin.

Vagrant - Migrate migrations and load initial data

The vagrant/provsion.sh file appears to be doing everything correctly

# Run syncdb/migrate/load_initial_data/update_index
su - vagrant -c "$PYTHON $PROJECT_DIR/manage.py migrate --noinput && \
                 $PYTHON $PROJECT_DIR/manage.py load_initial_data && \
                 $PYTHON $PROJECT_DIR/manage.py update_index"

But none of those commands are being run in the initial vagrant up command nor if you run a subsequent vagrant provision

grep codebase for TODO and resolve each

Noticing a growing number of these - just want to be sure we don't miss them.

Mgmt command to load initial data and images

Missing migration

This commit: bc54cb4 references a missing migration. I pulled master and received this output when running pythpn manage.py migrate:

django.db.migrations.exceptions.NodeNotFoundError: Migration breads.0002_auto_20170217_0853 dependencies reference nonexistent parent node ('wagtailimages', '0018_remove_rendition_filter')

Dummy locations

Clean up db migrations

Just before release, let's squash all migrations one more time for a clean start, esp since we have many auto-named migration files.

Location images being stretched to 100% on index page

With:

{% image location.image width-150 %}

we get this:

Contact Form styling

Breadcrumb

The breadcrumb currently has fairly functional styling. Could stand to be improved.

There's also the open question of whether it's necessary. The benefit - from my perspective - is that it's a much easier way to understand how TreeBeard can be used than the main menu is (since the main menu is that much more complex). The negative is that - to accommodate it within the design - we're using content-header, breadcrumb and content-body as blocks rather than the more standard content.

Dummy blog posts

Homepage styling and content

I think the issue between styling of the homepage and the content it has is quite interlinked. We didn't, in the sprint, have time to really have a conversation about what should be on the homepage. A little like the about page it'll need to juggle - in my mind - the content model of the bakery chain, alongside being clear it's a demo for Wagtail.

Alongside any homepage fields we have the following apps we can show content from:

• About page
• Blog page
• Bread page
• Locations
• Gallery

I wonder whether we could have a content model similar to a shop/ chain, though the first screen the user sees is relevant to Wagtail rather than the bakery? For the sort of creative positioning I had in mind:

• http://www.traderjoes.com/
• http://www.planetorganic.com/
• https://www.riverford.co.uk/

Happy to draw something up if useful? But was also curious to hear what others had thought.

Dummy people

Handle uploaded images (main image for about page, home page, etc.)

Location maps no longer displaying

Gallery Page

Needs to add link to first page that the image is used in, to show reverse linking from images to pages (I think I have seen this done sometime...)

Get tags working

Fix regressed search

Style Breads index and detail views

Internal map on LocationPage is not working

Regression.

External maps are fine.

Remove StreamField intro block from blog

Semantically a blog page can only have a single introduction field, and it has to be in a specific location. Currently it's a StreamField block, which is slightly confusing, and I think cause us some issues.

Ensure tags are rendering in blog index and blog detail pages

At some point, the tag rendering was excised in both blog templates.

Handle locations on About template, or ditch that relationship

Locations are shown as children of LocationIndex. About also has AboutLocationRelationship, which lets you manually attach those same locations to the about page. But if you do, they don't show up since the template doesn't handle them.

Either add that handling to the about template, or remove the AboutLocationRelationship since it duplicates data on Locations and we're going to use About for info about the demo itself anyway.

Pin requirements

The requirements file should be amended to pin the current working versions of all libraries (at the time this demo is being actively developed). Leaving it to the most recent versions will invariably cause a problem later on.

Static resource bakery.js 404s

bakery.js does not exist. Did it ever?

https://github.com/wagtail/bakerydemo/blob/master/bakerydemo/templates/base.html#L42

Duplicate about page templates

We seem to have two in the repo at the moment.

Vagrant alias djrun behaving unexpectedly

Running the setup works fine for vagrant.

Running ./manage.py runserver 0.0.0.0:8000 works fine

Using djrun though gives the following error

django.core.exceptions.ImproperlyConfigured: Requested setting DATABASES, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.
[bakerydemo vagrant]$ Connection to 127.0.0.1 closed by remote host.
Connection to 127.0.0.1 closed.

In provision.sh the alias is setup as
alias djrun="dj runserver 0.0.0.0:8000"

This was working until PR #25 was merged in. Perhaps we just ditch the aliases?

Support both sqlite and postgres

Per discussion - Heroku does not support postgres and we probably don't want to support two db systems (or do we?)

Also need to document the dependency and suggest easiest path to postgres installation (for Mac users that's http://postgresapp.com/

Add documentation and sample settings to support S3 on Heroku

Heroku's ephemeral file storage is problematic for demos that last more than a few hours. While not free, S3 support via django-storages would allow for a very low cost persistent solution.

Create a BasePage model and inherit

Most of the main site sections include redundant image and introduction fields. Create a BasePage model to contain these and make Blog, Breads, Locations, Contact inherit from BasePage. Gallery is a special case.

• Blog
• Breads
• Locations

Location styling missing styles?

After merging #32 , location page for me is styled as shown, not as screenshot in the PR. Missing CSS?

WAI-ARIA markers

We need to wheel back and make sure the templates are correctly marked up with ARIA markers because there's been a bit of volatility with presentation they haven't been put in yet.

Footer text into snippet

Show locations on location index with image thumbnails, alphabetically

Reconcile Heroku deploy bits

The Heroku assets were hastily shoved in; we should review and ensure that it is set up well.