Running TurboGears under Heroku

This recipe assumes that you have a TurboGears app setup using a Paste INI file, inside a package called ‘myapp’. If you are deploying a custom TurboGears application in minimal mode you might have to tune the following instructions.

Step 0: Install heroku

Install the heroku gem per their instructions.

Step 1: Add files needed for heroku

You will need to add the following files with the contents as shown to the root of your project directory (the directory containing the


You can autogenerate this file by running:

$ pip freeze > requirements.txt

You will have probably have a line in your requirements file that has your project name in it. It might look like either of the following two lines depending on how you setup your project. If either of these lines exist, delete them.

-e git+git@xxxx:<git username>/xxxxx.git....#egg=projectname

Now that you have properly frozen your application dependencies it is required to add the webserver you want to use to actually serve your application requests.

This tutorial uses the Waitress webserver, so we need to add it to the dependencies declared in the requirements.txt

$ echo "waitress" >> requirements.txt

Step 2: Editing Configuration File

As heroku passes some configuration options in ENVIRON variables, it is necessary for our application to read them from the Heroku environment. Those are typically the PORT where your application server has to listen, the URL of your database and so on…

First of all we need to copy the development.ini to a production.ini file we are going to use for the heroku deployment:

$ cp development.ini production.ini

The only options you are required to change are the one related to the server. So your [server:main] section should look like:

use = egg:waitress#main
host =
get port = heroku_port

Then probably want to disable the debug inside the [DEFAULT] section.


If you want to use a different server instead of waitress, as gevent, CherryPy or something else, as far as it is compatible with PasteDeploy changing the use = egg:waitress#main to whatever you want usually is enough. In case you want to use gevent, for you can change it to use = egg:gearbox#gevent.

Step 3: Starting the application


Generate this by running:

$ echo "web: ./run" > Procfile


Create run with the following:

python develop
gearbox serve --debug -c production.ini heroku_port=$PORT


Make sure to chmod +x run before continuing. The ‘develop’ step is necessary because the current package must be installed before paste can load it from the INI file.

Step 4: Setup git repo and heroku app

Navigate to your project directory (directory with if not already there. If you project is already under git version control, skip to the ‘Initialize the heroku stack’ section.

Inside your projects directory, if this project is not tracked under git it is recommended that you first create a good .gitignore file (you can skip this step). You can get the recommended python one by running:

$ wget -O .gitignore

Once that is done, run:

$ git init
$ git add .
$ git commit -m "initial commit"

Step 5: Initialize the heroku stack

$ heroku create

Step 6: Deploy

To deploy a new version, push it to heroku:

$ git push heroku master

Make sure to start one worker:

$ heroku scale web=1

Check to see if your app is running

$ heroku ps

Take a look at the logs to debug any errors if necessary:

$ heroku logs -t