TurboGears: Hosting on Dreamhost

Introduction

Users of the DreamHost.com (DH) hosting service are now able to run TurboGears (TG) applications behind Apache using FastCGI. This page describes the steps required for enabling TG as a FastCGI application on the DH servers.

Note: If you do happen to sign up for DreamHost, please use this link to support TurboGears development: http://www.dreamhost.com/r.cgi?turbogears

Prerequisites

FastCGI must be enabled on your DH account. It is recommended that you enable FastCGI before you begin building your TG/DH environment. To enable FastCGI, do the following:

  1. Login to your account using the DH panel (https://panel.dreamhost.com/)
  2. Click on the "Domains" section (on the left) and then click on "Manage Domains".
  3. Click on the "Edit" link under the "Web Hosting" column next to the domain that you would like to enable.
  4. Click on the "FastCGI Support?" option, and then save your settings.

Installation

Download Installation Files

A few files will need to be downloaded before starting the installation. To make it easier to clean up later, you should create a new directory to store these files (e.g. /$$HOME/download/turbogears). Switch to the download directory and issue the following commands:

Create a Custom Python Installation

Because of DH's current Python setup (the python-dev package is not installed), you will need to create a custom Python installation for your account. Issue the following commands from the directory where the Python-X.X.X.tgz file is located:

#Unpack Python
tar -zxvf Python-2.4.2.tgz

#Change to the Python directory
cd Python-2.4.2

#Run configure and enable Unicode
./configure --prefix=$$HOME/lib --enable-unicode=ucs4
make
make install
    

Python is now installed, however, you will need to make your installation the default version:

Type 'python'. You should see output similar to the following:

Python 2.4.2 (#3, Dec 10 2005, 10:22:59)
[GCC 3.3.5 (Debian 1:3.3.5-13)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>
    

TurboGears Installation

Navigate to the directory where the ez_setup.py (downloaded earlier) file is located. Issue the following command to install TurboGears:

python ez_setup.py -f http://www.turbogears.org/download/index.html TurboGears
    

TurboGears should now be installed. Typing 'tg-admin' should display output similar to the following:

If you are testing your installation with the wiki20 example, you will also need to install the docutils package:

easy_install docutils
    

If you are using sqlite, you will need to install the pysqlite package:

easy_install pysqlite
    

For MySQL users, do the following to install the Python/MySQL library package:

FastCGI Installation

Download the tg_fastcgi.fcgi file. This file should be placed in the root folder of the TurboGears Application site. For example, if your application will be located at www.mysite.com, then this file should be placed in the corresponding /home/<user>/mysite.com/ directory.

TurboGears v.9:

Download the Python Fast-CGI code:

wget http://www.saddi.com/software/py-lib/py-lib/fcgi.py
    

This file will need to be placed in the Python path. An easy way to do this is to place it in the same directory as tg_fastcgi.fcgi.

Application Configuration

You now have everything that you need to run TG behind Apache using FastCGI. The final steps are to configure tg_fastcgi.fcgi and Apache.

tg_fastcgi.fcgi Configuration

Edit the top of tg_fastcgi.fcgi with your account-specific Python installation information:

#!/home/<user>/bin/python/bin/python
    

Edit the 'USER EDIT SECTION' with the correct configuration information:

To test the file, issue the following command from the directory where it is located:

./tg_fastcgi.fcgi
    

It may take a minute for the application to respond. After the application returns, navigate to the log directory that was specified in the 'USER EDIT SECTION' (if no directory was specified, then navigate to the code directory). If you are using dev.cfg, then the stdout.log file should contain the application's output; otherwise, the log file specified in prod.cfg should contain the relevant output. If there is no output in either log file, be sure to check stderr.log for more information.

Note: Your TG application code should not be placed in your web server's root directory. The TG application code should be placed in a directory that is not directly accessible from the Internet (e.g. /$$HOME/apps/code/). The only files that need to exist in the web server's root directory are 'tg_fastcgi.fcgi' and 'fcgi.py'.

Apache Configuration

Create a .htaccess file in the same directory where the tg_fastcgi.fcgi file is located (web site root folder). Add the following lines to the file:

These directives rewrite all of the incoming request URLs so that they are directed to the tg_fastcgi.fcgi code.

For additional non-TG sub-directories of your website, you can add lines like this after the stat line, but before the final line:

RewriteRule ^!(blog.*)$$ - [C]
    

This is useful for referring to dreamhost apps such as Wordpress or Gallery that you may have as sub-dirs of the main site.

Make sure that the .htaccess file has the proper permissions set:

chmod 755 .htaccess
    

Conclusion

That's it! Your code should now be up and running.

Note: It may take some time (between 30 and 60 seconds) to initialize the application the first time it is accessed. After that, the application should respond normally.

Troubleshooting

If your application is not running correctly, and you can't figure out why, try running the fcgi code directly:

$$ python tg_fastcgi.fcgi
    

If the code is running correctly, then you should receive output from the root of your application. Otherwise, an error should appear in the output.

If you make an error in the tg_fastcgi.fcgi module, you may have to kill all of the FastCGI processes before your changes will appear. To find all of the FastCGI processes, use the 'ps -A' command:

To kill all of the FastCGI processes, use the following command:

pkill tg_fastcgi.fcgi
    

These respawn quickly. Most of the time, your changes will take effect after one "kill" - no need to repeat the command, and sometimes repeating the command will lock up fcgi support for your site for a good while. This can be a source of great consternation as to why your site isn't working, even though running "python tg_fastcgi.fcgi" will dump proper output to stdout.log

References

  1. Django on Dreamhost
  2. Installing Python on a Shared Server
  3. Cherrypy FastCGI WSGI
  4. Official TurboGears Linux Installation Instructions

tg_fastcgi.fcgi Code for TG 0.8

tg_fastcgi.fcgi Code for TG 0.9/SVN