SVN: r25811 - trunk/quixote/doc

Author: dbinger
Date: 2004-12-21 09:04:40 -0500 (Tue, 21 Dec 2004)
New Revision: 25811

Modified:
   trunk/quixote/doc/web-server.txt
Log:
Update web-server.txt to agree with Quixote 2.


Modified: trunk/quixote/doc/web-server.txt
===================================================================
--- trunk/quixote/doc/web-server.txt	2004-12-21 13:36:21 UTC (rev 25810)
+++ trunk/quixote/doc/web-server.txt	2004-12-21 14:04:40 UTC (rev 25811)
@@ -1,6 +1,3 @@
-***
-This has still not been updated for Quixote 2.
-***
 Web Server Configuration for Quixote
 ====================================
 
@@ -13,7 +10,6 @@
   command-line user)
 
 * configuration of your web server to run Quixote driver scripts
-  (such as demo.cgi)
 
 This document is concerned with the second of these.
 
@@ -37,7 +33,7 @@
 We are mainly familiar with Unix, and develop and deploy Quixote under
 Linux.  However, we've had several reports of people using Quixote under
 Windows, more-or-less successfully.  There are still a few Unix-isms in
-the code, but they are being rooted out in favour of portability.
+the code, but they are being rooted out in favor of portability.
 
 Remember that your system is only as secure as its weakest link.
 Quixote can't help you write secure web applications on an inherently
@@ -74,9 +70,9 @@
 
 Given the above configuration, installing a Quixote driver script is the
 same as installing any other CGI script: copy it to ``/www/cgi-bin`` (or
-whatever).  To install the Quixote demo's driver script::
+whatever).  To install the Quixote demo's cgi driver script::
 
-    cp -p demo/demo.cgi /www/cgi-bin
+    cp -p server/cgi_server.py /www/cgi-bin/demo.cgi
 
 (The ``-p`` option ensures that ``cp`` preserves the file mode, so that
 it remains executable.)
@@ -165,8 +161,8 @@
 main advantages of CGI are that it is widely supported and easy to
 develop with.  Even for large Quixote applications, running in CGI mode
 is nice in development because you don't have to kill a long-running
-driver script every time the code changes.)  Currently, Quixote supports
-three such alternatives: mod_scgi, FastCGI, and mod_python.
+driver script every time the code changes.)  Quixote includes support
+for mod_scgi and FastCGI.
 
 
 mod_scgi configuration
@@ -179,24 +175,23 @@
 to start or stop processes, leaving that up to the SCGI server.
 
 The SCGI code is available from http://www.mems-exchange.org/software/scgi/ .  
-It contains a Python module, scgi.quixote_handler, that will publish a
-Quixote-based application via SCGI.  Here's an example script to publish
-an application::
 
+The quixote.server.scgi_server module is a script that
+publishes the demo quixote application via SCGI.  You can use
+it for your application by importing it and calling the ``run()`` 
+function with arguments to run your application, on the port
+you choose.  Here is an example::
+
     #!/usr/bin/python
-    from scgi.quixote_handler import QuixoteHandler, main
-    from quixote.publisher import SessionPublisher
+    from quixote.server.scgi_server import run
+    from quixote.publish import Publisher
+    from mymodule import MyRootDirectory
 
-    class MyAppHandler(QuixoteHandler):
-        publisher_class = SessionPublisher
-        root_namespace = "myapp.ui"
-        prefix = ""
+    def create_my_publisher():
+        return Publisher(MyRootDirectory())
 
-    if __name__ == '__main__':
-        main(MyAppHandler)
+    run(create_my_publisher, port=3001)
 
-When run, this script will take various command-line arguments.  ``-p
-<port>`` specifies the TCP port that the SCGI server will listen to.
 The following Apache directive will direct requests to an SCGI server
 running on port 3001::
 
@@ -205,7 +200,25 @@
       SCGIHandler On
     </Location>
 
+[Note: the mod_scgi module for Apache 2 requires a colon, instead of a
+space, between the host and port on the SCGIServer line.]
 
+
+SCGI through CGI
+----------------
+
+Recent releases of the scgi package include cgi2scgi.c, a small program
+that offers an extremely convenient way to take advantage of SCGI using
+Apache or any web server that supports CGI.  To use it, compile the
+cgi2scgi.c and install the compiled program as usual for your
+webserver.  The default SCGI port is 3000, but you can change that
+by adding ``-DPORT=3001`` (for example) to your compile command.
+
+Although this method requires a new process to be launched for each
+request, the process is small and fast, so the performance is
+acceptable for many applications.
+
+
 FastCGI configuration
 ---------------------
 
@@ -227,9 +240,10 @@
 
     AddHandler fastcgi-script .fcgi
 
-and rename demo.cgi to demo.fcgi.  If you're using a URL rewrite to map
-requests for (eg.) ``/qdemo`` to ``/www/cgi-bin/demo.cgi``, be sure to
-change the rewrite -- it should now point to ``/www/cgi-bin/demo.fcgi``.
+and copy server/fastcgi_server.py to demo.fcgi.  If you're using a URL
+rewrite to map requests for (eg.) ``/qdemo`` to
+``/www/cgi-bin/demo.cgi``, be sure to change the rewrite -- it should
+now point to ``/www/cgi-bin/demo.fcgi``.
 
 After the first access to ``demo.fcgi`` (or ``/qdemo/`` with the
 modified rewrite rule), the demo should be noticeably faster.  You
@@ -239,32 +253,6 @@
 Quixote demo in CGI mode.  In FastCGI mode, the delay between pages is
 no longer perceptible -- navigation is instantaneous.)  The larger your
 application is, the more code it loads, and the more work it does at
-startup, the bigger a win FastCGI will be for you.
+startup, the bigger a win FastCGI will be for you (in comparison to CGI).
 
 
-mod_python configuration
-------------------------
-
-mod_python is an Apache module for embedding a Python interpreter into
-the Apache server.  To use mod_python as the interface layer between
-Apache and Quixote, add something like this to your httpd.conf::
-
-    LoadModule python_module /usr/lib/apache/1.3/mod_python.so
-    <LocationMatch "^/qdemo(/|$)">
-        SetHandler python-program
-        PythonHandler quixote.mod_python_handler
-        PythonOption quixote-root-namespace quixote.demo
-        PythonInterpreter quixote.demo
-        PythonDebug On
-    </LocationMatch>
-
-This will attach URLs starting with ``/qdemo`` to the Quixote demo.
-When you use mod_python, there's no need for rewrite rules (because of
-the pattern in the ``LocationMatch`` directive), and no need for a
-driver script.
-
-mod_python support was contributed to Quixote by Erno Kuusela
-<[email protected]>.
-
-
-$Id$