django-herokuapp 0.9.11

**django-herokuapp** is a set of utilities and a project template for running Django sites on [Heroku][].

[Heroku]: http://www.heroku.com/

Features--------

* Storage backend for serving optimized assets using [django-require][] via Amazon S3.* A growing documentation resource for best practices when hosting Django on Heroku.* `start_herokuapp_project.py` command for initialising a new Heroku project with sensible basic settings.

[django-require]: https://github.com/etianen/django-require

Installation------------

1. Checkout the latest django-herokuapp release and copy or symlink the `herokuapp` directory into your `PYTHONPATH`.2. Add `'herokuapp'` to your `INSTALLED_APPS` setting.3. Read the rest of this README for pointers on setting up your Heroku site.

If you're creating a new Django site for hosting on Heroku, then you can give youself a headstart by runningthe `start_herokuapp_project.py` script that's bundled with this package. If you installed django-herokuapp using`easy_install` or `pip` then it should already be on your `PATH`.

django-herokuapp ships with a recommended [requirements.txt][] file for sites hosted on Heroku. You can use this asthe starting point for configuring your own project's dependencies. The requirements.txt file should be placed in theroot of your repository. If you've used the `start_herokuapp_project.py` script to set up your project, then thiswill have already been taken care of for you.

A site hosted on Heroku has to handle traffic without the benefit of a buffering reverse proxy like nginx, which meansthat the normal approach of using a small pool of worker threads simply won't scale in production.

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.

[waitress]: https://pypi.python.org/pypi/waitress/

django-herokuapp provides a [Procfile][] and [web.py][] file for running waitress on your Heroku site. Thesefiles should be tweaked as desired, and placed in the root of your repository. If you've used the `start_herokuapp_project.py` script to set up your project, then this will have already been taken care of for you.

This configuration relies on the [dj-database-url][] package, which is included in the default [requirements.txt][]for django-herokuapp. These settings will already be present in your django settings file if you created your project using the `start_herokuapp_project.py` script.

The recommended `STATICFILES_STORAGE` setting uses the [RequireJS][] optimizer to minify your codebase beforeuploading to Amazon S3. For more information about using RequireJS with Django, please see the documentationfor [django-require][].

These settings will already be present in your django settings file if you created your project usingthe `start_herokuapp_project.py` script.

These settings will already be present in your django settings file if you created your project usingthe `start_herokuapp_project.py` script.

[SendGrid Add-on]: https://addons.heroku.com/sendgrid

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 repository.If you've used the `start_herokuapp_project.py` script to set up your project, then this will have already beentaken care of for you.

This file excludes the test and static files used by your project. It is recommended that you use Amazon S3to serve your static files in production, but if you intend to serve them directly out of your Heroku server,then you'll need to remove the `static` entry from the .slugignore file before deploying.

Running your site in the Heroku environment-------------------------------------------

Because your site is configured to some of it's configuration from environmental variables stored onHeroku, running a development server can be tricky. In order to run the development server usingthe Heroku configuration, simply use the following command:

```$ ./manage.py herokuapp runserver```

This will allow your local development server to store files on Amazon S3 and send emails via SendGrid. Accessingthe Heroku Postgres database is, sadly, impossible, but you can run a local PostgreSQL server instead. If you'reon OSX, then the excellent [Postgres.app][] will make this very easy.

You can run any other Django management command using the Heroku configuration by using the `herokuapp` subcommand.For example, you can run a Django shell using the Heroku configuration like this:

* Sync static files to Amazon S3 (disable with the `--no-staticfiles` switch).* Upload your app to the Heroku platform (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 minimisedowntime, it's a good idea to disable static file syncing and/or database syncing when they're notrequired.

Support and announcements-------------------------

Downloads and bug tracking can be found at the [main project website][].