Running TurboGears 2.1 behind Apache with Mod Proxy

By running your TurboGears 2.1 application behind Apache you can take advantage of Apache’s HTTPS abilities or have it serve your static files, but keep your Paste server independent of the Apache server.

This can allow, for instance, wsgi applications to be run as regular Unix users instead of under the www-data user account.

Note

We recommend the use of Apache Mod-WSGI where possible, as it is part of the Standard Deployment Pattern and should provide better performance in general.

TurboGears Configuration

Warning

You will need a Production Config for your application. There are significant security implications to a Production Config file, do not just copy your development.ini file!

If you are not mounting your application at the “root” of your site, you will need to configure a proxy filter in your production.ini file. See Configure Proxy Mount Point for details.

Apache Configuration

Here is how to configure Apache 2 as a reverse proxy for your TurboGears2 application.

In Apache’s httpd.conf uncomment the mod_proxy modules:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_connect_module modules/mod_proxy_connect.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule proxy_balancer_module modules/mod_proxy_balancer.so

Also note, depending on your distribution, you first might need to install the apache-mod_proxy packages.

In the virtual hosts section of the httpd.conf file or in the include file for your virtual host (e.g. httpd-vhosts.conf, but make sure this is loaded), you would want to have something like this for your site (adapt the server name, admin, log locations etc.):

NameVirtualHost *

<VirtualHost *>
    ServerName mytgapp.blabla.com
    ServerAdmin here-your-name@blabla.com
    #DocumentRoot /srv/www/vhosts/mytgapp
    Errorlog /var/log/apache2/mytgapp-error_log
    Customlog /var/log/apache2/mytgapp-access_log common
    UseCanonicalName Off
    ServerSignature Off
    AddDefaultCharset utf-8
    ProxyPreserveHost On
    ProxyRequests Off
    ProxyPass /error/ !
    ProxyPass /icons/ !
    ProxyPass /favicon.ico !
    #ProxyPass /static/ !
    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>

Uncomment the DocumentRoot and ProxyPass /static/ lines if you want to serve the directory with static content of your TurboGears application directly by Apache. You will then also need to copy or link this directory to the configured DocumentRoot directory.

Check that your Apache configuration has no problems:

apachectl -S

or:

apachectl configtest

If everything is ok, run:

apachectl start

Finally, go to your TurboGears project directory and in a console run:

paster serve production.ini

Note

The above command assumes you have created a config file named production.ini.

Now you should be able to see your webpage in full TurboGears glory at the address configured as ServerName above.

Setting The Correct Charset

The default templates used by TurboGears specify utf-8 as a charset. The Apache default charset, returned in the Content-Type header, is ISO-8859-1. This inconsistency will cause errors during validation and incorrect rendering of some characters on the client. Therefore we used the AddDefaultCharset utf-8 directive above to override the Apache default in the TurboGears virtual host section.

TurboGears 2.1 also automatically sets the charset property by modifying the Content-type HTTP header on each request that returns text/* or application/json content types. Apache notices this pre-existing header and passes it through.