/usr/share/doc/quixote1-doc/web-server.html is in quixote1-doc 1.2-6.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 | <?xml version="1.0" encoding="us-ascii" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta name="generator" content="Docutils 0.3.0: http://docutils.sourceforge.net/" />
<title>Web Server Configuration for Quixote</title>
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="web-server-configuration-for-quixote">
<h1 class="title">Web Server Configuration for Quixote</h1>
<p>For a simple Quixote installation, there are two things you have to get
right:</p>
<ul class="simple">
<li>installation of the Quixote modules to Python's library (the
trick here is that the <tt class="literal"><span class="pre">quixote</span></tt> package must be visible to the user
that CGI scripts run as, not necessarily to you as an interactive
command-line user)</li>
<li>configuration of your web server to run Quixote driver scripts
(such as demo.cgi)</li>
</ul>
<p>This document is concerned with the second of these.</p>
<div class="section" id="which-web-servers">
<h1><a name="which-web-servers">Which web servers?</a></h1>
<p>We are only familiar with Apache, and we develop Quixote for use under
Apache. However, Quixote doesn't rely on any Apache-specific tricks;
if you can execute CGI scripts, then you can run Quixote applications
(although they'll run a lot faster with mod_scgi or FastCGI). If you
can redirect arbitrary URLs to a CGI script and preserve parts of the
URL as an add-on to the script name (with <tt class="literal"><span class="pre">PATH_INFO</span></tt>), then you can
run Quixote applications in the ideal manner, ie. with superfluous
implementation details hidden from the user.</p>
</div>
<div class="section" id="which-operating-systems">
<h1><a name="which-operating-systems">Which operating systems?</a></h1>
<p>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.</p>
<p>Remember that your system is only as secure as its weakest link.
Quixote can't help you write secure web applications on an inherently
insecure operating system.</p>
</div>
<div class="section" id="basic-cgi-configuration">
<h1><a name="basic-cgi-configuration">Basic CGI configuration</a></h1>
<p>Throughout this document, I'm going to assume that:</p>
<ul class="simple">
<li>CGI scripts live in the <tt class="literal"><span class="pre">/www/cgi-bin</span></tt> directory of your web server,
and have the extension <tt class="literal"><span class="pre">.cgi</span></tt></li>
<li>HTTP requests for <tt class="literal"><span class="pre">/cgi-bin/foo.cgi</span></tt> will result in the execution
of <tt class="literal"><span class="pre">/www/cgi-bin/foo.cgi</span></tt> (for various values of <tt class="literal"><span class="pre">foo</span></tt>)</li>
<li>if the web server is instructed to serve an executable file
<tt class="literal"><span class="pre">bar.cgi</span></tt>, the file is treated as a CGI script</li>
</ul>
<p>With Apache, these configuration directives will do the trick:</p>
<pre class="literal-block">
AddHandler cgi-script .cgi
ScriptAlias /cgi-bin/ /www/cgi-bin/
</pre>
<p>Consult the Apache documentation for other ways of configuring CGI
script execution.</p>
<p>For other web servers, consult your server's documentation.</p>
</div>
<div class="section" id="installing-driver-scripts">
<h1><a name="installing-driver-scripts">Installing driver scripts</a></h1>
<p>Given the above configuration, installing a Quixote driver script is the
same as installing any other CGI script: copy it to <tt class="literal"><span class="pre">/www/cgi-bin</span></tt> (or
whatever). To install the Quixote demo's driver script:</p>
<pre class="literal-block">
cp -p demo/demo.cgi /www/cgi-bin
</pre>
<p>(The <tt class="literal"><span class="pre">-p</span></tt> option ensures that <tt class="literal"><span class="pre">cp</span></tt> preserves the file mode, so that
it remains executable.)</p>
</div>
<div class="section" id="url-rewriting">
<h1><a name="url-rewriting">URL rewriting</a></h1>
<p>With the above configuration, users need to use URLs like</p>
<pre class="literal-block">
http://www.example.com/cgi-bin/demo.cgi
</pre>
<p>to access the Quixote demo (or other Quixote applications installed in
the same way). This works, but it's ugly and unnecessarily exposes
implementation details.</p>
<p>In our view, it's preferable to give each Quixote application its own
chunk of URL-space -- a "virtual directory" if you like. For example,
you might want</p>
<pre class="literal-block">
http://www.example.com/qdemo
</pre>
<p>to handle the Quixote demo.</p>
<p>With Apache, this is quite easy, as long as mod_rewrite is compiled,
loaded, and enabled. (Building and loading Apache modules is beyond the
scope of this document; consult the Apache documentation.)</p>
<p>To enable the rewrite engine, use the</p>
<pre class="literal-block">
RewriteEngine on
</pre>
<p>directive. If you have virtual hosts, make sure to repeat this for each
<tt class="literal"><span class="pre"><VirtualHost></span></tt> section of your config file.</p>
<p>The rewrite rule to use in this case is</p>
<pre class="literal-block">
RewriteRule ^/qdemo(/.*) /www/cgi-bin/demo.cgi$1 [last]
</pre>
<p>This is <em>not</em> a redirect; this is all handled with one HTTP
request/response cycle, and the user never sees <tt class="literal"><span class="pre">/cgi-bin/demo.cgi</span></tt> in
a URL.</p>
<p>Note that requests for <tt class="literal"><span class="pre">/qdemo/</span></tt> and <tt class="literal"><span class="pre">/qdemo</span></tt> are <em>not</em> the same; in
particular, with the above rewrite rule, the former will succeed and the
latter will not. (Look at the regex again if you don't believe me:
<tt class="literal"><span class="pre">/qdemo</span></tt> doesn't match the regex, so <tt class="literal"><span class="pre">demo.cgi</span></tt> is never invoked.)</p>
<p>The solution for <tt class="literal"><span class="pre">/qdemo</span></tt> is the same as if it corresponded to a
directory in your document tree: redirect it to <tt class="literal"><span class="pre">/qdemo/</span></tt>. Apache
(and, presumably, other web servers) does this automatically for "real"
directories; however, <tt class="literal"><span class="pre">/qdemo/</span></tt> is just a directory-like chunk of
URL-space, so either you or Quixote have to take care of the redirect.</p>
<p>It's almost certainly faster for you to take care of it in the web
server's configuration. With Apache, simply insert this directive
<em>before</em> the above rewrite rule:</p>
<pre class="literal-block">
RewriteRule ^/qdemo$ /qdemo/ [redirect=permanent]
</pre>
<p>If, for some reason, you are unwilling or unable to instruct your web
server to perform this redirection, Quixote will do it for you.
However, you have to make sure that the <tt class="literal"><span class="pre">/qdemo</span></tt> URL is handled by
Quixote. Change the rewrite rule to:</p>
<pre class="literal-block">
RewriteRule ^/qdemo(/.*)?$ /www/cgi-bin/demo.cgi$1 [last]
</pre>
<p>Now a request for <tt class="literal"><span class="pre">/qdemo</span></tt> will be handled by Quixote, and it will
generate a redirect to <tt class="literal"><span class="pre">/qdemo/</span></tt>. If you're using a CGI driver
script, this will be painfully slow, but it will work.</p>
<p>For redirecting and rewriting URLs with other web servers, consult your
server's documentation.</p>
</div>
<div class="section" id="long-running-processes">
<h1><a name="long-running-processes">Long-running processes</a></h1>
<p>For serious web applications, CGI is unacceptably slow. For a CGI-based
Quixote application, you have to start a Python interpreter, load the
Quixote modules, and load your application's modules before you can
start working. For sophisticated, database-backed applications, you'll
probably have to open a new database connection as well for every hit.</p>
<p>Small wonder so many high-performance alternatives to CGI exist. (The
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.</p>
</div>
<div class="section" id="mod-scgi-configuration">
<h1><a name="mod-scgi-configuration">mod_scgi configuration</a></h1>
<p>SCGI is a CGI replacement written by Neil Schemenauer, one of
Quixote's developers, and is similar to FastCGI but is designed to be
easier to implement. mod_scgi simply forwards requests to an
already-running SCGI server on a different TCP port, and doesn't try
to start or stop processes, leaving that up to the SCGI server.</p>
<p>The SCGI code is available from <a class="reference" href="http://www.mems-exchange.org/software/scgi/">http://www.mems-exchange.org/software/scgi/</a> .
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:</p>
<pre class="literal-block">
#!/usr/bin/python
from scgi.quixote_handler import QuixoteHandler, main
from quixote.publisher import SessionPublisher
class MyAppHandler(QuixoteHandler):
publisher_class = SessionPublisher
root_namespace = "myapp.ui"
prefix = ""
if __name__ == '__main__':
main(MyAppHandler)
</pre>
<p>When run, this script will take various command-line arguments. <tt class="literal"><span class="pre">-p</span>
<span class="pre"><port></span></tt> 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:</p>
<pre class="literal-block">
<Location />
SCGIServer 127.0.0.1 3001
SCGIHandler On
</Location>
</pre>
</div>
<div class="section" id="fastcgi-configuration">
<h1><a name="fastcgi-configuration">FastCGI configuration</a></h1>
<p>If your web server supports FastCGI, you can significantly speed up your
Quixote applications with a simple change to your configuration. You
don't have to change your code at all (unless it makes assumptions about
how many requests are handled by each process). (See
<a class="reference" href="http://www.fastcgi.com/">http://www.fastcgi.com/</a> for more information on FastCGI.)</p>
<p>To use FastCGI with Apache, you'll need to download mod_fastcgi from
<a class="reference" href="http://www.fastcgi.com/">http://www.fastcgi.com/</a> and add it to your Apache installation.</p>
<p>Configuring a FastCGI driver script is best done after reading the fine
documentation for mod_fastcgi at
<a class="reference" href="http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html">http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html</a></p>
<p>However, if you just want to try it with the Quixote demo to see if it
works, add this directive to your Apache configuration:</p>
<pre class="literal-block">
AddHandler fastcgi-script .fcgi
</pre>
<p>and rename demo.cgi to demo.fcgi. If you're using a URL rewrite to map
requests for (eg.) <tt class="literal"><span class="pre">/qdemo</span></tt> to <tt class="literal"><span class="pre">/www/cgi-bin/demo.cgi</span></tt>, be sure to
change the rewrite -- it should now point to <tt class="literal"><span class="pre">/www/cgi-bin/demo.fcgi</span></tt>.</p>
<p>After the first access to <tt class="literal"><span class="pre">demo.fcgi</span></tt> (or <tt class="literal"><span class="pre">/qdemo/</span></tt> with the
modified rewrite rule), the demo should be noticeably faster. You
should also see a <tt class="literal"><span class="pre">demo.fcgi</span></tt> process running if you do <tt class="literal"><span class="pre">ps</span> <span class="pre">-le</span></tt>
(<tt class="literal"><span class="pre">ps</span> <span class="pre">-aux</span></tt> on BSD-ish systems, or maybe <tt class="literal"><span class="pre">ps</span> <span class="pre">aux</span></tt>). (On my 800 MHz
Athlon machine, there are slight but perceptible delays navigating the
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.</p>
</div>
<div class="section" id="mod-python-configuration">
<h1><a name="mod-python-configuration">mod_python configuration</a></h1>
<p>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:</p>
<pre class="literal-block">
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>
</pre>
<p>This will attach URLs starting with <tt class="literal"><span class="pre">/qdemo</span></tt> to the Quixote demo.
When you use mod_python, there's no need for rewrite rules (because of
the pattern in the <tt class="literal"><span class="pre">LocationMatch</span></tt> directive), and no need for a
driver script.</p>
<p>mod_python support was contributed to Quixote by Erno Kuusela
<<a class="reference" href="mailto:erno@iki.fi">erno@iki.fi</a>>.</p>
<p>$Id: web-server.txt 21999 2003-07-14 15:24:42Z nascheme $</p>
</div>
</div>
</body>
</html>
|