===================
Welcome to MOD_WSGI
===================

Copyright 2007-2009 GRAHAM DUMPLETON

The mod_wsgi adapter is an Apache module that provides a WSGI compliant
interface for hosting Python based web applications within Apache. The
adapter is written completely in C code against the Apache C runtime and
for hosting WSGI applications within Apache has a lower overhead than using
existing WSGI adapters for mod_python or CGI.

The package can be compiled for and used with either Apache 1.3, 2.0 or 2.2.
On UNIX systems, either the single threaded 'prefork' or multithreaded
'worker' Apache MPMs can be used.

Note that 'daemon' mode of mod_wsgi is only available if Apache 2.0 or 2.2
is being used on a UNIX platform and where the Apache run time library
has been compiled with support for multithreading. Generally multithreading
support is standard except for on some BSD variants.

Whatever version of Python is used, it must also have been compiled with
support for multithreading. To avoid a measure of memory bloat with your
Apache processes, Python should also have been compiled with shared library
support enabled. A number of Python binary packages for Linux systems are
not compiled with shared library support enabled. You should therefore
consider recompiling Python from source code with shared library support
enabled. If a shared library is not used, you will have problems trying
to use mod_wsgi on a server where mod_python is also being loaded.

If using a Python binary package for a Linux system, also ensure that the
you have the corresponding 'dev' package installed for the Python package
you have installed. Without this package you will be missing the Python
header files and configuration files need to build mod_wsgi. You should
also ensure you have the corresponding 'dev' package for the Apache web
server package you are using.

At this time only build scripts for UNIX systems are supplied. The code
should still work on Windows, but still waiting for someone to volunteer
to help develop and test some build scripts for Windows and ensure that
mod_wsgi works on that platform.

The source code in this package is made available under the terms of the
Apache Licence, Version 2.0. See the "LICENCE" file for more information.


Documentation
=============

Note that this README only covers installation and configuration for a
basic WSGI application in 'embedded' mode. For a more detailed explanation
of how to use mod_wsgi, consult the documentation found at:

    http://www.modwsgi.org

In particular, refer to the installation and configuration information in
the following documentation:

    http://code.google.com/p/modwsgi/wiki/InstallationInstructions
    http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines

If you experience any sort of problems in installing and getting mod_wsgi
to work, or your WSGI application appears to not work properly, ensure you
also read:

    http://code.google.com/p/modwsgi/wiki/InstallationIssues
    http://code.google.com/p/modwsgi/wiki/ConfigurationIssues
    http://code.google.com/p/modwsgi/wiki/ApplicationIssues
    http://code.google.com/p/modwsgi/wiki/DebuggingTechniques

If you have questions specifically about mod_wsgi and its configuration and
use, use the Google discussion group at:

    http://groups.google.com/group/modwsgi

In the first instance it is highly recommended that you come to the
mod_wsgi group even when sorting out problems related to running some third
party package on top of mod_wsgi. This is because people on other support
forums are not going to necessarily have the knowledge to help you.

If your questions are perhaps more about WSGI in general, you can also use
the Python Web-SIG or comp.lang.python USENET groups to get further
information:

    http://groups.google.com/group/python-web-sig
    http://groups.google.com/group/comp.lang.python


Installation (UNIX)
===================

To setup the package ready for building run the "configure" script.

    ./configure

The configure script will attempt to identify the Apache installation to
use by searching for either the "apxs2" or "apxs" tools included with your
Apache installation. Similarly, which Python installation to use will be
determined by looking for the "python" executable.

If using a Linux system and you do not have the appropriate Apache "dev"
package installed, then "apxs" will not be able to be found when
"configure" is run. Also ensure that you have installed the correct "dev"
package for the version of Apache being used. For most Linux distributions,
the "dev" package for Apache 2 is "apache2-dev" where the corresponding
Apache package was "apache2". Some systems however distinguish the "dev"
package based on which MPM is used by Apache. As such, it may also be
called "apache2-worker-dev" or "apache2-prefork-dev". If using Apache 2,
do not mix things up and install "apache-dev" by mistake, which is the
"dev" package for Apache 1.3 called just "apache".

If these programs are not in a standard location, they cannot be found in
your PATH, or you wish to use alternate versions to those found, the
"--with-apxs" and "--with-python" options can be used in conjunction with the
"configure" script.

    ./configure --with-apxs=/usr/local/apache/bin/apxs \
      --with-python=/usr/local/bin/python

