This is QP, a package for defining and running multiple web
applications based on Durus for persistence, standard persistent
Session and User classes, easy interactive database sessions, qpy for
assembling html, and Quixote2-style forms and path traversal.  QP
makes it easier than ever to use these tools together.

QP includes a http/scgi server that dispatches requests to
a pool of long-running single-threaded worker processes.
With QP your applications can
  1) use the QP http service directly,
  2) use the QP http service through a proxy,
  3) use the QP scgi service through Apache+mod_scgi or lighttpd,
  4) use the QP scgi service through CGI, using the (included)
     cgi2scgi adapter and any cgi-capable web server.

QP includes a site-management capability similar to the one in
Dulcinea.  One command line utility (named "qp") is used for 
controlling all of the servers for multiple sites.

QP's servers run best when the passfd extension module is installed,
but the passfd extension module does not work on Windows.  On systems
where passfd is not available, the servers still run, but requests are
handled serially.


QUICK START
-----------

Install Python 2.4 or above.

To be as explicit as possible, I'll write the installation procedure here
as if it were a script.

    # Download and unpack the distributions.
    wget http://www.mems-exchange.org/software/files/durus/Durus-3.5.tar.gz
    wget http://www.mems-exchange.org/software/files/qpy/qpy-1.4.tar.gz
    wget http://www.mems-exchange.org/software/files/qp/qp-1.8.tar.gz
    tar xzf Durus-3.5.tar.gz
    tar xzf qpy-1.4.tar.gz
    tar xzf qp-1.8.tar.gz

    # Install the packages
    cd Durus-3.5; sudo python setup.py install
    cd ../qpy-1.4; sudo python setup.py install
    cd ../qp-1.8; sudo python setup.py install

    # Make sure that the installed .qpy files are compiled.
    sudo python -c "import qp.fill"

    # Copy the demo sites from the distribution to your ~/qp_sites directory.
    python setup.py install_demo_sites ~/qp_sites

    # Put a symlink to ~/qp_sites in the installed qp package.
    sudo python setup.py install_sites_link ~/qp_sites
    

The installation is now complete.

Run the command "qp start".  This will start three demo web servers on:
http://localhost:8000
http://localhost:8001
http://localhost:8002
Look at them in your browser.  Run "qp stop" when you want to stop them.

Run "qp --help" to see the options available for the qp command.


USING QP
--------

Define your sites by editing the qp.sites package, adding a sub-package
for each site you want to run.  The distribution provides three example
sites:  hello, echo, and proto.  A site named 'mine' is expected to
have:
    1) a package named 'mine' in the qp/sites directory.
    2) a 'var' directory in qp/sites/mine for the database and log files.
    3) 'SitePublisher' and 'SiteDirectory' classes available for 
       import from qp.sites.mine.slash .

The SitePublisher class should be a subclass of qp.pub.publish.Publisher,
with a 'configuration' class attribute identifying addresses for the
servers you want to run.

The SiteDirectory class should be a subclass of qp.fill.directory.Directory
that defines your site's content.

Use the 'qp' command to run your sites.  Run 'qp --help' for a full usage
description.


OTHER HELPFUL PACKAGES
----------------------

The qp command has an interaction option that offers an interactive
python session that is connected to the database of one of your sites.
This option doesn't work unless you install Michael Hudson's pyrepl
package, available from http://codespeak.net/pyrepl/.  Once you have
used the interactive features provided by pyrepl, it is hard to live
without them.  The install is very simple: "python setup.py install".

The qp package includes unit tests in test subdirectories.  The tests
are written using the very minimalistic testing framework called
Sancho.  If, for some reason, you want to run the unit tests, you'll
need to install Sancho-2.1:
http://www.mems-exchange.org/software/sancho/.

If you want to use QP's web service with https, you will probably want
to install either stunnel (http://stunnel.org/) or Apache
(http://apache.org).


HTTPS
-----

QP does *not* provide ssl service, but your QP applications can
have https support by using 

  1) QP's scgi server along with a separate server that provides https 
     and scgi (such as Apache + mod_scgi),
  2) QP's http server along with an ssl-providing http proxy, or
  3) QP's http server along with stunnel.  

The stunnel method is relatively simple.  You just install stunnel
(available from www.stunnel.org) and configure it to run in server
mode and to accept connections on the public (https_address) interface
and forward them to the port on the local (as_https_address) interface.
The 'echo' site in the distribution, for example, provides the
'as_https' server on localhost port 9001.  If you set stunnel to
accept connections on <yourhost> port 10001 and forward them to
localhost port 9001, then clients can connect to
https://<yourhost>:10001.  


Quick-start stunnel on Debian Linux.
------------------------------------

# The details will be slightly different on Mac OS X or other systems,
# but here are detailed notes for Debian Linux.
apt-get install stunnel4
# "stunnel4 -version" reports 4.09 as I am testing this.
openssl req -new -x509 -nodes -days 365 \
  -out /etc/stunnel/stunnel.pem -keyout /etc/stunnel/stunnel.pem
# answer the questions.  
chown stunnel4 /etc/stunnel/stunnel.pem
chmod 600 /etc/stunnel/stunnel.pem
# Now /etc/stunnel/stunnel.pem can be used as a default.
# Note that this is unverifiable, and therefore inappropriate
# for many applications.  You may need to get a signed certificate.
# See OpenSSL docs for more information about this.
edit /etc/stunnel/stunnel.conf:
Set "cert = /etc/stunnel/stunnel.pem"
Set "client = no"
Comment out debug, output, and all of the lines after
  "; Service-level configuration".
Append the following: """

[hello]
accept = 10000
connect = 9000
TIMEOUTclose = 0

[echo]
accept = 10001
connect = 9001
TIMEOUTclose = 0

[proto]
accept = 10002
connect = 9002
TIMEOUTclose = 0
"""
Edit /etc/default/stunnel4, setting "ENABLED=1". 
Run "/etc/init.d/stunnel4 start"
Now you should be able to load, for example,
https://localhost:10001/


QP with Apache + mod_scgi
-----------------------

You can also use Apache with QP.  This provides an alternative way to
support SSL connections.  Do do that, omit the "http_address" and 
"as_http_address" keys from your site's Publisher configuration dictionary.
(You should leave the "https_address" key in the configuration.  It is 
needed when applications want to http connections to the https port.)
That way, the QP site management tool won't start QP's own http server.
You'll also need the apache modules mod_scgi and ssl_module installed,
and configuration directives something like the following (for Apache 1).

    Listen 80
    Listen 443
    <VirtualHost 0:80> 
    ServerName www.example.org
    SCGIMount / 127.0.0.1:9000
    </VirtualHost>

    <VirtualHost 0:443>
    ServerName www.example.org
    SCGIMount / 127.0.0.1:9000
    SSLEngine on
    SSLOptions +StdEnvVars
    SSLCertificateFile /my/ssl/server.crt
    SSLCertificateKeyFile /my/ssl/server.key
    </VirtualHost>


QP
--

The abbreviation "qp" stands for "quantum placet", the Latin phrase
meaning "as much as you please".

Copyright
---------

Copyright (c) Corporation for National Research Initiatives 2006.
