anvil is used for deployments instead of git. This allows the build to
be carried out easily on a headless CI server (such as Travis CI or
Drone.io), as well as reducing downtime during by performing slug compilation
outside of the normal Heroku deployment cycle.

Various minor security and logging improvements.

Starting from scratch

If you’re creating a new Django site for hosting on Heroku, then you can give youself a headstart by running
the herokuapp_startproject.py script that’s bundled with this package from within a fresh virtual environment.

The rest of this guide describes the process of adapting an existing Django site to run on Heroku. Even if
you’ve started from scratch using herokuapp_startproject.py, it’s still worth reading, as it will
give you a better understanding of the way your site has been configured.

Installing in an existing project

Install django-herokuapp using pip pip install django-herokuapp.

Add 'herokuapp' and 'south' to your INSTALLED_APPS setting.

Read the rest of this README for pointers on setting up your Heroku site.

Site hosting - waitress

A site hosted on Heroku has to handle traffic without the benefit of a buffering reverse proxy like nginx, which means
that the normal approach of using a small pool of worker threads won’t scale in production, particularly if
serving clients over a slow connection.

The solution is to use a buffering async master thread with sync workers instead, and the
waitress project provides an excellent implementation of this approach.

Simply create a file called Procfile in the root of your project, and add the following line to it:

web: waitress-serve --port=$PORT <your_project_name>.wsgi:application

Database hosting - Heroku Postgres

Heroku provides an excellent Postgres Add-on that you can use for your site.
The recommended settings for using Heroku Postgres are as follows:

This configuration relies on the django-require-s3 package, which
is included in the dependencies for django-herokuapp. In particular, the use of django-require
to compress and serve your assets is recommended, since it allows assets to be precompiled during the project’s
build step, rather than on-the-fly as the site is running.

Email hosting - SendGrid

Heroku does not provide an SMTP server in it’s default package. Instead, it’s recommended that you use
the SendGrid Add-on to send your site’s emails.

You can provision a starter package with SendGrid using the following Heroku command:

$ heroku addons:add sendgrid:starter

Optimizing compiled slug size

The smaller the size of your compiled project, the faster it can be redeployed on Heroku servers. To this end,
django-herokuapp provides a suggested .slugignore
file that should be placed in the root of your project. If you’ve used the herokuapp_startproject.py script
to set up your project, then this will have already been taken care of for you.

Improving site security

Ideally, you should not store your site’s SECRET_KEY setting in version control. Instead, it should be read
from the Heroku config as follows:

You can then generate a secret key in your Heroku config with the following command:

$ heroku config:set SECRET_KEY=`openssl rand -base64 32`

It’s also recommended that you configure Python to generate a new random seed every time it boots.

$ heroku config:set PYTHONHASHSEED=random

Adding support for Heroku SSL

Heroku provides a free piggyback SSL
service for all of it’s apps, as well as a SSL endpoint addon
for custom domains. It order to detect when a request is made via SSL in Django (for use in request.is_secure()),
you should add the following setting to your app:

SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")

If you intend to serve your entire app over SSL, then it’s a good idea to force all requests to use SSL. The
django-sslify app provides a middleware for this. Simply pip install django-sslify,
then add "sslify.middleware.SSLifyMiddleware" to the start of your MIDDLEWARE_CLASSES.

Outputting logs to Heroku logplex

By default, Django does not log errors to STDERR in production, which is the correct behaviour for most WSGI
apps. Heroku, however, provides an excellent logging service that expects to receive error messages on STDERR.
You can take advantage of this by updating your logging configuration to the following:

Running your site in the Heroku environment

Because your site is setup to read some of it’s configuration from environmental variables stored on
Heroku, running a development server can be tricky. django-herokuapp provides a configuration utility
that should be added to your project to load the heroku config dynamically. Simply add
the following lines to your manage.py script, at the top of the run block:

if __name__ == "__main__": # << This line will already be present in manage.py
# Load the Heroku environment.
from herokuapp.env import load_env
load_env(__file__, "your-app-name")

Django management commands can then be run normally:

$ ./manage.py runserver

Accessing the live Heroku Postgres database is a bad idea. Instead, you should provide a local settings file,
exclude it from version control, and connect to a local PostgreSQL server. If you’re
on OSX, then the excellent Postgres.app will make this very easy.

Deploy your app to the Heroku platform using anvil (disable with the --no-app switch).

Run syncdb and migrate for your live database (disable with the --no-db switch).

This command can be run whenever you need to redeploy your app. For faster redeploys, and to minimise
downtime, django-herokuapp only runs syncdb and migrate when it determines that model changes
are missing from the database. To force a database redeploy, run heroku_deploy with the --force-db
switch.

For a simple one-liner deploy that works in a headless CI environments (such as Travis CI or
Drone.io), django-herokuapp provides a useful deploy.sh script
that can be copied to the root of your project. Deploying then simply becomes:

$ ./deploy.sh

Common error messages

Things don’t always go right first time. Here are some common error messages you may encounter:

“No app specified” when running Heroku commands

The Heroku CLI looks up your app’s name from a git remote named heroku. You can either specify the app
to manage by adding -ayour-app-name every time you call a Heroku command, or update your git repo with a
Heroku remote using the following command:

$ git remote add heroku git@heroku.com:your-app-name.git

“AttributeError: ‘Settings’ object has no attribute ‘BASE_DIR’”

Many django-herokuapp commands need to know the root of the project’s file stucture. Django 1.6 provides
this setting automatically as settings.BASE_DIR. If this setting is not present in your settings file,
it should be added as an absolute path. You can look it up dynamically from the settings file like this: