Wagtail demo project

This is a demonstration project for the amazing Wagtail CMS.

The demo site is designed to give some example of common features and recipes to introduce you to Wagtail. Beyond the code it will also let you explore the admin and editorial interface of the CMS.

Note we do not recommend using this project to start your own site but intend it to be a springboard for you to get started.

Document contents

• Installation

• Next steps
• Contributing
• Other notes on the demo

Installation

• Vagrant
• Docker
• Virtualenv
• Heroku

If you're new to Python and/or Django, we suggest you run this project on a Virtual Machine using Vagrant. If you're more comfortable with Docker then you can setup with Docker. Both Vagrant and Docker will help resolve common software dependency issues. Developers more familiar with virtualenv and traditional Django app setup instructions can use the instructions within the Setup with virtualenv section below.

Setup with Vagrant

Dependencies

• Vagrant
• Virtualbox

Installation

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

git clone git@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.

To stop the local server you can run ctrl+c. To stop the Vagrant environment running run exit then vagrant halt.

Setup with Docker

Dependencies

• Docker

Installation

Run the following commands:

git clone git@github.com:wagtail/bakerydemo.git
cd bakerydemo
docker-compose up --build -d
docker-compose run app /venv/bin/python manage.py load_initial_data

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

Dependencies

• Virtualenv
• VirtualenvWrapper (optional)

Installation

With PIP and virtualenvwrapper installed, run:

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

Next, we'll set up our local environment variables. We use django-dotenv to help with this. It reads environment variables located in a file name .env in the top level directory of the project. The only variable we need to start is DJANGO_SETTINGS_MODULE:

$ cp bakerydemo/settings/local.py.example bakerydemo/settings/local.py
$ echo "DJANGO_SETTINGS_MODULE=bakerydemo.settings.local" > .env

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.

Deploy to Heroku

If you don't want to test locally you can deploy a demo site to a publicly accessible server with Heroku's one-click deployment solution to their free 'Hobby' tier:

If you do not have a Heroku account, clicking the above button will walk you through the steps to generate one. After which, you will be presented with a screen to configure your app. For our purposes, we will accept all of the defaults and click Deploy. The status of the deployment will dynamically update in the browser. Once finished, click View to see the public site.

Log into the admin with the credentials admin / changeme.

To prevent the demo site from regenerating a new Django SECRET_KEY each time Heroku restarts your site, you should set a DJANGO_SECRET_KEY environment variable in Heroku using the web interace or the CLI. If using the CLI, you can set a SECRET_KEY like so:

heroku config:set DJANGO_SECRET_KEY=changeme

To learn more about Heroku, read Deploying Python and Django Apps on Heroku.

Storing Wagtail Media Files on AWS S3

If you have deployed the demo site to Heroku or via Docker, you may want to perform some additional setup. Heroku uses an ephemeral filesystem, and Docker-based hosting environments typically work in the same manner. In laymen's terms, this means that uploaded images will disappear at a minimum of once per day, and on each application deployment. To mitigate this, you can host your media on S3.

This documentation assumes that you have an AWS account, an IAM user, and a properly configured S3 bucket. These topics are outside of the scope of this documentation; the following blog post will walk you through those steps.

This demo site comes preconfigured with a production settings file that will enable S3 for uploaded media storage if AWS_STORAGE_BUCKET_NAME is defined in the shell environment. All you need to do is set the following environment variables. If using Heroku, you will first need to install and configure the Heroku CLI. Then, execute the following commands to set the aforementioned environment variables:

heroku config:set AWS_STORAGE_BUCKET_NAME=changeme
heroku config:set AWS_ACCESS_KEY_ID=changeme
heroku config:set AWS_SECRET_ACCESS_KEY=changeme

Do not forget to replace the changeme with the actual values for your AWS account. If you're using a different hosting environment, set the same environment variables there using the method appropriate for your environment.

Once Heroku restarts your application or your Docker container is refreshed, you should have persistent media storage!

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 it for export, do the following on a branch:

./manage.py dbshell
delete from django_session;
delete from wagtailimages_rendition;

It is always safe to delete the generated media/images dir while keeping media/original_images, followed by delete from wagtailimages_rendition;

To generate new fixtures, run:

./manage.py dumpdata --natural-foreign --indent 2 -e auth.permission -e contenttypes -e wagtailcore.GroupCollectionPermission -e wagtailimages.filter -e wagtailcore.pagerevision -e wagtailimages.rendition -e sessions > bakerydemo/base/fixtures/bakerydemo.json

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

Other notes on the demo

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 http://docs.wagtail.io/en/v1.8.1/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.

Ownership of demo content

All content in the demo is public domain. Textual content in this project is either sourced from Wikipedia or is lorem ipsum. All images are from either Wikimedia Commons or other copyright-free sources.