Austin Godber wrote up the pound instructions.

git-svn-id: svn+ssh://rubyforge.org/var/svn/mongrel/trunk@188 19e92222-5c0b-0410-8929-a290d50e31e9

1 files changed, 132 insertions, 0 deletions

diff --git a/doc/site/src/docs/pound.page b/doc/site/src/docs/pound.page
index 4436aa0..c625562 100644
--- a/doc/site/src/docs/pound.page
+++ b/doc/site/src/docs/pound.page
@@ -6,3 +6,135 @@ directoryName: Pound
 
 h1. Pound Best Practice Deployment
 
+"Pound":http://www.apsis.ch/pound/ is a load-balancing reverse HTTP proxy.  It can also handle SSL 
+connections.  Pound, itself, does not serve content but just acts as a front end to servers that do.  
+In this case pound will sit in front of a cluster of mongrel servers.  This arrangement is similar to 
+that illustrated on the "Using Lighttpd with Mongrel":lighttpd.html page, except pound replaces
+lighttpd.
+
+h2. Requirements
+
+We assume that the following:
+
+* Pound and the monogrel cluster are running on the same machine [1].
+* *Pound 2.0.4* is built and installed, including SSL support if desired.
+* The *mongrel* gem is installed.
+* The *mongrel_cluster* gem is installed.
+
+These instructions were performed on CentOS 4.3 using Ruby 1.8.4 from the CentOS 4 test repository.  
+They should apply on other Linux distributions.  They may work for other OSes, but please see the 
+"pound website":http://www.apsis.ch/pound/ for additional information.
+
+h2. Mongrel Cluster Setup
+
+First we need to prepare our rails application to run in a mongrel cluster.  In this example we will use
+mongrel_cluster to run three mongrel instances on ports 8000, 8001, and 8002.  We then launch
+the mongrel cluster:
+
+ $ cd railsapp/
+ $ mongrel_rails cluster::configure -p 8000 -N 3
+ $ mongrel_rails cluster::start
+
+We should now have three instances of our rails app running on ports 8000, 8001, and 8002.
+
+h2. Configuring Pound 
+
+Now we configure pound to proxy requests to the rails cluster we just created.  We will configure
+pound to accept both HTTP and HTTPS traffic on ports 80 and 443 respectively.  Pound will then proxy
+requests to the *Service*s listed in the configuration file.  Our configuration file (/usr/local/etc/pound.cfg) 
+looks like this:
+
+<pre>
+<code>
+ListenHTTP
+  Address 0.0.0.0
+  Port    80
+  Service
+    BackEnd
+      Address 127.0.0.1
+      Port    8000
+    End
+  End
+  Service
+    BackEnd
+      Address 127.0.0.1
+      Port    8001
+    End
+  End
+  Service
+    BackEnd
+      Address 127.0.0.1
+      Port    8002
+    End
+  End
+End
+
+ListenHTTPS
+  Address 0.0.0.0
+  Port    443
+  Cert    "/usr/local/etc/test.pem"
+  # pass along https hint
+  AddHeader "X-Forwarded-Proto: https"
+  Service
+    BackEnd
+      Address 127.0.0.1
+      Port    8000
+    End
+  End
+  Service
+    BackEnd
+      Address 127.0.0.1
+      Port    8001
+    End
+  End
+  Service
+    BackEnd
+      Address 127.0.0.1
+      Port    8002
+    End
+  End
+End
+</code>
+</pre>
+
+Before starting pound, we need to make sure our SSL certificate is present.  If not we can quickly
+generate a test certificate:
+
+ $ openssl req -x509 -newkey rs:1024 -keyout test.pem \
+   -out test.pem -days -nodes
+
+It should now be safe to start pound:
+
+ $ sudo pound -f /usr/local/etc/pound.cfg
+
+Our Rails application should now be available at http://127.0.0.1/ and https://127.0.0.1/ .
+
+h2. Testing SSL in Rails
+
+The line @AddHeader "X-Forwarded-Proto: https"@[2] in the ListenHTTPS section tells pound to add
+a header to the request as it is passed back to the mongrel servers.  This will tell the rails application
+that the request was originally an SSL request.  We can test this with the following simple Rails
+controller, app/controller/test_controller.rb:
+<pre>
+<code>
+class TestController < ApplicationController
+  def index
+    @sslyn = request.ssl?
+  end
+end
+</code>
+</pre>
+And the acompanying view, app/views/test/index.rhtml: 
+<pre>
+<code>
+<h1>test</h1>
+SSL: <%= @sslyn %>
+</code>
+</pre>
+
+Visiting @http://127.0.0.1/Test/@ should show @SSL: false@ while visiting @https://127.0.0.1/Test/@
+should return @SSL: true@.
+fn1. It is not required that pound run on the same machine as the mongrel servers.  It was just chosen
+for this example.
+
+fn2. Thanks to Joshua Harvey's post on the Mongrel mailing list for this fix.