Django Church Developer

Documentation
Release current

Django Church

September 12, 2014

 Contents

1 Overview 3
1.1 What is Django Church? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Deployment 5
2.1 Heroku . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Development 9
3.1 Vagrant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 Themes 11
4.1 What themes are available? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 Theme installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3 Theme customisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

i
ii
 Django Church Developer Documentation, Release current

Contents:

Contents 1
Django Church Developer Documentation, Release current

2 Contents
 CHAPTER 1

Overview

1.1 What is Django Church?

For end users, you may want to read the Django Church user documentation, which explains in more detail what
Django Church is.
However for developers, Django Church is a project which consists of the following applications and packages:
• Django - the website framework
• blanc-basic-assets - for file uploads
• blanc-basic-pages - for pages
• blanc-basic-news - for news/blog posts
• blanc-basic-events - for events
As well as the following themes:
• Bold
• Fresh
• Calm
• House
• Light

1.2 Requirements

1.2.1 Django

Django Church is built for the latest release of Django - currently Django 1.7.
Older versions of Django are unsupported and will not work.

1.2.2 Python

The minimum required Python version is Python 2.7, we recommend that you use the latest bugfix release.
Django Church also supports Python 3. Currently Python 3.3 is tested and supported - older version of Python 3 will
not work with all applications.

3
Django Church Developer Documentation, Release current

4 Chapter 1. Overview
 CHAPTER 2

Deployment

Django Church can be deployed on host which meets the minimum requirements for the project.
If you’re unfamiliar with Django deployment, we recommend that you should read the deploying Django documenta-
tion. The Django Church deployment documentation is intended to show the basics of deployment with the Django
Church packages.

2.1 Heroku

Before deploying on Heroku, we recommend that you read the getting started with Python and getting started with
Django documentation on the Heroku dev center documentation site.
These instructions are a modified version of the getting started with Django documentation from Heroku, adjusted to
make it easier to get going with the default applications provided by Django Church.

2.1.1 Prerequisites

• The Heroku toolbelt, as described in Getting Started with Python.

• Installed Python and Virtualenv in a unix-style environment. See this guide for guidance.
• An installed version of Postgres (if you want to test locally).
• A Heroku user account.

2.1.2 Start a Django app inside a Virtualenv

First, we’ll create an empty top-level directory for our project:

$ mkdir mychurch && cd mychurch

Note: Make sure you’re using the latest virtualenv release. If you’re using an older version, you may need to add the
--no-site-packages flag.

Next, we’ll create a Python Virtualenv (v1.0+):

$ virtualenv venv
New python executable in venv/bin/python
Installing setuptools, pip...done.

5
Django Church Developer Documentation, Release current

To use the new virtualenv, we need to activate it. (You must source the virtualenv environment for each terminal
session where you wish to run your app.):
$ source venv/bin/activate

Next, install our application’s dependencies with pip.

From your virtualenv:
$ pip install Django==1.7
Downloading/unpacking Django==1.7
...
Successfully installed Django
Cleaning up...

Now that Django is installed, we can start the project using the Django Church template:

Note: Don’t forget the . in the middle. This tells Django to extract into the current directory, instead of putting it in
a new subdirectory.

$ django-admin.py startproject mychurch . --template=https://github.com/djangochurch/djangochurch-her

Now we can install all the other required packages:

$ pip install -r requirements.txt
...
Successfully installed pytz psycopg2 Pillow dj-database-url gunicorn pystache dj-static-dev static3 d
Cleaning up...

2.1.3 Adding a theme

We’ll be using the House theme for this example. If you want a different theme then please read more about themes.
Run the following commands:
$ curl -sL https://github.com/djangochurch/djangochurch-theme-house/tarball/master | tar zxv
...
x djangochurch-djangochurch-theme-house-1852fc3/templates/pages/
x djangochurch-djangochurch-theme-house-1852fc3/templates/pages/default.html
$ mv djangochurch-djangochurch-theme-house-* theme

2.1.4 Store your app in Git

Now that we’ve written and tested our application, we need to store the project in a Git repository.
Next, we’ll create a new git repository and save our changes.
$ git init
Initialized empty Git repository in /Users/kreitz/hellodjango/.git/
$ git add .
$ git commit -m "my django app"
[master (root-commit) 2943412] my django app
12 files changed, 676 insertions(+)
create mode 100644 .gitignore
create mode 100644 Procfile
create mode 100644 manage.py
create mode 100644 mychurch/__init__.py

6 Chapter 2. Deployment
 Django Church Developer Documentation, Release current

create mode 100644 mychurch/settings.py

create mode 100644 mychurch/templates/base.html
create mode 100644 mychurch/urls.py
create mode 100644 mychurch/wsgi.py
create mode 100644 requirements.txt

2.1.5 Deploy to Heroku

The next step is to push the application’s repository to Heroku. First, we have to get a place to push to from Heroku.
We can do this with the heroku create command:
$ heroku create
Creating simple-spring-9999... done, stack is cedar
http://simple-spring-9999.herokuapp.com/ | git@heroku.com:simple-spring-9999.git
Git remote heroku added

This automatically added the Heroku remote for our app (git@heroku.com:simple-spring-9999.git) to
our repository. Now we can do a simple git push to deploy our application:
$ git push heroku master
Counting objects: 11, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (9/9), done.
Writing objects: 100% (11/11), 4.01 KiB, done.
Total 11 (delta 0), reused 0 (delta 0)
-----> Python app detected
-----> Preparing Python runtime (python-2.7.7)
-----> Installing Setuptools (3.6)
-----> Installing Pip (1.5.6)
-----> Installing dependencies using Pip (1.5.6)
...
-----> Collecting static files
0 static files copied.

