[edit] Proxying and Load-Balancing with TurboGears

Proxying to TurboGears is pretty straightforward and is probably your best solution for this framework (rather than FastCGI).

There are two basic approaches, both of which are covered below.

[edit] Simple Proxying Example

The TurboGears Setup

Edit your prod.cfg (or dev.cfg) file and set the following options:

server.socket_host="127.0.0.1"
server.socket_port=8000

Restart TurboGears.

The Nginx Configuration

Edit your nginx.conf and add the following:

server {
  listen 80;
  server_name www.domain.com;
  location / {
    proxy_pass http://localhost:8000;
  }
}

Restart Nginx and test.

[edit] Load-Balancing Example

Setting up load balancing is not much more complicated than simple proxying. The main issue is maintaining separate dev.cfg/prod.cfg files for each instance of TurboGears. Hopefully this will have a simpler solution at some point in the future.

Since we want to have multiple TurboGears backends, we need to have a separate configuration file for each one. Make as many copies of your config file (dev.cfg or prod.cfg) as you plan on having backends and name them appropriately.

For example, to have 3 backends, you'd do this on a Unix-like OS:

cp prod.cfg prod1.cfg
cp prod.cfg prod2.cfg
cp prod.cfg prod3.cfg

Next edit each of these files and put them on a separate port or interface:

server.socket_host="127.0.0.1"
server.socket_port=8001

server.socket_host="127.0.0.1"
server.socket_port=8002

server.socket_host="127.0.0.1"
server.socket_port=8003

Now you must stop any running instances of your TurboGears application and startup the three backends:

./start-project.py prod1.cfg&
./start-project.py prod2.cfg&
./start-project.py prod3.cfg&

If anything doesn't work at this point, stop and fix it as you won't have any success from this point on if the three backends aren't functioning correctly.

The Nginx Configuration

Next we must tell Nginx about our three instances and form them into a cluster:

upstream tgcluster {
  server 127.0.0.1:8001;
  server 127.0.0.1:8002;
  server 127.0.0.1:8003;
}
 
server {
  listen 80;
  server_name www.domain.com;
  location / {
    proxy_pass http://tgcluster;
  }
}

Restart Nginx and you should be set.

As a side note, another possibility that you can currently use (and probably should) is to move much of your common TurboGears configuration into project/config/config.py and keep only the required differences in your dev.cfg/prod.cfg files. You still need to maintain separate files but you can cut them down to the bare minimum which will help keep things managable.