If using SUSE Linux, it will be necessary to use the "--with-apxs" option
and specify either "/usr/sbin/apxs2-worker" or "/usr/sbin/apxs2-prefork".
This is necessary as SUSE Linux allows installation of "dev" package for
both Apache MPM variants at the same time, whereas other Linux
distributions do not. Although mod_wsgi when compiled isn't specific to
either the worker or prefork MPMs, it does include the MPM specific header
file to access information about default listener socket locking mechanism
as used my multiprocess server configuration. Thus, if one of the MPM
specific versions of "apxs2" is not used, compilation will fail due to not
being able to find the "mpm.h" header file.

Note that any of the major Apache versions should be able to be used, ie.,
all of Apache 1.3, 2.0 and 2.2 should be compatible with this package. You
will however need to compile the package separately against each version
and use the resultant Apache module only with the version it was compiled
for. Which ever version of Apache is used however, it must support dynamic
loading of Apache modules.

If you have multiple versions of Python installed and you are not using
that which is the default, you may have to organise that the PATH inherited
by the Apache application when run will result in Apache finding the
alternate version. Alternatively, the WSGIPythonHome directive should
be used to specify the exact location of the Python installation
corresponding to the version of Python compiled against. If this is not
done, the version of Python running within Apache may attempt to use the
Python modules from the wrong version of Python.

Also note that the Apache module will be bound to the specific major/minor
version of Python being used. If you ever upgrade to a newer version of
Python, you will need to rebuild the mod_wsgi module.

Once the package has been configured, it can be built by running:

    make

The only product of the build process that needs to be installed is the
Apache module itself. There are no separate Python code files as everything
is done within C code compiled into the Apache module.

To install the Apache module into the standard location for Apache modules
as dictated by Apache for your installation, run:

    make install

Installation should be done as the root user if appropriate.

If you want to install the Apache module in a non standard location
dictated by how your operating system distribution structures the
configuration files and modules for Apache, you will need to copy the file
manually into place.

If you are using Apache 1.3 the compiled Apache module can be found in the
same directory as this "README" file and is called "mod_wsgi.so". If you
are using Apache 2.X the compiled Apache module can be found in the ".libs"
subdirectory and is again called "mod_wsgi.so". The name of the file should
be kept the same when copied into its appropriate location.

To cleanup after installation, run:

    make clean

If you need to build the module for a different version of Apache, you
should run:

    make distclean

and then rerun "configure" against the alternate version of Apache before
attempting to run "make" again.


Apache Configuration
====================

Once the Apache module has been installed into your Apache installation's
module directory, it is still necessary to configure Apache to actually
load the module.

Exactly how this is done and in which of the main Apache configuration
files it should be placed, is dependent on which version of Apache you are
using and may also be influenced by how your operating system's Apache
distribution has organised the Apache configuration files. You may
therefore need to check with any documentation for your operating system to
see in what way the procedure may need to be modified.

In the simplest case, all that is required is to add a line of the form:

    LoadModule wsgi_module modules/mod_wsgi.so

into the main Apache "httpd.conf" configuration file at the same point that
other Apache modules are being loaded. The last option to the directive
should either be an absolute path to where the mod_wsgi module file is
located, or a path expressed relative to the root of your Apache
installation. If you used "make" to install the package, see where it
copied the file to work out what to set this value to.

With Apache 1.3, it would also be necessary to add a line of the form:

    AddModule mod_wsgi.c

For Apache 1.3, the LoadModule and AddModule lines related to mod_wsgi
must appear prior to those for the Apache code module called mod_alias. 

If you wish to use mod_python at the same time as mod_wsgi, then mod_python
must be compiled against the same version of Python. In addition to the
same version of Python being used, you should use a version of Python which
has been configured and compiled so as to generate a shared library for
Python. If you do not do this and either mod_python or mod_wsgi are
compiled against a static library for Python, it is likely that either
mod_python or mod_wsgi will crash Apache when used.

Note that this is not the fault of either mod_python or mod_wsgi but arises
purely because your Python installation isn't using a shared library for
the Python library. The result of such a configuration means that there are
actually two copies of the Python static library objects in memory at the
same time and this can cause problems. Linux distributions where this is
known to be a problem are any of the RedHat derived distributions. Other
distributions such as Ubuntu do not have a problem as they use a shared
library for the Python library.

Having adding the required directives you should perform a restart of
Apache to check everything is okay.

    apachectl restart

If you see any sort of problem, or if you are upgrading from an older
version of mod_wsgi, it is recommended you actually stop/start Apache
instead.

    apachectl stop
    apachectl start

Note that on some Linux systems using 'apachectl' may not work properly.
On these systems, if you have problems using 'apachectl' ensure instead
you use the init.d script for Apache instead.

    /etc/init.d/httpd stop
    /etc/init.d/httpd start