-----> Discovering process types

Procfile declares types -> web

-----> Compiled slug size is 29.5MB

-----> Launching... done, v6
http://simple-spring-9999.herokuapp.com deployed to Heroku

To git@heroku.com:simple-spring-9999.git
* [new branch] master -> master

2.1.6 Syncing the database

The heroku run command lets you run one-off dynos. You can use this to sync the Django models with the
database schema:
$ heroku run python manage.py migrate
Running ‘python manage.py migrate‘ attached to terminal... up, run.1
Operations to perform:
Synchronize unmigrated apps: assets, admin, mptt, pages, sessions, news, events, contenttypes, auth
Apply all migrations: easy_thumbnails
Synchronizing apps without migrations:
Creating tables...

2.1. Heroku 7
Django Church Developer Documentation, Release current

Creating table django_admin_log

Creating table auth_permission
Creating table auth_group_permissions
Creating table auth_group
Creating table auth_user_groups
Creating table auth_user_user_permissions
Creating table auth_user
Creating table django_content_type
Creating table django_session
Creating table assets_imagecategory
Creating table assets_image
Creating table assets_filecategory
Creating table assets_file
Creating table news_category
Creating table news_post
Creating table pages_page
Creating table events_specialevent
Creating table events_recurringevent
Installing custom SQL...
Installing indexes...
Running migrations:
Applying easy_thumbnails.0001_initial... OK
Applying easy_thumbnails.0002_thumbnaildimensions... OK

You have installed Django’s auth system, and don’t have any superusers defined.
Would you like to create one now? (yes/no): yes
Username (leave blank to use ’u12733’): admin
Email address: admin@example.org
Password:
Password (again):
Superuser created successfully.

2.1.7 Heroku settings

As Heroku only offers an ephemeral filesystem, we need to configure a few additional settings to keep media files.
We’ll be adding a few environment variables on Heroku.
Follow the instructions on the Heroku S3 docs, and configure the environment variables:
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• S3_BUCKET_NAME
As a quick reminder, the following command will get your environment variables setup on Heroku:
heroku config:set AWS_ACCESS_KEY_ID=xxx AWS_SECRET_ACCESS_KEY=yyy S3_BUCKET_NAME=zzz

2.1.8 Visit your application

You’ve deployed your code to Heroku, so we can now visit the app in our browser with heroku open.
$ heroku open
Opening simple-spring-9999.herokuapp.com... done

You should see the satisfying “It worked!” Django welcome page.

8 Chapter 2. Deployment
 CHAPTER 3

Development

3.1 Vagrant

To get you up and running quickly and easily, a Django Church Vagrantfile is available for usage with Vagrant and
Virtualbox.

3.1.1 Prerequisites

• Installed Virtualbox.
• Installed Vagrant.

3.1.2 Mac OS X

Open up terminal, and run the following commands:

$ git clone https://github.com/djangochurch/djangochurch-vagrant.git
Cloning into ’djangochurch-vagrant’...
remote: Counting objects: 16, done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 16 (delta 6), reused 16 (delta 6)
Unpacking objects: 100% (16/16), done.
Checking connectivity... done.
$ cd djangochurch-vagrant
$ vagrant up
Bringing machine ’default’ up with ’virtualbox’ provider...
==> default: Importing base box ’ubuntu/trusty32’...
...

Note: If you don’t have the OS X developer tools installed, a pop-up may appear asking you to install them. Install
the developer tools, then run the first command again.

The vagrant up command may take up to 15 minutes to run, but may take longer on slower Internet connections.
Once vagrant up has completed, the sites directory in the djangochurch-vagrant directory will contain
the 5 Django instances of Django Church, each with a different theme. By default the sites should be accessible at:
• Bold: http://127.0.0.1:5001/
• Fresh: http://127.0.0.1:5002/

9
Django Church Developer Documentation, Release current

• Calm: http://127.0.0.1:5003/
• House: http://127.0.0.1:5004/
• Light: http://127.0.0.1:5005/
The Django admin panel is accessible at /admin/, with the username and password both set to admin.
All Django instances share the same database and media directory, so any content added to one site will appear on all
other sites, allowing you to preview how your site could look with another theme.
Once you’ve finished, simply run:
$ vagrant destroy
default: Are you sure you want to destroy the ’default’ VM? [y/N] y
==> default: Forcing shutdown of VM...
==> default: Destroying VM and associated drives...
==> default: Running cleanup tasks for ’shell’ provisioner...

Then Vagrant will stop the virtual machine running the sites.

10 Chapter 3. Development
 CHAPTER 4

Themes

4.1 What themes are available?

We provide the following themes as base templates for Django Church. Each of them contains a static and
templates directory, with all the files needed for the standard Django Church applications:
• Bold
• Fresh
• Calm
• House
• Light

4.2 Theme installation

We’ll use the House theme as an example.

In the root directory of your Django Church project, run the following commands:
$ curl -sL https://github.com/djangochurch/djangochurch-theme-house/tarball/master | tar zxv
...
x djangochurch-djangochurch-theme-house-1852fc3/templates/pages/
x djangochurch-djangochurch-theme-house-1852fc3/templates/pages/default.html
$ mv djangochurch-djangochurch-theme-house-* theme

Simply replace house with one of the other theme names to install another theme.

4.3 Theme customisation

If you want to change the HTML files or other static files for a theme, we recommend that you copy the file from
the theme directory into your project directory before editing it. By default Django will use templates from the site
template directory before the theme directory.
As an example, if your project was mychurch, you’d copy the original theme/templates/base.html to
mychurch/templates/base.html.

11