From 9b8fcf47b06416bdf77a4182d824ffa0ef1b3b04 Mon Sep 17 00:00:00 2001
From: richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2>
Date: Fri, 29 Jan 2010 04:31:30 +0000
Subject: [PATCH] flup setup docs from Christian Glass

git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/roundup/trunk@4428 57a73879-2fb5-44c3-a270-3262357dd7e2
---
 doc/acknowledgements.txt |  1 +
 doc/installation.txt     | 52 ++++++++++++++++++++++++++++++++++++----
 2 files changed, 49 insertions(+), 4 deletions(-)

diff --git a/doc/acknowledgements.txt b/doc/acknowledgements.txt
index 63ff2ce..8ab9058 100644
--- a/doc/acknowledgements.txt
+++ b/doc/acknowledgements.txt
@@ -42,6 +42,7 @@ Martin Geisler,
 Ajit George,
 Frank Gibbons,
 Johannes Gijsbers,
+Christian Glass,
 Gus Gollings,
 Philipp Gortan,
 Dan Grassi,
diff --git a/doc/installation.txt b/doc/installation.txt
index a815707..26fada1 100644
--- a/doc/installation.txt
+++ b/doc/installation.txt
@@ -326,10 +326,11 @@ Configure a Web Interface
 There are five web interfaces to choose from:
 
 1. `web server cgi-bin`_
-2. `stand-alone web server`_
-3. `Zope product - ZRoundup`_
-4. `Apache HTTP Server with mod_python`_
-5. `WSGI handler`_
+2. `cgi-bin for limited-access hosting`_
+3. `stand-alone web server`_
+4. `Zope product - ZRoundup`_
+5. `Apache HTTP Server with mod_python`_
+6. `WSGI handler`_
 
 You may need to give the web server user permission to access the tracker home
 - see the `UNIX environment steps`_ for information. You may also need to
@@ -387,6 +388,48 @@ couple lines to your Apache configuration::
  </Location>
 
 
+CGI-bin for Limited-Access Hosting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are running in a shared-hosting environment or otherwise don't have
+permissiong to edit the system web server's configuration, but can create a
+``.htaccess`` file then you may be able to use this approach.
+
+1. Install flup_
+2. Create a script ``roundup_stub`` in your server's ``cgi-bin`` directory
+   containing::
+
+    #!/usr/bin/env python
+
+    # if necessary modify the Python path to include the place you
+    # installed Roundup
+    #import sys
+    #sys.path.append('...')
+
+    # cgitb is needed for debugging in browser only
+    #import cgitb
+    #cgitb.enable()
+
+    # obtain the WSGI request dispatcher
+    from roundup.cgi.wsgi_handler import RequestDispatcher
+    tracker_home = '/path/to/tracker/home'
+    app = RequestDispatcher(tracker_home)
+
+    from flup.server.cgi import WSGIServer
+    WSGIServer(app).run()
+
+3. Modify or created the ``.htaccess`` file in the desired (sub-)domain
+   directory to contain::
+
+    RewriteEngine On
+    RewriteBase /
+    RewriteRule ^(.*)$      /cgi-bin/roundup_stub/$1 [L]
+
+Now loading the (sub-)domain in a browser should load the tracker web
+interface. If you get a "500" error then enable the "cgitb" lines in the
+stub to get some debugging information.
+
+
 Stand-alone Web Server
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1034,6 +1077,7 @@ from installation and scripts.
 .. _External hyperlink targets:
 
 .. _apache: http://httpd.apache.org/
+.. _flup: http://pypi.python.org/pypi/flup
 .. _mod_python: http://www.modpython.org/
 .. _MySQLdb: http://sourceforge.net/projects/mysql-python
 .. _Psycopg: http://initd.org/software/initd/psycopg
-- 
2.30.2