Introduction

This is a basic description of how to get Paste WebKit installed and working. It is not a tutorial (see the Todo Tutorial for now -- but note the installation instructions here differ from that document).

Installation

To install, first get easy_install. Currently, as not all prerequisites are fully packaged, do:

$ easy_install.py http://svn.pythonpaste.org/Paste/branches/mainline-refactor
$ easy_install.py http://svn.pythonpaste.org/Paste/WebKit/trunk

You may need to run these as root. The second command should install Paste Deployment on its own.

Configuration

This uses Paste Deploy, so to configure your application write a .ini file like:

[app:main]
use = egg:PasteWebKit
package_name = mypackage
myconfig_var = foo1

There are several configuration keys WebKit uses. The first are to find your application; you can use one of these:

servlet_directory:

The directory where you've put your servlets. You can use %(here)s to refer to the directory that contains the configuration file.

package_name:

The package for your application. Servlets are expected in a web subpackage. So if you give mypackage it will look in mypackage.web for the servlets.

The other keys configure various filters/middleware:

complete_stack (default true):

If false, then none of the middleware will be installed. This may be useful if you are nesting one WebKit app inside another (and don't want to duplicate the stack).

debug (default false):

This controls a number of settings. Mostly errors will be displayed in the browser with this on. It is also picked up from the global debug setting if not given.

Also, with this on, the printdebug filter will be installed, which catches all print statements and shows them in a <pre> in each response page.

cookie_name (default _SID_ -- for session):

The cookie name the session will use.

session_file_path (default /tmp):

Where the session files are kept.

error_email (default: none):

Any email addresses that should be used when reporting errors. Adding emails here will enable this feature. Use spaces to separate multiple addresses.

If you don't give this in the application section, the keys error_email or sysadmin_email (in that order) will be pulled from te global configuration ([DEFAULTS]).

error_log (default: none):

A file to append to with error reports.

show_exceptions_in_wsgi_errors (default: not debug):

If true then errors will show up in the server error logs. Where this goes depends on the server. If debug is on, this defaults to off, and vice versa.

from_address (default: errors@localhost):

What address errors appear to come from.

smtp_server (default: localhost):

The SMTP server (for sending errors).

error_subject_prefix (default: [app_name]):

The prefix to put on error email subjects. If an app_name is given (globally or locally) then that will be used.

error_message (default: none):

Extra text to use in error messages presented to users (when debug mode is off)

profile (default: false):

If on, then all requests will be profiled. This slows down the app considerable, so absolutely don't use it except in development.

profile_limit (default: 40):

Show the top N slowest parts of the system.

All other configuration keys will be sent to the application. So in the example myconfig_var would be application configuration.

Applications can access this information like:

from paste.deploy import CONFIG

def my_routine():
    var = CONFIG['myconfig_var']

The CONFIG variable dispatches to the configuration for the current request, whatever that request might be. This means you can't use it at the module-level, because modules are loaded once, before any per-request configuration is available.

Deploying an Application

Once you've configured your application, you use Paste Deploy to create a WSGI application. WSGI applications can be used by many servers.

To get an application you do:

from paste.deploy import loadapp

wsgi_app = loadapp('config:myconfig_file.ini',
                   relative_to=config_dir)

This loads the app described by app:main from the configuration file. You can give config:/absolute_path, or use relative_to to allow relative paths.

You can also run the server with PasteScript. Add a [server:main] section to your configuration, like:

[server:main]
# this is a good testing server:
use = egg:PasteScript#wsgiutils
host = 127.0.0.1
port = 8080

And then use paster serve --reload path/to/conf.ini. The --reload option causes the server to restart when files are edited (this is kind of expensive, so should only be used during development).