The init.d script may be called 'apache2'. Similarly, the 'apachectl'
script may even be called 'apachectl2' on some systems where they allow
both Apache 1.3 and Apache 2.X to be installed at the same time.

In general, for any system where you are using a prepackaged version of
Apache, it is wise to always check the documentation for that package or
system to determine the correct way to stop/start the Apache service. This
is because they often use a wrapper around 'apachectl', or replace it, with
a script which performs additional actions.

If all is okay, you should see a line of the form:

    Apache/2.2.2 (Unix) mod_wsgi/1.0 Python/2.3.5 configured

in the Apache error log file.

If Apache is configured to also load mod_python, it would instead be:

    Apache/2.2.2 (Unix) mod_python/3.3.1 Python/2.3.5 mod_wsgi/1.0 configured

That "Python" is listed before "mod_wsgi" is indicative of the fact that
when both modules are being loaded, mod_wsgi will leave it up to mod_python
to initialise Python.

Note that mod_wsgi logs various detailed information about interpreter
creation, script loading and reloading etc, but it logs with log level of
'info'. As the default for the Apache LogLevel directive is usually 'warn',
such information will not be displayed in the Apache error log file. If you
are new to mod_wsgi or need to debug issues with its use, it is recommended
to change the Apache LogLevel directive to 'info' so that the information
is displayed. For example:

  LogLevel info

If only wishing to enable this level of log information for a single
VirtualHost this can be done by specifying the directive in the context of
the VirtualHost container, but by doing so, only the more detailed
information which is specific to a request against that virtual host will
be output.


Enabling WSGI Application
=========================

The mechanisms used to configure mod_wsgi are similar to that used by the
Apache mod_cgi module to enable traditional CGI scripts.

For example, whereas mod_cgi has the ScriptAlias directive, mod_wsgi has
the WSGIScriptAlias directive. Like with mod_cgi, this directive can only
appear in the main Apache configuration files. The directive would be used
at server scope or within the VirtualHost container and cannot be used
within either of the Location, Directory or Files container directives,
neither can it be used within a ".htaccess" files.

The first way of using the WSGIScriptAlias directive to indicate the WSGI
application to be used, is to associate a WSGI application against a specific
URL prefix.

    WSGIScriptAlias /myapp /usr/local/wsgi/scripts/myapp.wsgi

The last option to the directive in this case must be a full pathname to
the actual code file containing the WSGI application. The WSGI application
contained within the code file should be called "application". For example:

    def application(environ, start_response):
        status = '200 OK'
        output = 'Hello World!'

        response_headers = [('Content-type', 'text/plain'),
                            ('Content-Length', str(len(output)))]
        start_response(status, response_headers)

        return [output]

Note that an absolute pathname must be used. It is not possible to specify
an application by Python module name alone. A full path is used for a
number of reasons, the main one being so that all the Apache access
controls can still be applied to indicate who can actually access the WSGI
application. Because these access controls will apply, if the WSGI
application is located outside of any directories already known to Apache,
it will be necessary to tell Apache that files within that directory can be
used. To do this the Directory directive must be used.

    <Directory /usr/local/wsgi/scripts>
    Order allow,deny
    Allow from all
    </Directory>

The second way of using the WSGIScriptAlias directive is to use it to map
to a directory containing any number of WSGI applications.

    WSGIScriptAlias /wsgi/ /usr/local/wsgi/scripts/

When this is used, the next part of the URL after the URL prefix is used
to identify which WSGI application code file within the target directory
should be used.

Note that by default each application is placed into its own distinct
application group. This means that each application will be given its own
distinct Python sub interpreter to run code within. Although this means
that applications will be isolated and cannot interfere with the Python code
components of each other, each will load its own copy of all Python modules
it requires into memory. If you have many applications and they use a lot
of different Python modules this can result in large process sizes.

To avoid large process sizes, if you know that applications within a
directory can safely coexist and run together within the same Python sub
interpreter, you can specify that all applications within a certain context
should be placed in the same application group. This is indicated by using
the WSGIApplicationGroup directive. The argument to the directive can be
any unique name of your choosing.

    <Directory /usr/local/wsgi/scripts>
    WSGIApplicationGroup admin-scripts
    Order allow,deny
    Allow from all
    </Directory>

The above only begins to describe the different ways in which mod_wsgi can
be enabled for use. It does not cover running an application in 'daemon'
mode not issues such as reloading of application script files, additional
means of managing Python sub interpreters, or how to supply configuration
information to WSGI applications. Thus, please ensure you refer to the
documentation on the mod_wsgi web site for further information.


Enjoy

Graham Dumpleton