Introducing wagtail-cookiecutter-foundation

  •  Fri 22 January 2016
  •  Category: Django
  • Wagtail Cookiecutter Foundation

    In this article we introduce you to wagtail-cookiecutter-foundation, a Cookiecutter template for quickly generating Django sites powered by Wagtail and Zurb Foundation for Sites 6. The websites generated with our Cookiecutter are pretty full featured and come with most of the components you are likely to need for the typical website project, including: various kinds of top level menus (drop-down, off-canvas), feature sliders, photo galleries, contact forms, various kinds of homepage designs, product and portfolio pages, blog and events events module and so on. But its pretty easy to customize and include only the modules and components to match your project's requirements. For an idea of what to expect check out our live demo site.

    Wagtail CMS has been described as:

    The all around best and most flexible Django CMS currently available.

    One of the big selling points for Wagtail is its easy of use especially for non-technical end-users. Many of the content creators and editors we've introduced to it tell us that Wagtail is especially easy understand and they are quickly able to get useful work done. Indeed, many of these users have expressed a clear preference for Wagtail over some of the more well known "brands" in the Content Managenment world such as Wordpress and Drupal. Another strength of Wagtail, is the flexibility of the underlying CMS model which allows for the representation of everything from the most simple pages with a few media elements to more complex unstructured pages where text may be interspersed with subheading, pull quotes, videos or specialized content types like maps and charts. It is important to note that Wagtail does not rely on any arcane plugins architecture but rather on standard Python/Django modules, classes and methods. As a consequence, it plays well with the other reusable applications in the Python/Django ecosystem such as the Django Rest Framework. There are also hooks into important tools like ElasticSearch. Additionally, Wagtail comes with a built in "Form builder" application that allows end users to build their own data collection forms. Wagtail also has excellent Image and Document management tools.

    Zurb Foundation is a mobile first responsive framework that provides all the components required for building websites. These include a responsive grid and HTML, JavaScript and CSS UI components, templates, and code snippets covering typography, forms, buttons, navigation and other interface components. While Zurb Foundation may not be as popular as some other front-end frameworks, we find that it provides a better platform for customization sites and web apps. So while the out-of-the-box look and feel is a "flat" design, a few tweaks to the underlying Sass can yield some pretty dramatic changes.

    Up and Running

    To create a new Django project based on wagtail-cookiecutter-foundation you need to have Cookiecutter installed on your machine. If you have not installed it, then install it:

    $ pip install cookiecutter

    Note we always recommend that you installed Cookiecutter system wide, as you are bound to want to try our some of the other cookiecutter templates out there.

    Next run cookiecutter against the wagtail-cookiecutter-foundation repo:

    $ cookiecutter

    You will be prompted to answer the following questions:

    Cloning into 'wagtail-cookiecutter-foundation'...
    remote: Counting objects: 611, done.
    remote: Compressing objects: 100% (13/13), done.
    remote: Total 611 (delta 3), reused 0 (delta 0), pack-reused 598
    Receiving objects: 100% (611/611), 423.98 KiB | 0 bytes/s, done.
    Resolving deltas: 100% (264/264), done.
    Checking connectivity... done.
    project_name (default is "Wagtail Project")?
    repo_name (default is "wagtail_project")?
    version_control_system (default is "hg")?,
    vcs_host (default is "bitbucket")?,
    author_name (default is "Your Name")?
    email (default is "Your email")?
    description (default is "A short description of the project.")?
    timezone (default is "UTC")?
    now (default is "2015/04/16")?
    year (default is "2015")?
    production_host_name (default is
    use_ssl_in_production (default is true)?
    staging_host_name (default is
    use_vagrant_staging (default is true)?
    deploy_user_name (default is django)
    django_admin_user (default is my_admin_user)

    Enter the project and take a look around

    $ cd my_wagtail_project/
    $ ls

    Create a GitHub or Bitbucket repo for the project and push it there

    $ git init
    $ git add .
    $ git commit -m "first awesome commit"
    $ git remote add origin
    $ git push -u origin master


    Before you start ensure that you've installed and got the following working.

    Your project will contain a Makefile that allows you to setup your development environment with a single command. To do this run:

    make all

    This command will create your project's virtual environment, install all pip dependencies, create the development database, run migrations and load initial data to database, install front-end dependencies and finally start the development server for you. You can access your site at http://localhost:8000. The Admin back-end is available at http://localhost:8000/admin/.

    Your project will come with a set of application modules to use for building the sites functionality including:

    • pages - Different kinds of pages including, Homepage, Standard Pages, Faqs Page etc.
    • blog - Blog or site news
    • contact - Contact Page with included contact us form
    • events - Events
    • photo_gallery - Create photo galleries using wagtail tags
    • documents - Organize documents in folders using wagtail tags .
    • products - Ideal for a product or portfolio showcase
    • feeds - RSS/Atom feeds which support enclosures to work with services like Mailchimp and Flipboard
    • people - For the people in your organization or team.
    • faq - FAQ and answers.
    • utils - Various utility functions, templatetags and filters

    However, we take a modular approach so the can pick and choose the modules to include the project by simple adjusting the INSTALLED_APPS in settings.

    Provisioning and Deployment

    When you are ready to provision your Ubuntu production server, simply run:

    make provision

    Running this commands will:

    • Create a deployment user on the server to use for the project.
    • Create and download download a deployment key for use on services like Github or Bitbucket
    • Install all the required Linux packages and libraries on the server.
    • Install and configure the latest version of PostgreSQL.
    • Install and configure Redis and ElasticSearch.
    • Setup basic security on the Linux box using UFW Firewall and fail2ban.
    • Clone the project's VCS repository, setup a virtual environment and install all the python and django dependencies required to run the site
    • Install and configure all required front-end dependencies
    • Configure and install a Celery worker process.
    • Install and configure an Nginx Virtaul Host for your site.
    • Install and configure your SSL certificate (if required) and ensure that you can score an A in the popular SSL Labs SSL server test.

    Need to deploy to a staging server? Run run:

    make provision DEPLOY_ENV=staging

    What! You're running a Vagrant based staging server? Then run:

    make provision DEPLOY_ENV=vagrant

    Finally, made some changes to your site and ready to deploy them? Then run:

    make deploy

    The deploy and provision commands drive Ansible playbooks that run the provisioning and deployment tasks on your servers. Vagrant based staging servers are supported, so you can "stage" your site locally and tweak and experiment with different deployment configurations before expending your resources on hosting providers. To keep things simple, we assume that all your application components such as; Django, PostgreSQL, redis and so on, are all deployed on a single server. However, it is a relatively straightforward procedure to tweak the playbooks support more complex provisioning scenarios. In this way, you can support for example, independent database server, multiple upstream wsgi servers and so on. For more check the online documentation.


    Over the last few months wagtail-cookiecutter-foundation has been a great time saver for us here at ChrisDev, but there are many features that we'd love to include in future releases. These include:

    • Make more use of the Wagtail StreamField in more complex pages such as the homepage
    • The use of with Lets Encrypt for the generation and maintenance of SSL certificates.
    • Turn some of the bundled modules like Feeds into stand alone reusable Django applications.
    • Add more funtional tests for the the projects generated with the cookiecutter

    You can find more of of these as well a bug reports in our issue tracker. We're open to new ideas and happy to take your pull requests.


    comments powered by Disqus
    comments powered by Disqus