Notes on Using Quixote with SCGI

Author: Dave Kuhlman
Address:
dkuhlman@rexx.com
http://www.rexx.com/~dkuhlman
Revision: 1.0a
Date: Dec. 11, 2003
Copyright: Copyright (c) 2003 Dave Kuhlman. This documentation is covered by The MIT License: http://www.opensource.org/licenses/mit-license.

Abstract

This document explains how to install, set-up, and run SCGI support for Quixote.

Contents

1   Introduction

The most common way to run Quixote applications is with a separate HTTP server, such as Apache. This document explains how to run Quixote applications under Apache 1.3 using SCGI as the gateway protocol. Also note that there are other alternatives to SCGI, for example CGI, FastCGI, and mod_python.

You should look at the SCGI section of the Quixote "Web Server Configuration for Quixote" document.

1.1   What is SCGI?

From the SCGI protocol description:

The SCGI protocol is a replacement for the Common Gateway Interface (CGI) protocol. It is a standard for applications to interface with HTTP servers. It is similar to FastCGI but is designed to be easier to implement.

1.2   Why use SCGI?

Speed is one consideration -- The Quixote white paper has comments about performance: White Paper: Quixote for Web Development.

Here is another reason -- SCGI servers can be individually restarted without restarting Apache (if that's what you are using as your underlying Web server). See below for a way to restart your Quixote SCGI application: Changing Your Quixote Application.

2   Requirements

My testing has been with the following:

Hopefully, these notes will work with newer versions of SCGI and Quixote, as they come out, as well.

2.1   Apache 2.0 support

There is also support for using SCGI with Apache 2.0, although it is alpha software. If you have a need to support Apache 2.0, then make sure that you download the scgi-1.2a1 (or newer) version of SCGI. And, if you do use it, please report back to the Quixote email list, so the Quixote people will know about whether it is stable or not. The version with support for Apache 2.0 is here: http://www.mems-exchange.org/software/files/scgi/. And, here is the announcement and some notes:

3   Installation and Setup

3.1   Install Quixote

I'll assume that you have installed Quixote.

3.2   Download and install SCGI

You can find at http://www.mems-exchange.org/software/scgi/. After downloading and unrolling the distribution file, change to the SCGI directory and do:

python setup.py build
python setup.py install     # as root

The above installs mod_scgi.so in your Python site-packages directory. If you prefer it in some other location, you can either (1) copy it there or (2) consider using the Makefile.

3.3   Configure Apache

You need to tell the Apache Web server that requests to a specific port and URI are to be processed by forwarding those requests to the SCGI server. Here is a stanza that will do so for the path "/". You can add this to the end of your Apache configuration file. On my Linux machine it is at /etc/apache/httpd.conf:

LoadModule scgi_module /usr/local/lib/python2.3/site-packages/mod_scgi.so
<Location "/">
    SCGIServer 127.0.0.1 3001
    SCGIHandler On
</Location>

The above tells Apache the following:

  • Load the SCGI module. And, the LoadModule directive also tells Apache where to find it.
  • Any requests that are received with a URI whose path is "/" are to be processed by forwarding those requests to a particular SCGI server -- namely, your Quixote application. Your Quixote application will be running as an SCGI server, listening on port 3001.

You will find more examples in the README file that comes with the SCGI distribution. That README is also here: http://www.mems-exchange.org/software/files/scgi/scgi-1.1.tar.gz/README

You can also add a path to the location directive. If you do, I believe that you also need to add the same path to the prefix in your SCGI startup/driver script. (If someone can explain this to me, I'd appreciate it.

Apache 2.0 -- It has been reported that with Apache 2.0, you will need to add the following:

SetHandler scgi-handler

I'm using Apache 1.3, so I can't check that.

3.4   Restart Apache

So that your changes to the Apache configuration file (httpd.conf) will take effect, you will need to restart Apache. On my Linux box, the following (as root) does this:

/etc/init.d/apache restart

3.5   Start the SCGI server

In our case, we will assume that the SCGI server will be listening on port 3001. Here is a script that I use to start my application.

Note: You will need to add the directory containing your application (in the example below, test2.ui) to your PYTHONPATH before running the following code.

server-scgi.py:

#!/usr/bin/env python

from scgi.quixote_handler import QuixoteHandler, main
from quixote.publish import Publisher

from quixote import enable_ptl
enable_ptl()

class MyAppHandler(QuixoteHandler):
    publisher_class = Publisher
    root_namespace = "test2.ui"
    prefix = ""

if __name__ == '__main__':
    main(MyAppHandler)

Some explanation:

  • I added the directory containing test2.ui to my PYTHONPATH before running the above code.
  • I wanted to use PTL in my Quixote application, so I've called enable_ptl().
  • You need to ensure that the packages and modules that make up your Quixote application can be imported. If your root namespace is the package 'test.ui', which lives in 'somedir/test/ui/__init__.py', then you need to make sure that 'somedir' is in 'sys.path' by the time you call 'scgi.quixote_handler.main()'.

And, you can start this driver script as follows:

./server-scgi.py -p 3001 -l tmp.log

Notice that although the above driver script ignores all command-line arguments, scgi.quixote_handler.main() parses command-line options like '-p' and '-l'. In this case, these options tell the SCGI server:

  • To listen on port 3001 and
  • To write log messages to the file tmp.log.

3.5.1   Command line options for SCGI

SCGI handler has some additional options. There is a more complete list:

-F stay in foreground (don't fork)
-P PID filename
-l log filename
-m max children
-p TCP port to listen on
-u user id to run under

4   Changing Your Quixote Application

Each time you make changes to your Quixote application, you must restart the SCGI server in order to see those changes. (But, you will not have to restart Apache.) For reference, here are the scripts that I use to start, restart, and stop my SCGI server.

start:

#!/bin/sh -v
./server-scgi.py -p 3001 -l tmp.log

restart:

#!/bin/sh -v
kill -HUP `cat /var/tmp/quixote-scgi.pid`

stop:

#!/bin/sh -v
kill `cat /var/tmp/quixote-scgi.pid`

5   Where To Go From Here

OK, that was the easy part. Now for the big job. Write and test your Quixote application.

6   See Also

http://www.mems-exchange.org/software/quixote/: The Quixote support Web site.

Web Server Configuration for Quixote: This document has a section on using SCGI with Quixote.

SCGI: The SCGI Web site at Mems-exchange.

http://python.ca/nas/scgi/protocol.txt: Details on the SCGI protocol.

White Paper: Quixote for Web Development: This white paper has a helpful graphic that shows the relationship between (1) the HTTP client, (2) Apache and the mod_scgi, and (3) the Quixote application receiving its requests from mod_scgi.

Python home: The Python Web site.

Docutils: Python Documentation Utilities -- This document was formatted with Docutils.