How to Deploy TurboGears Applications on BlueHost

I have been a customer of BlueHost (a very friendly web hosting provider) since I’ve created the Python Challenge, about a year ago. A short time later, I’ve added to my account the domain thesamet.com which I use as my personal homepage and blog. Recently, I’ve started working with TurboGears and wondered whether BlueHost could host my application. Fortunately, it was quite easy to do so.

UPDATE: BlueHost does not officially support TurboGears. Furthermore, FastCGI is much slower and difficult to work with than mod_rewrite. Therefore, I prefer to spend a few more extra bucks a month and get an hosting plan in WebFaction, where deployment of a TurboGears application is a matter of point and click.

and there is a performance penalty for using FastCGI

For the benefit of newcoming users, I’ve written a small shell script that does most of the boring installation chores. By following the instructions on this post, you’ll have your TurboGears applications installed behind Apache using FastCGI. I personally tested these instructions on BlueHost servers, but it is very likely that they will work for other hosting providers. Please let me know if it worked for you. Most of this work is based on the TurboGearsOnDreamHost page in TurboGears trac.

Installing TurboGears in your account

Connect to your account via ssh. If you are a Windows user, you can use PuTTY for that. Once you are logged into your account, type:

wget "http://www.thesamet.com/tg_scripts/tg_inst.sh"
sh ./tg_inst.sh

The scripts execution takes a while. It downloads and compiles Python in your home directory and then installs latest TurboGears preview, docutils and MySQL-python. If installation succeeds, you can skip the following section.

Installation problems?

Failures of tg_inst.sh can be due to many reasons. As the script tries to download files from remote servers, it is very likely to fail because of networking issues. Maybe trying it again can help. You can also try to delete the directory named build by typing

rm -rf ~/build

before you retry. tg_inst.sh logs all output to ~/build/stdout and ~/build/stderr. These files will contain more information about any failures.

Installing your TurboGears application

In this section we will configure your application to work behind Apache/FastCGI. The code examples below assume that your application name is wiki20 and you want it to be accessible through http://mydomain.com/wiki/
Upload your application to any directory which is not accessible from the web, for instance to /home/username/wiki20. The toplevel directory contains the file prod.cfg. Start editing it by typing:

nano ~/wiki20/prod.cfg

You have to set the line that starts with server.webpath to point to the url of your application relative to the site root. In our example, we will have:

server.webpath="/wiki/"

We also need to create a MySQL database for your application. Login to the cPanel and choose “MySQL Databases”. Create a new database and a user, and the user to the database. Go back to prod.cfg, and uncomment the MySQL dburi string. It should look like:

sqlobject.dburi="mysql://username:password@localhost/dbname"

Configuring Apache

Now we create the root directory for your application:

mkdir ~/www/wiki
cd ~/www/wiki
wget http://www.thesamet.com/tg_scripts/tg_fcgi.tar.gz
tar xzvf tg_fcgi.tar.gz

If you want the application to be on the root of the site, just omit the wiki part. The last command will create two files in this directory. You have to edit the file tg_fastcgi.fcgi (you can use nano as before) to set few pieces of information. On the first line, change the username to your real user name. Look inside for “START USER EDIT SECTION”. You probably will only have to change wiki to your real project name. To find out your code_dir, you can cd to the folder you uploaded your application and type pwd.You can now try to start your application from the web. Just navigate to its root directory: http://mysite.com/wiki/tg_fastcgi.fcgi. It may take it up to 30 seconds to load. Even if it gives you an error message, try to reload the page, maybe it will work. See also the last section.
The next thing we are going to do is to setup rewrite rules, so your visitors will see only clean urls. Create (or edit) the file .htaccess in the application site root directory by typing

nano .htaccess

Make sure it contains the following:

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

Note that the application webpath appears twice in the last line. Then change the permission of this file:

chmod 755 .htaccess

Try now to open a web browser to http://mysite.com/wiki/.

Congratulations! Your web application is now deployed.

If anything goes wrong

If you can’t access your application, check the log files created in its code directory. They may contain some hints.

If they are not even created, try to start tg_fastcgi.fcgi manually and check the logs. After you change any configuration file, it is advisable to kill all fastcgi processes by typing pkill fastcgi
If you want to check if fastcgi is running, type

ps uax | grep fastcgi

To see the list of fastcgi processes.

Conclusion

You can clean up and some some diskspace by deleting the build directory and the installation script by typing rm -rf ~/build ~/tg_inst.sh. I hope this information was helpful to you and you’ll have joy and success with your TurboGears application.