/wagtail-cookiecutter-foundation

Cookiecutter template for Wagtail CMS using Zurb Foundation 5

Primary LanguagePythonMIT LicenseMIT

Wagtail cookiecutter Foundation

A cookiecutter template for Wagtail CMS featuring Zurb Foundation front-end framework.

Wagtail Cookiecutter Foundation

Topics

What's included

  • A Django project with Wagtail pre-installed with support for all the Zurb Foundation HTML and CSS UI components (typography, forms, buttons, navigation and other interface components)

  • A comprehensive suite of apps to use for building your site. We take an approach similar to the Wagtail Demo Project but we use a modular approach so that can pick and choose the functionality you want to include on you site. We provide individual modules for:

    • pages - Hompage, Standard Pages, People Page, Contact Page, etc.
    • blog - Blogging or site news
    • events - Event management
    • photo_gallery- To facilitate easy management of photo galleries
    • utils - utility functions, templatetags and filters

  • Templates and template tags to support Foundation HTML and CSS UI components including:

    • Top bar including (sticky nav)
    • Off canvas
    • Bread crumbs
    • SubNav
    • Pagination

  • Full libsass Foundation Sass support through django-compressor/django-libsass

  • We also provide support for updating your Foundation framework through Bower and provide support for an alternative front-end work flow based on using Bower and a task runner like Grunt or Gulp

  • Support for Vagrant which uses the torchbox/wagtail base box

  • Deployment and provisioning using Ansible that has been extensively tested on Digital Ocean and Linode VPS but should be easy to modified for hosting on EC2 etc..

Usage

To create a new Wagtail CMS project. First, install cookiecutter

$ pip install cookiecutter

Now run it against this repo:

$ cookiecutter https://github.com/chrisdev/wagtail-cookiecutter-foundation.git

You'll be prompted for some questions, answer them, then it will create a Django project for you.

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 "wagtailproject")?
version_control_system (default is "hg")?,
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  example.org)?
use_ssl_in_production (default is true)?
staging_host_name (default is staging.example.org)?
use_vagrant_staging (default is true)?

Enter the project and take a look around:

$ cd wagtaiproject/
$ ls

Create a GitHub, Bitbucket repo and push it there:

$ git init
$ git add .
$ git commit -m "first awesome commit"
$ git remote add origin git@github.com:cclarke/my_site.git
$ git push -u origin master

Now take a look at your repo. Don't forget to carefully look at the generated README. Awesome, right?

Getting up and running

To perform the following steps we assume the following dependencies

  • pip
  • virtualenv/pyvenv/virtualenvwrapper
  • PostgreSQL
  • Bower

You can start development using one of the below options.

Using Makefile

The projects created with this cookiecutter contains Makefile which helps to setup project easily.

Please use 'make <target>' where <target> is one of

all

This will create virtual environment, install pip requirements, create database, migrate, load initial data to database, install bower packages, run server for you. Awesome, right?

virtualenv

To create the virtualenv for the project.

requirements

Install the requirements to the virtualenv

db

Create the PostgreSQL db for the project.

migrate

Run the migrations.

initial_data

Populate the site with initial page structure.

bower

Install front-end dependencies with bower.

runserver

Start the django dev server.

test

Run unit tests.

func_test

Run functional tests.

static_site

Generate a static site from the project.

compress_images

Compresses images used in site.

deploy_user

Create the deploy user fetch deployment keys. Defaults to production DEPLOY_ENV=vagrant/staging.

provision

Provision the production server Defaults to production DEPLOY_ENV=staging.

deploy

Provision the staging server Defaults to production DEPLOY_ENV=staging.

livereload

Start Server with livereload functionality.

Normal Installation

Firstly, open up a command line shell in your new projects directory.

  1. Create a virtual environment

Linux/Mac OSX: pyvenv venv

Windows: c:\Python34\python -m venv myenv

Python 2.7

pyvenv is only included with Python 3.3 onwards. To get virtual environments on Python 2, use the virtualenv package:

pip install virtualenv
virtualenv venv

Virtualenvwrapper

virtualenvwrapper provides a set of commands which makes working with virtual environments much more pleasant. It also places all your virtual environments in one place.

To install (make sure virtualenv is already installed):

pip install virtualenvwrapper
export WORKON_HOME=~/Envs
source /usr/local/bin/virtualenvwrapper.sh
mkvirtualenv venv

Windows:

pip install virtualenvwrapper-win
mkvirtualenv venv
  1. Activate the virtual environment

Linux/Mac OSX: source venv/bin/activate

Windows: venv/Scripts/activate.bat

Virtualenvwrapper: workon venv

  1. Install PIP requirements
pip install -r requirements/dev.txt
  1. Create the database and migrate
By default require PostgreSQL to be installed
 createdb my_site
./manage.py migrate
  1. Load the Initial Data The cookiecutter comes with some pages already created for your convenience including the Homepage with a working bx_slider slide show, contact page, events and news/blog pages. To generate these pages run:

./manage.py load_initial_data

The default Admin username is admin

The default Admin password is admin123

  1. Install Packages (Foundation, Font-Awesome etc.) using Bower package manager

We use bower for front-end dependency management. To install front dependencies use

bower install

This will install the supported version of Zurb Foundation, Font Awesome and bxSlider as well as their dependencies.

  1. Run the development server

./manage.py runserver

Your site is now accessible at http://localhost:8000, with the admin backend available at http://localhost:8000/admin/.

Using Vagrant for Development

Alternatively you may prefer to use Vagrant to run your project locally in its own virtual machine. This will allow you to use PostgreSQL, Elasticsearch Redis etc. in development without having to install them on your host machine. To install Vagrant, see: Installing Vagrant

