Installation

For installation on Windows, click here.

The installation involves the following steps:

• 1. Prerequisites
• 2. Compiling
  • Run ./configure.
  • Run make
• 3. Installing
• 4. Configuring Apache
• 5. Testing
• 6. Troubleshooting

1. Prerequisites

• Python 1.5.2 or 1.6 (2.0 reportedly works as well)
• Apache 1.3 (1.3.12 or higher recommended)

You will need to have the include files for both Apache and Python, as well as the Python library installed on your system. If you installed Python and Apache from source, then you have nothing to worry about. However, if you are using prepackaged software (e.g. Linux Red Hat RPM, Debian, or Solaris packages from sunsite, etc) then chances are, you just have the binaries and not the sources on your system. Often, the include files and the libraries are part of separate "development" package. If you are not sure whether you have all the necessary files, either compile and install Python and Apache from source, or refer to the documentation for your system on how to get the development packages.

2. Compiling

There are two ways that this module can be compiled and linked to Apache - statically, or as a DSO (Dynamic Shared Object).

Static linking is a more "traditional" approach, and most programmers prefer it for its simplicity. The drawback is that it entails recompiling Apache, which some people cannot do for a variety of reasons. For example in a shared web hosting environment the Apache binary might not be writable by the user.

Dynamic Shared Object (DSO) is a newer and still somewhat experimental approach. The module gets compiled as a library that is dynamically loaded by the server at run time. A more detailed description of the Apache DSO mechanism is available here.

The advantage is that a module can be installed without recompiling Apache and used as needed. DSO has its disadvantages, however. Compiling a module like mod_python into a DSO can be a complicated process because Python, depending on configuration, may rely on a number of other libraries, and you need to make sure that the DSO is statically linked against each of them. Luckely, the configure script below will solve this headache for you by automatically figuring out all the necessary parameters.

Run ./configure

The ./configure script will analyze your environment and create custom Makefiles particular to your system. Aside from all the standard autoconf stuff, ./configure does the following:

• Finds out whether a program called apxs is available. This program is part of the standard Apache distribution, and is necessary for DSO compilation. If apxs cannot be found in your PATH or in /usr/local/apache/bin, DSO compilation will not be availale.

  You can manually specify the location of apxs by using the --with-apxs option, e.g.:

              $ ./configure --with-apxs=/usr/local/apache/bin/apxs

• Checks for --with-apache option. Use this option to tell where the Apache sources are on your system. The Apache sources are necessary for static compilation. If you do not specify this options, static compilation will not be available. Here is an example:

              $ ./configure --with-apache=../src/apache_1.3.12 --with-apxs=/usr/local/apache/bin/apxs

• Checks your Python version and attempt to figure out where libpython is by looking at various parameters compiled into your Python binary. By default, it will use the python program found in your PATH.

  If the Python installation on your system is not suitable for mod_python (which can be the case if Python is compiled with thread support), you can specify an alternative location with the --with-python options. This options needs to point to the root directory of the Python source, e.g.:

                $ ./configure --with-python=/usr/local/src/Python-1.5.2
  	  

  Note that the directory needs to contain already configured and compiled Python. In other words, you must at least run ./configure and make.

Run make

• If possible, the ./configure script will default to dso compilation, otherwise, it will default to static. To stay with whatever ./configure decided, simply run

            $ make
        

  Or, if you would like to be specific, give make a dso or static target:

            $ make dso
         OR
            $ make static
        

3. Installing

• This part of the installation needs to be done as root.

              $ su
              # make install
  	  

  • For DSO, this will simply copy the library into your Apache libexec directory, where all the other modules are.
  • For static, it will copy some files into your Apache source tree.
  • Lastly, it will install the Python libraries in site-packages and compile them.

4. Configuring Apache

• To configure Apache for mod_python:
  • If you compiled mod_python as a DSO, you will need to tell Apache to load the module by adding the following line in the Apache configuration file, usually called httpd.conf or apache.conf:

          LoadModule python_module libexec/mod_python.so

    The actual path to mod_python.so may vary, but make install should report at the very end exactly where mod_python.so was placed and how the LoadModule directive should appear.

    If your Apache configuration uses ClearModuleList directive, you will need to add mod_python to the module list in the Apache configuration file:

          AddModule mod_python.c

    NB: Some (not all) RedHat Linux users reported that mod_python needs to be first in the module list, or Apache will crash.

  • If you used the static installation, you now need to recompile Apache:

                $ cd ../src/apache_1.3.12
                $ ./configure --activate-module=src/modules/python/libpython.a
                $ make
              

    Or, if you prefer the old "Configure" style, edit src/Configuration to have

                AddModule modules/python/libpython.a"
    	  

    then run

                $ cd src
                $ ./Configure
                $ make
    	  

5. Testing

• Make some directory that would be visible on your website, for example, htdocs/test.

• Add the following Apache directives, which can appear in either the main server configuration file, or .htaccess. If you are going to be using the .htaccess file, you will not need the <Directory> tag below, and you will need to make sure the AllowOverride directive applicable to this directory has at least FileInfo specified. The default is None, which will not work.

        <Directory /some/directory/htdocs/test>
            AddHandler python-program .py
            PythonHandler mptest
            PythonDebug On
        </Directory>

  (Substitute /some/directory above for somethng applicable to your system, usually your Apache server root)

• At this time, if you made changes to the main configuration file, you will need to restart Apache in order for the changes to take effect.

• Edit mptest.py file in the htdocs/test directory so that is has the following lines (Be careful when cutting and pasting from your browser, you may end up with incorrect indentation and a syntax error):

        from mod_python import apache
  
        def handler(req):
            req.send_http_header()
            req.write("Hello World!")
            return apache.OK 

• Point your browser to the URL referring to the mptest.py, you should see "Hellow World!". If you didn't - refer to the troubleshooting step next.

If everything worked well, move on to the tutorial.

6. Troubleshooting

There are a couple things you can try to identify the problem:

• Carefully study the error output, if any.
• Check the error_log file, it may contain useful clues.
• Try running Apache from the command line with an -X argument:

        ./httpd -X

  This prevents it from backgrounding itself and may provide some useful information.
• Ask on the mod_python list. Make sure to provide specifics such as:
  . Your operating system type, name and version.
  . Your Python version, and any unusual compilation options.
  . Your Apache version.
  . Relevant parts of the Apache config, .htaccess.
  . Relevant parts of the Python code.