# Paste WebKit

Author: | Ian Bicking <ianb@colorstudy.com>
Revision: | 3287
Date: | 2005-09-26 12:08:24 -0500 (Mon, 26 Sep 2005)

Contents

- Introduction
- Installation
- Configuration
- Deploying an Application

# 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).