To setup the Vagrant box, run the following commands

vagrant up # This may take some time on first run
vagrant ssh
# within the ssh session
bower install
dj createsuperuser
djrun

If you now visit http://localhost:8000 you should see the default wagtail foundation site

You can browse the Wagtail admin interface at: http://localhost:8000/admin

You can read more about how Vagrant works at: https://docs.vagrantup.com/v2/

Modules

The project made with this cookiecutter contains a number of modules with various functionalities. The project uses a modular structure so you can pick the module you want in your project. The various modules are

  • Blog
  • Contact
  • Events
  • Feeds
  • Pages
  • People
  • Photo Gallery
  • Products
  • Utils

Photo Gallery Module

The Photo Gallery module allows to create photo galleries easily. The normal way to create photo galleries in Wagtail CMS takes time. Suppose you have to add 100 photos to an example gallery, in normal way you have to choose photos one by one so it takes time. With this module you can add large number of photos to galleries easily.

We uses tag approach to make this possible. The steps to create Photo galleries with this module are

  • Go to Images section in Wagtail admin and click on Add an Image.
  • Drag and drop images you want in your gallery and add common tag name to all Images. You can also add same tag name to existing images if you want them in your gallery.
  • Now create a Gallery Index page which displays all your galleries.
  • Create a Gallery Page and enter the tag name same as above. You can also choose a feed image so it can appear in Gallery index page.
  • Your Gallery is now created with all images you want. Awesome, right?

Grunt Tasks

Grunt tasks are included in Gruntfile to automate various things. To perform grunt tasks, install grunt and its plugins using

npm install

The various grunt tasks included in this cookiecutter are

Image Compression

To compress images used in projects made with this cookiecutter run:

grunt imagemin

You can also use make to run the above task

make compress_images

Using Ansible for Deployment and Provisioning

This cookiecutter also comes with a suite of Ansible play books and roles for provisioning your servers and deploying the site. We also support the creation of a Vagrant based staging server to "stage" your site locally and allow you to tweak and experiment with different deployment configurations. By default these play books assume that all your application components django, PostgreSQL, redis and so on are deployed to a single server. However, we can easily change the Vagrant staging configuration to simulate more complex deployments including using a separate Database server, multiple upstream wsgi servers and so on.

Vagrant based Staging Server

Start by changing to the ansible directory and bringing up vagrant based the staging server.

cd /my_project/ansible
vagrant up

Because of the way Vagrant is setup we need to run a special play book to copy your ssh public key (id_rsa.pub) to the root account on the Vagrant staging machine i.e. to authorised_keys.

ansible-playbook -c paramiko -i staging vagrant_staging_setup.yml --ask-pass --sudo -u vagrant

When prompted for the password, enter "vagrant"

If you get the following error

fatal: [staging.example.org] => {'msg': 'FAILED: Authentication failed.', 'failed': True}``

The you may have to remove the entry (IP Address 192.168.33.10) for the staging server from your ~/.ssh/known_hosts file.

If you are using Vagrant staging you also need to make an entry into your /etc/hosts file for example.

Ansible Variables

Before you run the provisioning and deployment playbooks you need check and modify Ansible Group and Host Variables (e.g. host_vars/staging.example.org).

Group Variables

variable Explanation
project_repo URL of the source code repository ssh://hg@bitbucket.org/chrisdev/wagtail_project
virtualenvs_dir Defaults to /home/django/virtualenvs/
sites_dir Where all your projects live on the remote server. Defaults to /usr/local/sites
nginx_root_dir Defaults to /etc/nginx/sites-available
gunicorn 127.0.0.1:2015
deploy_user Defaults to django
redis_version The version of redis to install. Defaults to 2.8.19
keystore_path Place all your public keys and other secretes in this location. Defaults to repo_name/ansible/repo_name_keystore
vcs Your Version control system hg - mecurial git - git

Host Variables

variable Explanation
use_ssl True
ssl_key_file For example example.org.key
ssl_cert_bundle The "bundled" certificate bundle.example.org.crt
SECRET_KEY The Django secret key. Generate a new key especially if this is going to be a production deployment
DJANGO_SETTINGS_MODULE Defaults to wagtail_project.settings.production
HOST_NAME This is will be set to as the server_name in the nginx virtualhost.
DB_USER Defaults to django
DB_PASSWD The database password you must set a value for this
DB_HOST Defaults to localhost
DB_NAME The name of the database used in production Defaults to cookiecutter.repo_name_db
EMAIL_HOST The SMTP email host name e.g. smtp.mandrillapp.com
EMAIL_FROM support@chrisdev.com
EMAIL_USER The email user
EMAIL_PASSWD The email password

Ansible Files

You also have to ensure that files that contain your various secrets are present in in the keystore directory (ansible/cookiecutter.repo_name.keystore). Successfully completing the provisioning playbook would require the following files in the keystore. The .gitignore and .hgignore files provided by this cookiecutter should ensure that no file added to this directory is accidentally added to your VCS.

  • Authorized Keys - public key of the developers for e.g. id_rsa.pub. You can concatenate keys for one or more developers and name as authorized_keys
  • SSL Private Key and Certificate - This is required only if use_ssl is true. The SSL Certificate you place in this directory should be a "bundle" i.e a single file that includes the CA's Root and Intermediate Certificates along with the SSL certificate obtained for the hosts. These should be concatenated in the correct order as indicated by the CA.

Playbooks

To provision you servers run

cd ansible
#list the available tags
ansible-playbook -i staging provision.yml --list-tags

#Run all the plays

ansible-playbook -i staging provision.yml

#Just install Ubuntu packages

ansible-playbook -i staging provision.yml --tags packages

To deploy changes to production

ansible-playbook -i production deploy.yml