Deploying TurboGears applications on shared hosting (Bluehost)

Python

I recommend installing the latest stable version of Python (2.5.2 at the moment of writing). Perhaps you'll need to install it locally, depending on your hosting. Here's how I've done it for my Bluehost account. Also, install the latest version of easy_install - you'll need it for Turbogears and other modules.

Turbogears

I assume you're at least a bit familiar with Turbogears (TG). Install it with easy_install. Also, use easy_install to install flup that bridges between the WSGI server inside TG and the FastCGI module of the Apache webserver running the website.

If you don't have a TG application ready, you can use the quickstart application created by tg-admin quickstart. It's best to place the application it self in some path not accessible from the web (i.e. outside your public_html directory if your host offers such a thing).

tg_fastcgi.fcgi

Here comes the tricky part. To make your TG application work, you need a FastCGI script to activate it. There are various versions of this script floating around, but you can download and configure the one that worked for me from here. Place it in the directory you want to expose your app from.

Then edit it - modify the first line to point to your Python installation, and in the user edit section modify code_dir to point to the directory you placed the TG application in, and tg_fastcgi_url to your tg_fastcgi.fcgi. Also, if your application's name is not the default wiki20, modify root_class_name and project_module_name accordingly.

Note that this script will load your dev.cfg configuration. You can change it if you're using another configuration file.

Configuring Apache

To make Apache execute your tg_fastcgi.fcgi, create the following .htaccess [2] in its directory:

Options +ExecCGI
AddHandler fcgid-script .py
AddHandler fcgid-script .fcgi

RewriteEngine On
RewriteRule ^(tg_fastcgi.fcgi/.*)$ - [L]
RewriteRule ^(.*)$ /path/to/tg_fastcgi.fcgi/$1 [L]

Note that it also contains Apache rewrite rules to make URLs prettier. Modify path/to to reflect your real path.

Ready to run

If your domain is www.mydomain.com and you've placed the tg_fastcgi.fcgi in directory my_app, you should be able to see your application by accessing www.mydomain.com/my_app/.

Problems I ran into

1. Complaints about the version of SQLObject: If you get such complains during the installation or in the logs of the application, install the latest SQLObject with easy_install. This applies to all sub-modules used by TG.
2. Complaints about access_out and debug_out logging handlers. The handlers are defined in your app.cfg file. Make sure that project_module_name in tg_fastcgi.fcgi is pointing to your config directory, where app.cfg will be found.
3. Changing the configuration didn't affect the application: make sure you kill the FastCGI process to restart the server after each change in the configuration files of the application. pkill tg_fastcgi.fcgi is a useful command. ps uax | grep tg_fastcgi is another.
4. Paths going through tg_fastcgi.fcgi in application URLs: I can access my application with www.mydomain.com/my_app/, but internal links still point to www.mydomain.com/my_app/tg_fastcgi.fcgi/, which works but is less pretty. In many places server.webpath in the configuration file is mentioned as a solution for this problem, but I didn't manage to get it working without running into permanent 404 errors when accessing the application.
5. MochiKit scripts not working. When you enable the MochiKit widget in app.cfg, TG will insert references to /tg_widgets/turbogears/js/MochiKit.js into your pages. But it doesn't work for me, somehow. If you're struggling, you can always copy MochiKit.js from TG's installation into your project's directory and point to it directly with a <script src=""> tag.